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

Дата оновлення перекладу 2023-08-17

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

Цей адаптер зберігає значення в пам'яті, використовуючи один (або більше) екземплярів сервера Memcached. На відміну від адаптера APCu, і подібно до адаптера Redis, він не обмежується поточною пам'яттю сервера; ви можете зберігати зміст незалежно від вашого PHP-оточення. Можливість використовувати кластер серверів для забезпечення надмірності та/або відмовостійкості також доступна.

Caution

Вимоги: Розширення 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 за допомогою Імені джерела даних (DSN) або масиву 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([
    'memcached://10.0.0.100',
    'memcached://10.0.0.101',
    'memcached://10.0.0.102',
    // etc...
]);

// одне 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([
    // імʼя хосту + порт
    '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() також приймає масив опцій як другий аргумент. Очікуваним форматом є асоціативний масив пар ключ => значення, що представляють імена опцій та їхні відповідні значення:

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

$client = MemcachedAdapter::createConnection(
    // рядок DSN або масив рядків DSN
    [],

    // асоціативний масив опцій конфігурації
    [
        '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, за замовчуванням: 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.

Допустимими значеннями опції є будь-який літерно-цифровий рядок.

poll_timeout (тип: int, за замовчуванням: 1000)

Задає час (у секундах) до закінчення тайм-ауту під час операції опитування сокета.

Допустимими значеннями опції є будь-яке натуральне число.

randomize_replica_read (тип: bool, за замовчуванням: false)
Вмикає або вимикає рандомізацію початкової точки зчитування реплік. Зазвичай читання виконується з основного сервера, а у випадку промаху - з "основного+1", потім з "основного+2" і так до n реплік. Ця опція встановлює читання реплік у рандомізованому порядку між усіма доступними серверами; це дозволяє розподілити навантаження читання між декількома серверами за рахунок більшого трафіку на запис.
recv_timeout (тип: int, за замовчуванням: 0)

Задає кількість часу (у мікросекундах) до закінчення тайм-ауту під час операції вихідного сокета (читання). Якщо опцію no_block не увімкнено, це все одно дозволить вам використовувати тайм-аути на читання даних.

Допустимими значеннями опції є 0 або будь-яке натуральне число.

retry_timeout (тип: int, за замовчуванням: 0)

Вказує час (у секундах) до завершення тайм-ауту і повторної спроби з'єднання.

Допустимими значеннями опції є будь-яке натуральне число.

send_timeout (тип: int, за замовчуванням: 0)

Вказує кількість часу (у мікросекундах) до тайм-ауту під час вхідної операції сокета (надсилання). Якщо опція no_block не увімкнена, це дозволить вам мати таймаут при відправці даних.

Допустимими значеннями опції є 0 або будь-яке натуральне число.

serializer (тип: string, за замовчуванням: php)

Вказує серіалізатор для серіалізації нескалярних значень. Опція igbinary вимагає, щоб розширення PHP igbinary було увімкнено, а розширення 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`_" (алгоритм Нейгла) Протоколу керування передаванням (TCP), який є механізмом, призначеним для підвищення ефективності роботи мереж за рахунок зменшення зайвих зусиль на заголовки TCP шляхом об'єднання декількох невеликих вихідних повідомлень і надсилання їх одночасно.
use_udp (тип: bool, за замовчуванням: false)

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

Caution

У цьому режимі тестуються не всі операції бібліотеки. Змішані TCP та UDP сервери не допускаються.

verify_key (тип: bool, за замовчуванням: false)
Вмикає або вимикає тестування і перевірку всіх використовуваних ключів, щоб переконатися, що вони є дійсними і відповідають дизайну протоколу, який використовується.

Tip

Зверніться до документації про попередньо визначені константи розширення Memcached для отримання додаткової інформації про доступні опції.