The Aerospike client for PHP enables your 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.
The Aerospike client for PHP is written as a C module, but we have added a PHP
stub under docs/phpdoc. You can import the stub into your IDE for
auto-completion, or build the API documentation using
phpDocumentor
phpdoc run -v -d phpdoc/ -t html/
The Aerospike PHP client provides a custom session handler that can be used to store user sessions in Aerospike. A set and namespace must be given to act as the container for the sessions.
The session ID is used as the primary key of the record containing the
session. The key-value pairs in the $_SESSION object are stored in the matching
record. The value of session.gc_maxlifetime is used as the record ttl.
session.save_handler string
Set to aerospike to enable sessions support.
session.save_path string
A string formatted as ns|set|addr:port[,addr:port[,...]]. for example "test|sess|127.0.0.1:3000"
As with the $config of the constructor, the host info of just one cluster node is necessary.
Initializing the client to a cluster is a costly operation, so ideally it should be reused for the multiple requests that the same PHP process will handle (as is the case for mod_php and fastCGI).
The developer can determine whether the constructor will
use persistent connections by way of an optional boolean argument.
After the first time Aerospike::__construct__() is called within the process, the
client will be stored for reuse by subsequent requests, if persistent connections
were indicated. With persistent connections, the methods reconnect() and
close() do not actually close the connection.
Each Aerospike client opens 2*N connections to the cluster, where N is the number
of nodes in that cluster, and a connection simply costs a file descriptor
on the server-side. Depending on the number of web servers and PHP processes on
each server, you may need to adjust the
proto-fd-max
server config parameter and the OS limits to account for the necessary number of
file descriptors.
On the client side, the web server should be configured to reduce the frequency
in which new clients are created. Historically, the max_requests for mod_php
and FPM was set low to combat memory leaks. PHP has been stable on memory for a
long while, so the correct configuration would be to have fewer processes, and
let each of them handle a high number of requests. This reduces the process
initialization overhead, and the overall number of connections on the web
server. Monitoring the memory consumption of the PHP processes allows the
max_requests to be raised safely to an efficient, stable value.
The client keeps track of changes at the server-side through a
cluster tending
thread. In a web server context, a single client can handle cluster tending and
share its state through a shared-memory segment. To enable shm cluster tending,
the developer can set the aerospike.shm.use ini config
to true, or at the constructor through its config.
Halting a query() or scan() result stream can be done by returning (an explicit) boolean false from the callback. The client will then close the sockets to the nodes of the cluster, halting the stream of records.
The PHP Data types of Integer, String, Float, Array map directly to Aerospike data types. All other data types will be handled through serialization. See the "Handling Unsupported Types" sections for details. The following table shows how data is stored
| PHP Data Type | Aerospike Data type |
|---|---|
| Integer | integer |
| Float | float |
| String | string |
| Array | (list or map)* |
| \Aerospike\Bytes | blob |
Depending on the structure of the array in PHP, the data will be either stored as an as_list, or an as_map.
If the array has only integer keys, which are sequential and begin with 0, it will be stored as as_list. Otherwise
it will be stored as as_map. For example ["a", "b", "c"] would be stored as a list, whereas ["a" => "1", "b", "c"=>"d"] would
be stored as as_map.
Both list and map datatypes from the server will be converted into PHP arrays
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 convert it to \Aerospike\Bytes
Warning Storing \Aerospike\Bytes results in information being stored as: AS_BYTES_BLOB . Subsequent retrieval of this data will be passed to a user specified deserializer if it has been registered. Storing \Aerospike\Bytes and using a user specified deserializer will likely cause errors, and is strongly discouraged.
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.
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
- LDT Support has been removed.
- Type checking in general is stricter for method parameters. If you are not sure whether an argument to a function is an integer or a string, we recommend casting it to the type specified by the method. Running with strict_types enabled may help to catch some issues.
- An exception will be raised if the constructor fails to connect to the cluster.
- \Aerospike\Bytes will be stored to the server as type AS_BYTES_BLOB instead of AS_BYTES_PHP. This change allows better compatability with other clients.
- Correspondingly, data stored in the server as AS_BYTES_BLOB will be returned as Aerospike\Bytes, if no deserializer has been registered. The Previous version of the Aerospike PHP Client returned a string if AS_BYTES_BLOB was encountered with no registered deserializer.
- Support for PHP versions < 7 has been removed.
- The INI entry
aerospike.serializernow takes an integer value. 0 for No Serializer, 1 for default PHP serialization, and 2 for user specified serializer. See Configuration for additional information on the code values. - The constructor will no longer attempt to create a unique SHM key for the user. If a key is not specified in the shm configuration array, the default value will be used. A key provided in the constructor takes precedence over a value specified by INI.
- The layout of the shared memory used by the client when using an SHM key has changed. The default key has changed as well in order to prevent accidental sharing between new and old clients.
- The formatting of the response from an info call may have changed. It now includes the request at the beginning of the response.
- When using initKey with a digest, the digest must now be exactly 20 bytes.
- The integer values of the
Aerospike::LOG_LEVEL_*constants have changed. This should not effect the user unless they were providing log levels as integers rather than using the constants. Aerospike::LOG_LEVEL_OFFhas been removed. It no longer had any effect.
PHP >= 7 is supported by this client.