Адаптер кеша Memcached

Дата обновления перевода 2025-07-25

Адаптер кеша Memcached

Этот адаптер сохраняет значения в оперативной памяти, используя один (или больше) экземпляр Memcached server. В отличие от адаптера APCu adapter, и схоже с адаптером Redis, он не ограничен общей памятью текушего сервера; вы можете хранить содержание независимо от вашего PHP окружения. Возможность использовать кластер серверов для предоставляения избыточности и / или восстановления после отказа, также доступна.

Warning

Требования: PHP-расширение Memcached, а также сервер Memcached должны быть установлены, активны и запущены для использования этого адаптера. Для этого адаптера требуется версия PHP-расширения Memcached 2.2 и выше.

Этот адаптер ожидает передачи экземпляра Memcached в качестве первого параметра. Пространство имён и время жизни кеша по умолчанию могут быть опционально переданы в качестве второго и третьего параметров:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
use Symfony\Component\Cache\Adapter\MemcachedAdapter;

$cache = new MemcachedAdapter(
    // объект клиента, который устанавливает опции и добавляет экземпляр(ы) сервера
    \Memcached $client,

    // строка-префикс ключей объектов, хранящихся в этом кеше
    $namespace = '',

    // время жизни по умолчанию (в секундах) для объектов кеша, которые не определяют
    // собственное время жизни, со значением 0, вызывающим бесконечное хранение объектов
    // (т.е. пока не вызывается MemcachedAdapter::clear() или не перезапускается сервер(ы))
    $defaultLifetime = 0
);

Сконфигурируйте соединение

Метод помощника createConnection() позволяет создание и конфигурацию экзепмпляра класса Memcached, используя Domain Name System (DNS) или массив DSN:

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;

// передайте одну строку DSN, чтобы зарегистрировать один сервер для клиента
$client = MemcachedAdapter::createConnection(
    'memcached://localhost'
    // DSN может включать в себя опции конфигурации (передайте их в качестве строки запроса):
    // 'memcached://localhost:11222?retry_timeout=10'
    // 'memcached://localhost:11222?socket_recv_size=1&socket_send_size=2'
);

// передайте массив строк DSN, чтобы зарегистрировать несколько серверов для клиента
$client = MemcachedAdapter::createConnection(array(
    'memcached://10.0.0.100',
    'memcached://10.0.0.101',
    'memcached://10.0.0.102',
    // и др...
));

// одно DSN может определять несколько серверов, используя следующий синтаксис:
// host[hostname-or-IP:port] (где порт является опциональным). Сокеты должны содержать замыкание ':'
$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(array(
    // имя хоста + порт
    'memcached://my.server.com:11211'

    // имя хоста без порта + имя пользователя и пароль SASL
    'memcached://rmf:abcdef@localhost'

    // IP адеса вместо имени хоста + вес
    'memcached://127.0.0.1?weight=50'

    // сокет вместо имени хоста/IP + имя пользователя и пароль SASL
    'memcached://janesmith:mypassword@/var/run/memcached.sock'

    // сокет вместо имени хоста/IP + вес
    'memcached:///var/run/memcached.sock?weight=20'
));

Сконфигурируйте опции

Метод помощника createConnection() также принимает массив опций в качестве второго аргумента. Ожидаемый формат - это ассоцитивный массив пар key => value, представляющих имена опций и их соответствующие значения:

1
2
3
4
5
6
7
8
9
10
11
12
13
use Symfony\Component\Cache\Adapter\MemcachedAdapter;

$client = MemcachedAdapter::createConnection(
    // DSN-строка или массив DSN-строк
    array(),

    // ассоциативный массив опций конфигурации
    array(
        'compression' => true,
        '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)

Указывает количество реплик, которые должны сохраняться для каждого объекта (на разных серверах). Это не обязывает определенные мем-кешированные серверы хранить реплики, а вемсто этого сохраняет реплики вместе со всеми другими объектами (на "n" - следующих зарегистрированных серверах).

Валидные значения опции включают в себя любое положительное число.

prefix_key (тип: string, по умолчанию: an empty string)

Указывает "домен" (или "пространство имён"), досбавленный к вашим ключам. Он не может быть длиннее 128 знаков и уменьшает максимальный размер ключа.

Валидные значения опции включают в себя любую буквенно-цифровую строку.

poll_timeout (тип: int, по умолчанию: 1000)

Указывает количество времени (в секундах) перед тайм-аутом во время операции опроса сокетов.

Валидные значения опции включают в себя любое положительное число.

randomize_replica_read (тип: bool, по умолчанию: false)
Включает или отключает рандомизацию отправной точки чтения реплики. Обычно чтение происходит с основного сервера, а в случае ошибки - с "primary+1", потом "primary+2", и так до "н" реплик. Эта опция устанавливает чтения реплик рандомизированно между всеми доступными серверами; это позволяет распределять нагрузку чтений на несколько серверов за счёт увеличения трафика записи.
recv_timeout (тип: int, по умолчанию: 0)

Указывает количество времени (в микросекундах) до тайм-аута во время операции исходящего сокета (чтения). Когда опция no_block не включена, это позволит вам всё равно иметь тайм-ауты во время чтения данных.

Валидные значения опции включают в себя 0 или любое положительное число.

retry_timeout (тип: int, по умолчанию: 0)

Указывает количество времени (в секундах) до тайм-аута и повторной попытки установки соединения.

Валидные значения опции включают в себя любое положительное число.

send_timeout (тип: int, по умолчанию: 0)

Указывает количество времени (в микросекундах) до тайм-аута во время операций входящего сокета (отправки). Когда опция no_block е включена, это позволит вам всё равно иметь тайм-ауты во время отправки данных.

Валидные значения опции включают в себя 0 или любое положительное число.

serializer (тип: string, по умолчанию: php)

Указывает, как сериализатор использовать для сериализации нескалярных значений. Опции igbinary требуют включения ig-бинарного PHP расширения, а также компиляции мем-кешированного расширения для его поддержки.

Валидные значения опции включают в себя 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`_" (алогоритм Нейгла) Протокол управления передачей (TCP), который является механизмом для улучшения проихводительности сетей путём снижения перенагрузки заголовков TPC, объединяя неколько небольших исходящих сообщений и отправляя их одновременно.
use_udp (тип: bool, по умолчанию: false)

Включает или отключает использование режима Протокол пользовательских датаграм (UDP) (вместо режима Протокол управления передачей (TCP)), где все операции исполняются в режиме "выстрелил и забыл"; после исполнение клиентом, не будет сделано ни одной попытки убедиться, что операция была получена или получила обратной воздействие.

Warning

Не все операции библиотек тестируются в этом режиме. Смешанные серверы TCP и UDP не разрешены.

verify_key (тип: bool, по умолчанию: false)
Включает или отключает тестирование и верификацию для всех использованных ключей, чтобы зарантировать, что они валидны и подходят под используемый протокол.
.. tip::
Обратитесь к документации предопределённые константы расширения Memcached, чтобы узнать больше о доступных опциях.