Memcached

Table of Contents

1. Introduction
2. Libraries
3. Creating a Memcached Connection
   1. Single Client
   2. Multiple Clients
   3. Server Pools
4. Type Mappers
   1. Booleans
   2. Timestamps

Introduction

Memcached (pronounced "Mem-cash-dee") is a distributed memory cache with basic key-value store functionality. Although it doesn't come with all the bells and whistles of Redis, it does offer faster speed, which is suitable for simple key-value data. For more information, read the official PHP documentation.

Libraries

Opulence lets you choose whichever Memcached library you'd like. The built-in library \Memcached is the most popular.

Creating a Memcached Connection

Opulence\Memcached\Memcached acts as a convenient wrapper around Memcached. It accepts either a single client or a list of clients. Opulence uses magic methods to pass on method calls to the underlying Memcached client(s).

Single Client

use Memcached as Client;
use Opulence\Memcached\Memcached;

// Create our connection
$client = new Client();
$client->addServer('localhost', 11211);
$memcached = new Memcached($client);

// Try it out
$memcached->set('foo', 'bar');
echo $memcached->get('foo'); // "bar"

You can get the client instance:

$memcached->getClient();

Multiple Clients

If you pass in multiple clients, one of them MUST be named default.

use Memcached as Client;
use Opulence\Memcached\Memcached;

$defaultClient = new Client();
$defaultClient->addServer('127.0.0.1', 11211);
$backupClient = new Client();
$backupClient->addServer('127.0.0.2', 11211);
$clients = [
    'default' => $defaultClient,
    'backup' => $backupClient
];
$memcached = new Memcached($clients);

You can get a particular client instance:

$memcached->getClient('backup');

Note: The default client will always be used unless you call getClient($name) and make calls to that client directly.

Server Pools

\Memcached allows you to add multiple servers to a client:

use Memcached as Client;
use Opulence\Memcached\Memcached;

$client = new Client();
$client->addServer('127.0.0.1', 11211);
$client->addServer('127.0.0.2', 11211);
$memcached = new Memcached($client);

You can get the client instance:

$memcached->getClient();

Type Mappers

Opulence\Memcached\Types\TypeMapper helps you translate to and from Memcached data types. For example, you cannot store a DateTime object in Memcached, so you need to convert to a Unix timestamp when storing it. Conversely, when you read from Memcached, you can use a type mapper to convert the Unix timestamp back into a DateTime object. You can also use a factory to create type mappers:

use Opulence\Memcached\Types\Factories\TypeMapperFactory;

$typeMapper = (new TypeMapperFactory)->createTypeMapper();

Booleans

To Memcached

$phpBoolean = true;
echo $typeMapper->toMemcachedBoolean($phpBoolean); // 1

From Memcached

$memcachedBoolean = 1;
echo $typeMapper->fromMemcachedBoolean($memcachedBoolean) === true; // 1

Timestamps

To Memcached

$phpDate = new DateTime('1987-07-24 12:34:56');
echo $typeMapper->toMemcachedTimestamp($phpDate); // 554128496

Note: This method accepts any object implementing DateTimeInterface, including DateTimeImmutable.

From Memcached

$memcachedDate = 554128496;
$phpDate = $typeMapper->fromMemcachedTimestamp($memcachedDate);
echo $phpDate->format('Y-m-d'); // "1987-07-24"