USAGE.md

Usage

Create a \yrmcds\Client instance

First of all, you must create a client object as follows:

$client = new \yrmcds\Client("server", 11211);

The above code creates a client connected to memcached or yrmcds running on "server" on port 11211. The connection is not persistent; it will be closed when this object is deleted.

Create a client with persistent connection

To keep the connection between requests, specify a persistent ID in the third parameter of the constructor:

$client = new \yrmcds\Client('server', 11211, 'server');

As shown, using the hostname as the persistent ID is recommended.

Although a persistent connection will not be closed at a request end, these finalizations are done to make it stable:

• All server-side locks acquired by this client are released.
• Floating response packets are received and discarded.
• The socket timeout value is reset to the default.

Auto prefixing keys

In many cases, a memcached client need to prefix a constant string to all keys. By specifying a non-empty string in the fourth parameter of the constructor, the client will automatically prefix that string to keys.

For instance, the following code will store an object with prefix:foo key:

$client = new \yrmcds\Client('server', 11211, NULL, 'prefix:');
$client->set('foo', 'some data');

Request serial number

Every command sending method in \yrmcds\Client does not wait the response from the server. Instead, it returns a serial number of the issued request.

To receive a response for a command, use \yrmcds\Client::recv():

$serial = $client->set('foo', 'some data');
echo $serial, PHP_EOL; // prints the serial number of the set command.

$r = $client->recv();
var_dump( $r );        // $r is an instance of \yrmcds\Response

Quiet commands

Most commands have quiet mutations. For instance, the quiet mutation of get command can be issued by passing TRUE to $quiet parameter:

$client->get($key, TRUE);

The server does not send a response for these quiet mutations when the command succeeds, i.e. when the response status code would be \yrmcds\STATUS_OK.

In addition, the server does not send a response for get commands when the response code would be \yrmcds\STATUS_NOTFOUND, i.e. when the named object does not exist in the server.

Multi get

Combining the asynchronous commands and quiet mutations, multi-get can be implemented efficiently:

$client->get($key1, TRUE);
$client->get($key2, TRUE);
$client->get($key3, TRUE);
...
$client->get($keyn, TRUE);
$serial = $client->noop();  // noop is guaranteed to return a response.

while( TRUE ) {
    $r = $client->recv();
    if( $r->serial == $serial )
        break;              // got the response for noop.

    var_dump( $r );         // dump retrieved objects.
}

Retrieving statistics

For statGeneral(), statSettings(), statItems() and statSizes() commands, the server returns a series of response packets. The series ends with a response with no key property.

This code shows the general server statistics:

$client->statGeneral();
while( TRUE ) {
    $r = $client->recv();
    if( ! property_exists($r, 'key') )
        break;
    echo $r->key, ': ', $r->data, PHP_EOL;
}

Errors

Errors are notified in these 3 ways:

1. Fatal PHP error

   is triggered when an API is used illegally.

2. \yrmcds\Error exception

   is thrown when a network problem happens.

3. The response status code in a \yrmcds\Response instance

   brings the result of an issued command.

For instance, lock() command may fail with \yrmcds\STATUS_LOCKED status code if the object is already locked by another client:

$client->lock($key);

$r = $client->recv();
if( $r->status == \yrmcds\STATUS_LOCKED ) {
    // the object has been locked by another client.
}

Session handler

yrmcds_session.php provides a session handler class utilizing the server-side locking mechanism of yrmcds.

Compared to the widely adopted client-side locking technique using add, the server-side locking is far more robust.

Anyways, this is how to use the session handler:

$client = new \yrmcds\Client('server');
$handler = new \yrmcds\SessionHandler($client);
session_set_save_handler( $handler );

session_start();

The expiration time of inactive sessions and the timeout of lock acquisition can be configured by specifying the second and the third parameters of \yrmcds\SessionHandler constructor:

// inactive sessions will expire in 600 seconds.
$handler = new \yrmcds\SessionHandler($client, 600);

// lock timeout is set 30 seconds.
$handler = new \yrmcds\SessionHandler($client, 3600, 30);

// session lock is disabled.
$handler = new \yrmcds\SessionHandler($client, 3600, 0);

\yrmcds\SessionHandler requires PHP 5.4 or better and, of course, yrmcds.