Memcached Cache Adapter
Warning: You are browsing the documentation for Symfony 4.x, which is no longer maintained.
Read the updated version of this page for Symfony 7.1 (the current stable version).
This adapter stores the values in-memory using one (or more) Memcached server instances. Unlike the APCu adapter, and similarly to the Redis adapter, it is not limited to the current server's shared memory; you can store contents independent of your PHP environment. The ability to utilize a cluster of servers to provide redundancy and/or fail-over is also available.
Caution
Requirements: The Memcached PHP extension as well as a Memcached server
must be installed, active, and running to use this adapter. Version 2.2
or
greater of the Memcached PHP extension is required for this adapter.
This adapter expects a Memcached instance to be passed as the first parameter. A namespace and default cache lifetime can optionally be passed as the second and third parameters:
1 2 3 4 5 6 7 8 9 10 11 12 13 14
use Symfony\Component\Cache\Adapter\MemcachedAdapter;
$cache = new MemcachedAdapter(
// the client object that sets options and adds the server instance(s)
\Memcached $client,
// a string prefixed to the keys of the items stored in this cache
$namespace = '',
// the default lifetime (in seconds) for cache items that do not define their
// own lifetime, with a value 0 causing items to be stored indefinitely (i.e.
// until MemcachedAdapter::clear() is invoked or the server(s) are restarted)
$defaultLifetime = 0
);
Configure the Connection
The createConnection() helper method allows creating and configuring a Memcached class instance using a Data Source Name (DSN) or an array of DSNs:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
use Symfony\Component\Cache\Adapter\MemcachedAdapter;
// pass a single DSN string to register a single server with the client
$client = MemcachedAdapter::createConnection(
'memcached://localhost'
// the DSN can include config options (pass them as a query string):
// 'memcached://localhost:11222?retry_timeout=10'
// 'memcached://localhost:11222?socket_recv_size=1&socket_send_size=2'
);
// pass an array of DSN strings to register multiple servers with the client
$client = MemcachedAdapter::createConnection([
'memcached://10.0.0.100',
'memcached://10.0.0.101',
'memcached://10.0.0.102',
// etc...
]);
// a single DSN can define multiple servers using the following syntax:
// host[hostname-or-IP:port] (where port is optional). Sockets must include a trailing ':'
$client = MemcachedAdapter::createConnection(
'memcached:?host[localhost]&host[localhost:12345]&host[/some/memcached.sock:]=3'
);
4.2
The option to define multiple servers in a single DSN was introduced in Symfony 4.2.
The Data Source Name (DSN) for this adapter must use the following format:
1
memcached://[user:pass@][ip|host|socket[:port]][?weight=int]
The DSN must include a IP/host (and an optional port) or a socket path, an
optional username and password (for SASL authentication; it requires that the
memcached extension was compiled with --enable-memcached-sasl
) and an
optional weight (for prioritizing servers in a cluster; its value is an integer
between 0
and 100
which defaults to null
; a higher value means more
priority).
Below are common examples of valid DSNs showing a combination of available values:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
use Symfony\Component\Cache\Adapter\MemcachedAdapter;
$client = MemcachedAdapter::createConnection([
// hostname + port
'memcached://my.server.com:11211'
// hostname without port + SASL username and password
'memcached://rmf:abcdef@localhost'
// IP address instead of hostname + weight
'memcached://127.0.0.1?weight=50'
// socket instead of hostname/IP + SASL username and password
'memcached://janesmith:mypassword@/var/run/memcached.sock'
// socket instead of hostname/IP + weight
'memcached:///var/run/memcached.sock?weight=20'
]);
Configure the Options
The createConnection()
helper method also accepts an array of options as its second argument. The
expected format is an associative array of key => value
pairs representing
option names and their respective values:
1 2 3 4 5 6 7 8 9 10 11 12
use Symfony\Component\Cache\Adapter\MemcachedAdapter;
$client = MemcachedAdapter::createConnection(
// a DSN string or an array of DSN strings
[],
// associative array of configuration options
[
'libketama_compatible' => true,
'serializer' => 'igbinary',
]
);
Available Options
auto_eject_hosts
(type:bool
, default:false
)-
Enables or disables a constant, automatic, re-balancing of the cluster by
auto-ejecting hosts that have exceeded the configured
server_failure_limit
. buffer_writes
(type:bool
, default:false
)- Enables or disables buffered input/output operations, causing storage commands to buffer instead of being immediately sent to the remote server(s). Any action that retrieves data, quits the connection, or closes down the connection will cause the buffer to be committed.
connect_timeout
(type:int
, default:1000
)-
Specifies the timeout (in milliseconds) of socket connection operations when the
no_block
option is enabled.Valid option values include any positive integer.
distribution
(type:string
, default:consistent
)-
Specifies the item key distribution method among the servers. Consistent hashing delivers better distribution and allows servers to be added to the cluster with minimal cache losses.
Valid option values include
modula
,consistent
, andvirtual_bucket
. hash
(type:string
, default:md5
)-
Specifies the hashing algorithm used for item keys. Each hash algorithm has its advantages and its disadvantages. The default is suggested for compatibility with other clients.
Valid option values include
default
,md5
,crc
,fnv1_64
,fnv1a_64
,fnv1_32
,fnv1a_32
,hsieh
, andmurmur
. libketama_compatible
(type:bool
, default:true
)-
Enables or disables "libketama" compatible behavior, enabling other
libketama-based clients to access the keys stored by client instance
transparently (like Python and Ruby). Enabling this option sets the
hash
option tomd5
and thedistribution
option toconsistent
. no_block
(type:bool
, default:true
)- Enables or disables asynchronous input and output operations. This is the fastest transport option available for storage functions.
number_of_replicas
(type:int
, default:0
)-
Specifies the number of replicas that should be stored for each item (on different servers). This does not dedicate certain memcached servers to store the replicas in, but instead stores the replicas together with all of the other objects (on the "n" next servers registered).
Valid option values include any positive integer.
prefix_key
(type:string
, default: an empty string)-
Specifies a "domain" (or "namespace") prepended to your keys. It cannot be longer than 128 characters and reduces the maximum key size.
Valid option values include any alphanumeric string.
poll_timeout
(type:int
, default:1000
)-
Specifies the amount of time (in seconds) before timing out during a socket polling operation.
Valid option values include any positive integer.
randomize_replica_read
(type:bool
, type:false
)- Enables or disables randomization of the replica reads starting point. Normally the read is done from primary server and in case of a miss the read is done from "primary+1", then "primary+2", all the way to "n" replicas. This option sets the replica reads as randomized between all available servers; it allows distributing read load to multiple servers with the expense of more write traffic.
recv_timeout
(type:int
, default:0
)-
Specifies the amount of time (in microseconds) before timing out during an outgoing socket (read) operation. When the
no_block
option isn't enabled, this will allow you to still have timeouts on the reading of data.Valid option values include
0
or any positive integer. retry_timeout
(type:int
, default:0
)-
Specifies the amount of time (in seconds) before timing out and retrying a connection attempt.
Valid option values include any positive integer.
send_timeout
(type:int
, default:0
)-
Specifies the amount of time (in microseconds) before timing out during an incoming socket (send) operation. When the
no_block
option isn't enabled, this will allow you to still have timeouts on the sending of data.Valid option values include
0
or any positive integer. serializer
(type:string
, default:php
)-
Specifies the serializer to use for serializing non-scalar values. The
igbinary
options requires the igbinary PHP extension to be enabled, as well as the memcached extension to have been compiled with support for it.Valid option values include
php
andigbinary
. server_failure_limit
(type:int
, default:0
)-
Specifies the failure limit for server connection attempts before marking the server as "dead". The server will remain in the server pool unless
auto_eject_hosts
is enabled.Valid option values include any positive integer.
socket_recv_size
(type:int
)-
Specified the maximum buffer size (in bytes) in the context of incoming (receive) socket connection data.
Valid option values include any positive integer, with a default value that varies by platform and kernel configuration.
socket_send_size
(type:int
)-
Specified the maximum buffer size (in bytes) in the context of outgoing (send) socket connection data.
Valid option values include any positive integer, with a default value that varies by platform and kernel configuration.
tcp_keepalive
(type:bool
, default:false
)- Enables or disables the "`keep-alive`_" Transmission Control Protocol (TCP) feature, which is a feature that helps to determine whether the other end has stopped responding by sending probes to the network peer after an idle period and closing or persisting the socket based on the response (or lack thereof).
tcp_nodelay
(type:bool
, default:false
)- Enables or disables the "`no-delay`_" (Nagle's algorithm) Transmission Control Protocol (TCP) algorithm, which is a mechanism intended to improve the efficiency of networks by reducing the overhead of TCP headers by combining a number of small outgoing messages and sending them all at once.
use_udp
(type:bool
, default:false
)-
Enables or disables the use of User Datagram Protocol (UDP) mode (instead of Transmission Control Protocol (TCP) mode), where all operations are executed in a "fire-and-forget" manner; no attempt to ensure the operation has been received or acted on will be made once the client has executed it.
Caution
Not all library operations are tested in this mode. Mixed TCP and UDP servers are not allowed.
verify_key
(type:bool
, default:false
)- Enables or disables testing and verifying of all keys used to ensure they are valid and fit within the design of the protocol being used.
Tip
Reference the Memcached extension's predefined constants documentation for additional information about the available options.