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


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.


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:


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('', 11211);
$backupClient = new Client();
$backupClient->addServer('', 11211);
$clients = [
    'default' => $defaultClient,
    'backup' => $backupClient
$memcached = new Memcached($clients);

You can get a particular client instance:


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('', 11211);
$client->addServer('', 11211);
$memcached = new Memcached($client);

You can get the client instance:


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();


To Memcached
$phpBoolean = true;
echo $typeMapper->toMemcachedBoolean($phpBoolean); // 1
From Memcached
$memcachedBoolean = 1;
echo $typeMapper->fromMemcachedBoolean($memcachedBoolean) === true; // 1


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"