Skip to content

Latest commit

 

History

History
117 lines (95 loc) · 5.57 KB

README.md

File metadata and controls

117 lines (95 loc) · 5.57 KB
Raw

Overview

The Aerospike HHVM client enables your PHP application to work with an Aerospike cluster as its key-value store.

The Data Model document gives further details on how data is organized in the cluster.

Client API

The Aerospike client for HHVM will eventually implement the full API described in the aerospike/aerospike-client-php repository. Currently a subset of the API has been implemented by the HNI extension.

Runtime Configuration

Aerospike Class

Lifecycle and Connection Methods

Error Handling and Logging Methods

Key-Value Methods

Query and Scan Methods

User Defined Methods

Admin Methods

Large Data Type Methods

Implementation Status

So far the Runtime Configuration, Lifecycle and Connection Methods, Error Handling and Logging Methods, and Key-Value Methods have been implemented.

Persistent Connections

Initializing the C-client to connect to a specified cluster is a costly operation, so ideally the C-client should be reused for the multiple requests made against the same PHP process (as is the case for mod_php and fastCGI).

The PHP developer can determine whether the Aerospike class constructor will use persistent connections or not by way of an optional boolean argument. After the first time Aerospike::__construct() is called within the process, the extension will attempt to reuse the persistent connection.

When persistent connections are used the methods reconnect() and close() do not actually close the connection. Those methods only apply to instances of class Aerospike which use non-persistent connections.

Halting a Stream

Halting a query() or scan() result stream can be done by returning (an explicit) boolean false from the callback. The extension will capture the return value from the registered PHP callback, and pass it to the C-client. The C-client will then close the sockets to the nodes involved in streaming results, effectively halting it.

Handling Unsupported Types

See: Data Types See: as_bytes.h

  • Allow the user to register their own serializer/deserializer method
  • OPT_SERIALIZER : SERIALIZER_PHP (default), SERIALIZER_NONE, SERIALIZER_USER
  • when a write operation runs into types that do not map directly to Aerospike DB types it checks the OPT_SERIALIZER setting:
  • if SERIALIZER_NONE it returns an Aerospike::ERR_PARAM error
  • if SERIALIZER_PHP it calls the PHP serializer, sets the object's as_bytes_type to AS_BYTES_PHP. This is the default behavior.
  • if SERIALIZER_USER it calls the PHP function the user registered a callback with Aerospike::setSerializer(), and sets as_bytes_type to AS_BYTES_BLOB
  • when a read operation extracts a value from an AS_BYTES type bin:
  • if it’s a AS_BYTES_PHP use the PHP unserialize function
  • if it’s a AS_BYTES_BLOB and the user registered a callback with Aerospike::setDeserializer() call that function, otherwise place it in a PHP string

Warning: Strings in PHP are a binary-safe structure that allows for the null-byte (\0) to be stored inside the string, not just at its end. Binary-strings with this characteristic are created by calling functions such as serialize() and gzdeflate(). As a result, the Aerospike client may truncate the resulting strings. On the Aerospike server, strings are a data type that can be queried using a secondary index, while bytes are a data type that is only used for storage. The developer should wrap binary-string with an object to distinguish them. This allows the serializer to behave in the correct manner.

Example:

require('autoload.php');
$client = new Aerospike(['hosts'=>[['addr'=>'127.0.0.1', 'port'=>3000]]]);

$str = 'Glagnar\'s Human Rinds, "It\'s a bunch\'a munch\'a crunch\'a human!';
$deflated = new \Aerospike\Bytes(gzdeflate($str));
$wrapped = new \Aerospike\Bytes("trunc\0ated");

$key = $client->initKey('test', 'demo', 'wrapped-bytes');
$status = $client->put($key, ['unwrapped'=>"trunc\0ated", 'wrapped'=> $wrapped, 'deflated' => $deflated]);
if ($status !== Aerospike::OK) {
    die($client->error());
}
$client->get($key, $record);
$wrapped = \Aerospike\Bytes::unwrap($record['bins']['wrapped']);
$deflated = $record['bins']['deflated'];
$inflated = gzinflate($deflated->s);
echo "$inflated\n";
echo "wrapped binary-string: ";
var_dump($wrapped);
$unwrapped = $record['bins']['unwrapped'];
echo "The binary-string that was given to put() without a wrapper: $unwrapped\n";

$client->close();

Outputs:

Glagnar's Human Rinds, "It's a bunch'a munch'a crunch'a human!
wrapped binary-string: string(10) "truncated"
The binary-string that was given to put() without a wrapper: trunc

Further Reading