PHP Classes

Zephir HandlerSocket Client: Access MySQL tables as NoSQL with HandlerSocket

Recommend this page to a friend!
  Info   View files Documentation   View files View files (40)   DownloadInstall with Composer Download .zip   Reputation   Support forum   Blog    
Ratings Unique User Downloads Download Rankings
StarStarStarStar 74%Total: 157 This week: 1All time: 8,999 This week: 560Up
Version License PHP version Categories
zhandlesocket 1.0.5MIT/X Consortium ...5Networking, Zephir
Description 

Author

This package can access MySQL tables as NoSQL with HandlerSocket.

It provides classes written in Zephir to access MySQL INNODB tables using a noSQL interface provided by Percone HandlerSocker MySQL plugin.

The connection class establishes a TCP connection with the HandlerSocker server on a given host and port.

Other packages can perform queries for retrieving, storing and deleting rows on a given table.

Innovation Award
PHP Programming Innovation award nominee
June 2016
Number 2


Prize: One subscription to the PDF edition of the PHP Architect magazine
Zephir is a statically typed language derived from PHP that can be compiled into native PHP extensions which can run along with PHP code based on the Zend Engine.

The HandlerSocket Client package is written in Zephir and is able to connect to a MySQL database server and treat INNODB tables as NoSQL databases, thus allowing PHP developers to take advantage of both worlds in the same application: the world of transactional databases with regular SQL and the world of NoSQL databases.

Manuel Lemos
Picture of Victor Bolshov
  Performance   Level  
Name: Victor Bolshov <contact>
Classes: 10 packages by
Country: Russian Federation Russian Federation
Age: 45
All time rank: 42211 in Russian Federation Russian Federation
Week rank: 416 Up24 in Russian Federation Russian Federation Down
Innovation award
Innovation award
Nominee: 2x

Documentation

zhandlersocket

Another PHP extension for communicating with handlersocket. Built with Zephir: https://github.com/phalcon/zephir. Thus, you will have to install Zephir first to build zhandlersocket. Once you have Zephir installed and cloned the zhandlersocket repo:

cd <zhandlersocket directory>
zephir build

After that, under _ext/modules_ you will find the zhandlersocket.so. Copy it to your PHP's extension_dir, add "extension=zhandlersocket.so" to your php.ini and restart your web-server. Check with the following command if zhandlersocket is there:

php -m

The output should, among other lines, contain "zhandlersocket".

Short example

use \Zhandlersocket\Client;

$client = new Client();// create a HS client with default connection parameters

$index = $client->getIndex("test", "my_table", "PRIMARY", ["id", "name"]);

// find() would return an array of rows, because an index is not always unique
// In this case, we know there will be 1 or 0 rows with ID=10, so we use findFirst(),
// which will fetch the very first row and return it
$row = $index->findFirst(10);

// Update a row:
$upd = $index->updateById(10, ["id" => 10, "name" => "New name"]);// have to specify ALL columns

A closer look

HandlerSocket enables you to use InnoDB table in a NoSQL way. HS performance when selecting by Primary Key is at least close to that of Memcached, and according to some benchmarks, HS is even faster. Given this, you might well give up on using Memcached in certain cases (and having all the assiciated headaches with cache invalidating).

HS operates on InnoDB indexes. That means that you always perform a query on a index. This might be the table's PRIMARY KEY but it also may be any other index you have on the table.

In order to perform queries with ZhandlerSocket, you first need to instantiate ZhandlerSocket\Client:

$client = new Client("localhost", 9998, 9999);

Above are the default connection parameters, and you could as well omit them.

When you have a Client instance, you might want to create an instance of ZhandlerSocket\Index:

$index = $client->getIndex("test", "my_table", "PRIMARY", ["id", "name"]);

This code means that you would like to speak Handlersocket with InnoDB table my_table from database test. You will perform you find queries using PRIMARY KEY, and you would like to receive in response the foloowing columns: id and name.

PRIMARY KEY is not the only capability. Suppose you have a table movie, which has fields id, genre, title, view_count. PRIMARY KEY is id but there is also a key on genre column called genre_key. Eventually, the index might well be named exactly as the column but don't be confused: when opening a HS index, you need the index name, not the column name.

$index = $client->getIndex("test", "movie", "genre_key", ["id", "genre", "title", "view_count"]);

ZhandlerSocket\Client->getIndex() method accepts an optional 5th parameter which is filter columns. This specifies columns that you want to support additional filtering for. Those do not necessarily have to be a part of index but they have to be a part of columns you chose for selection (4th argument).

Basic usage of HS is to select a row by key, update a row, delete a row. ZhandlerSocket\Index class has the following to offer for the basic find-by-key functionality:

  • find(id) - return one row with matching id. An index might consist of several columns, and HS allows you to select rows by a compound key. For this, find() supports passing array as its argument. You have to take care that values in this array come in exactly the same order as they are mentioned in the InnoDB index. The return value is an associative array with keys matching to column names you specified when calling ZhandlerSocket\Client->getIndex(). In case no matching rows found, find() will return boolean FALSE;
  • findMany(array ids[, string column = null]) - an equivalent of SQL IN clause. Attempts to find all rows with IDs from from the first argument. The match is done against the very first column passed to Client->getIndex().

However, ZhandlerSocket\Index has also more to offer. HandlerSocket provides one with robust tools for quickly finding rows in a InnoDB table. Zhandlersocket ships with WhereClause class which enables you to specify criteria you want to apply to the selection.

  • findByWhereClause() - Zhandlersocket ships with a Zhandlersocket\WhereClause class which is capable of building the HS analogue of SQL WHERE and LIMIT clause together. You can create the WhereClause instance with Index->createWhereClause(), setup your filters and LIMIT/OFFSET, then either call Index->findByWhereClause() or simply do WhereClause->find() method (which is the preferable way).

