Memcached 缓存适配器

编辑此页

此适配器使用一个（或多个）Memcached 服务器实例将值存储在内存中。与 APCu 适配器不同，但与 Redis 适配器类似，它不受限于当前服务器的共享内存；您可以独立于 PHP 环境存储内容。还可以利用服务器集群来提供冗余和/或故障转移。

警告

要求： 必须安装、激活并运行 Memcached PHP 扩展以及 Memcached 服务器才能使用此适配器。此适配器需要 2.2 或更高版本的 Memcached PHP 扩展。

此适配器期望将 Memcached 实例作为第一个参数传递。命名空间和默认缓存生命周期可以可选地作为第二个和第三个参数传递。

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

配置连接

`createConnection()` 辅助方法允许使用数据源名称 (DSN) 或 DSN 数组创建和配置 Memcached 类实例。

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://127.0.0.1'
    // the DSN can include config options (pass them as a query string):
    // 'memcached://127.0.0.1:11222?retry_timeout=10'
    // 'memcached://127.0.0.1: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'
);

此适配器的数据源名称 (DSN) 必须使用以下格式：

1
memcached://[user:pass@][ip|host|socket[:port]][?weight=int]

DSN 必须包含 IP/主机（以及可选端口）或套接字路径、可选的用户名和密码（用于 SASL 身份验证；这要求 memcached 扩展在编译时使用了 --enable-memcached-sasl）以及可选的权重（用于在集群中优先排序服务器；其值是介于 0 和 100 之间的整数，默认为 null；值越高表示优先级越高）。

以下是有效 DSN 的常见示例，展示了可用值的组合：

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'
]);

配置选项

`createConnection()` 辅助方法还接受选项数组作为其第二个参数。期望的格式是 key => value 对的关联数组，表示选项名称及其各自的值。

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',
    ]
);

可用选项

auto_eject_hosts (类型: bool, 默认值: false)
启用或禁用集群的持续、自动重新平衡，方法是自动移除超出配置的 server_failure_limit 的主机。
buffer_writes (类型: bool, 默认值: false)
启用或禁用缓冲输入/输出操作，使存储命令缓冲而不是立即发送到远程服务器。任何检索数据、退出连接或关闭连接的操作都将导致缓冲区被提交。
connect_timeout (类型: int, 默认值: 1000)

指定启用 no_block 选项时套接字连接操作的超时时间（以毫秒为单位）。

有效的选项值包括*任何正整数*。

distribution (类型: string, 默认值: consistent)

指定服务器之间项目键的分配方法。一致性哈希提供更好的分配，并允许在缓存损失最小的情况下将服务器添加到集群。

有效的选项值包括 modula、consistent 和 virtual_bucket。

hash (类型: string, 默认值: md5)

指定用于项目键的哈希算法。每种哈希算法都有其优点和缺点。建议使用默认值以与其他客户端兼容。

有效的选项值包括 default、md5、crc、fnv1_64、fnv1a_64、fnv1_32、fnv1a_32、hsieh 和 murmur。

libketama_compatible (类型: bool, 默认值: true)
启用或禁用 "libketama" 兼容行为，使其他基于 libketama 的客户端能够透明地访问客户端实例存储的键（例如 Python 和 Ruby）。启用此选项会将 hash 选项设置为 md5，并将 distribution 选项设置为 consistent。
no_block (类型: bool, 默认值: true)
启用或禁用异步输入和输出操作。这是存储功能可用的最快传输选项。
number_of_replicas (类型: int, 默认值: 0)

指定应为每个项目存储的副本数（在不同的服务器上）。这不会指定某些 memcached 服务器来存储副本，而是将副本与所有其他对象一起存储（在注册的“n”个后续服务器上）。

有效的选项值包括*任何正整数*。

prefix_key (类型: string, 默认值: 空字符串)

指定一个前置于您的键的“域”（或“命名空间”）。它不能超过 128 个字符，并且会减小最大键大小。

有效的选项值包括*任何字母数字字符串*。

poll_timeout (类型: int, 默认值: 1000)

指定套接字轮询操作超时前的时间量（以秒为单位）。

有效的选项值包括*任何正整数*。

randomize_replica_read (类型: bool, 默认值: false)
启用或禁用副本读取起点的随机化。通常，读取是从主服务器完成的，如果未命中，则从“primary+1”，然后“primary+2”，一直到“n”个副本完成读取。此选项将副本读取设置为在所有可用服务器之间随机进行；它允许将读取负载分配到多个服务器，但代价是更多的写入流量。
recv_timeout (类型: int, 默认值: 0)

指定传出套接字（读取）操作超时前的时间量（以微秒为单位）。当 no_block 选项未启用时，这将允许您仍然对数据读取设置超时。

有效的选项值包括 0 或*任何正整数*。

retry_timeout (类型: int, 默认值: 0)

指定连接尝试超时并重试之前的时间量（以秒为单位）。

有效的选项值包括*任何正整数*。

send_timeout (类型: int, 默认值: 0)

指定传入套接字（发送）操作超时前的时间量（以微秒为单位）。当 no_block 选项未启用时，这将允许您仍然对数据发送设置超时。

有效的选项值包括 0 或*任何正整数*。

serializer (类型: string, 默认值: php)

指定用于序列化非标量值的序列化器。igbinary 选项需要启用 igbinary PHP 扩展，以及 memcached 扩展在编译时已支持它。

有效的选项值包括 php 和 igbinary。

server_failure_limit (类型: int, 默认值: 0)

指定服务器连接尝试的失败限制，超过此限制后，服务器将被标记为“死机”。除非启用 auto_eject_hosts，否则服务器将保留在服务器池中。

有效的选项值包括*任何正整数*。

socket_recv_size (类型: int)

指定传入（接收）套接字连接数据上下文中的最大缓冲区大小（以字节为单位）。

有效的选项值包括*任何正整数*，默认值*因平台和内核配置而异*。

socket_send_size (类型: int)

指定传出（发送）套接字连接数据上下文中的最大缓冲区大小（以字节为单位）。

有效的选项值包括*任何正整数*，默认值*因平台和内核配置而异*。

tcp_keepalive (类型: bool, 默认值: false)
启用或禁用 "`keep-alive`_" 传输控制协议 (TCP) 功能，该功能通过在空闲期后向网络对等方发送探测，并根据响应（或缺乏响应）关闭或保持套接字，来帮助确定另一端是否已停止响应。
tcp_nodelay (类型: bool, 默认值: false)
启用或禁用 "`no-delay`_" (Nagle 算法) 传输控制协议 (TCP) 算法，这是一种旨在通过减少 TCP 标头的开销来提高网络效率的机制，方法是将多个小的传出消息组合在一起并一次性发送。
use_udp (类型: bool, 默认值: false)

启用或禁用用户数据报协议 (UDP) 模式（而不是传输控制协议 (TCP) 模式）的使用，其中所有操作都以“即发即弃”的方式执行；一旦客户端执行操作，就不会尝试确保操作已被接收或执行。

警告

并非所有库操作都在此模式下进行测试。不允许混合 TCP 和 UDP 服务器。

verify_key (类型: bool, 默认值: false)
启用或禁用对所有使用的键进行测试和验证，以确保它们有效并符合所用协议的设计。

提示

请参考 Memcached 扩展的预定义常量文档，以获取有关可用选项的更多信息。

本作品，包括代码示例，根据 Creative Commons BY-SA 3.0 许可协议获得许可。
目录
    版本