Manipulating data with ZhandlerSocket\Index:

  • insert(array values) - insert a new row. Depending on whether AUTO_INCREMENT is used, the return value differs: - integer LAST INSERT ID for AUTO_INCREMENT mode; - bool TRUE for NON-AUTO_INCREMENT mode. For AUTO_INCREMENT mode, simply pass NULL as the value for the AUTO_INCREMENT column
  • updateById(id, values) - update row identified by ID. values is an assoc {col1: val1,..}, and all the values for all columns that you used creating the index, have to be specified.
  • updateByWhereClause(<WhereClause> wc, values) - same as above but will update all the columns matching the WhereClause. Use with care and bear in mind the LIMIT that is set up in WhereClause and by default it applies a limit of 1 with offset 0, unless you have used WhereClause->setIn() or explicitly set limit with WhereClause->setLimit().
  • incrementById(id, values) - increment values in a row specified by ID. Internally, delegates to incrementByWhereClause()
  • incrementByWhereClause(<WhereClause> wc, values) - increment values in rows that match to WhereClause. Use with care and bear in mind the LIMIT that is set up in WhereClause in values. You only specify those cols that need to be incremented + the ID column(s) Internally, a new index is created containing JUST the columns to be updated, because as a result of the increment request, all participating STRING cols will be updated to "0" if you leave them there. The implementation is quite poor and a very possible subject to change. However, it seems like the HS implementation of increment is poor either. Maybe I will just have to remove its support.
  • deleteById(id) - delete a row by ID
  • function deleteByWhereClause(<WhereClause> wc) - delete rows that match WhereClause. Use with care and bear in mind the LIMIT that is set up in WhereClause.

Zhandlersocket\WhereClause short reference

WhereClause class is responsible for filtering and setting limits for selection from HS. HS is not only capable of selecting a single row by PRIMARY KEY, but also of selecting multiple rows based on criteria. Basic usage:

// We have an index on "counter" column, and we want to find up to 10 rows with counter > 20   
$index = $client->getIndex("test", "test", "counter_idx", ["id", "counter"]);
$rows = $index->createWhereClause(">", 20)->setLimit(10)->find();

You can also perform some filtering of the results with WhereClause->addFilter(). This is _post-filtering_ which occurs on the result set obtained from index. Filtering can be done on all columns specified as fcols argument whe creating the index.


  Files folder image Files  
File Role Description
Files folder imageext (1 file)
Files folder imageide (1 directory)
Files folder imagetest (7 files)
Files folder imagezhandlersocket (14 files)
Accessible without login Plain text file .gitignore Data Auxiliary data
Accessible without login Plain text file config.json Data Auxiliary data
Accessible without login Plain text file README.md Doc. Documentation

  Files folder image Files  /  ext  
File Role Description
  Accessible without login Plain text file .gitignore Data Auxiliary data

  Files folder image Files  /  ide  
File Role Description
Files folder image0.0.1 (1 directory)

  Files folder image Files  /  ide  /  0.0.1  
File Role Description
Files folder imageZhandlersocket (15 files)

  Files folder image Files  /  ide  /  0.0.1  /  Zhandlersocket  
File Role Description
  Plain text file Client.zep.php Class Class source
  Plain text file Command.zep.php Class Class source
  Plain text file CommunicationException.zep.php Class Class source
  Plain text file Connection.zep.php Class Class source
  Plain text file ConnectionException.zep.php Class Class source
  Plain text file DebugLogger.zep.php Class Class source
  Plain text file DuplicateEntryException.zep.php Class Class source
  Plain text file Encoder.zep.php Class Class source
  Plain text file Index.zep.php Class Class source
  Plain text file Log.zep.php Class Class source
  Plain text file Logger.zep.php Class Class source
  Plain text file NullLogger.zep.php Class Class source
  Plain text file WhereClause.zep.php Class Class source
  Plain text file WhereClauseFilter.zep.php Class Class source
  Plain text file ZException.zep.php Class Class source

  Files folder image Files  /  test  
File Role Description
  Accessible without login Plain text file BaseTest.php Test Test
  Accessible without login Plain text file bootstrap.php Conf. Configuration script
  Accessible without login Plain text file ClientTest.php Test Test
  Accessible without login Plain text file connect.php Conf. Configuration script
  Plain text file EncoderTest.php Class Class source
  Accessible without login Plain text file IndexTest.php Test Test
  Accessible without login Plain text file test.php Aux. Auxiliary script

  Files folder image Files  /  zhandlersocket  
File Role Description
  Plain text file Client.zep Class Class source
  Plain text file Command.zep Class Class source
  Plain text file CommunicationException.zep Class Class source
  Plain text file Connection.zep Class Class source
  Plain text file ConnectionException.zep Class Class source
  Plain text file DebugLogger.zep Class Class source
  Plain text file DuplicateEntryException.zep Class Class source
  Plain text file Encoder.zep Class Class source
  Plain text file FakeLogger.zep Class Class source
  Plain text file Index.zep Class Class source
  Plain text file Logger.zep Class Class source
  Plain text file WhereClause.zep Class Class source
  Plain text file WhereClauseFilter.zep Class Class source
  Plain text file ZException.zep Class Class source

 Version Control Unique User Downloads Download Rankings  
 100%
Total:157
This week:1
All time:8,999
This week:560Up
 User Ratings  
 
 All time
Utility:91%StarStarStarStarStar
Consistency:100%StarStarStarStarStarStar
Documentation:91%StarStarStarStarStar
Examples:-
Tests:91%StarStarStarStarStar
Videos:-
Overall:74%StarStarStarStar
Rank:108