PHP: полный мануал с примерами, функциями и ООП

<?php
declare(strict_types=1);

$saved = apcu_store('shop:v1:category:7', 'Инструменты', 60);
if (!$saved) throw new RuntimeException('Кеш не принял запись');
echo apcu_fetch('shop:v1:category:7'), "\n";

Инструменты

Первый аргумент — адрес ячейки, второй — содержимое, 60 — секунды. Кеш не отправляет данные посетителю: вывод выполняет echo.

<?php
declare(strict_types=1);

$product = ['name' => 'Ключ', 'price' => 800];
apcu_store('shop:v1:product:17', $product, 60);
$product['price'] = 900;
echo apcu_fetch('shop:v1:product:17')['price'], "\n";
apcu_store('shop:v1:product:17', $product, 60);
echo apcu_fetch('shop:v1:product:17')['price'], "\n";

800
900

Исходный массив и кеш — разные состояния. Замена по тому же ключу разрешена store; add её запрещает.

<?php
declare(strict_types=1);

$failed = apcu_store(['shop:currency' => 'RUB', 'shop:language' => 'ru'], null, 60);
echo count($failed), "\n";
echo apcu_fetch('shop:currency'), "\n";

0
RUB

Проверяйте массив ошибок, а не if ($failed) как флаг успеха. При ошибке кеша рабочее приложение обычно продолжает с уже рассчитанными данными.

<?php
declare(strict_types=1);

var_dump(apcu_add('shop:currency', 'RUB', 60));
var_dump(apcu_add('shop:currency', 'EUR', 60));
echo apcu_fetch('shop:currency'), "\n";

bool(true)
bool(false)
RUB

Второй автор предложения не перезаписывает первое. Это не постоянное хранение пользовательского выбора — для него нужна база или сессия.

<?php
declare(strict_types=1);

apcu_store('shop:language', 'ru');
$failed = apcu_add(['shop:language' => 'en', 'shop:currency' => 'RUB'], null, 60);
echo implode(', ', array_keys($failed)), "\n";
echo apcu_fetch('shop:currency'), "\n";

shop:language
RUB

Часть набора может добавиться, часть — нет. Поэтому batch нельзя выдавать за транзакционную блокировку нескольких данных.

<?php
declare(strict_types=1);

apcu_store('shop:feature:delivery', false, 60);
$value = apcu_fetch('shop:feature:delivery', $found);
var_dump($found, $value);
$missing = apcu_fetch('shop:feature:unknown', $found);
var_dump($found, $missing);

bool(true)
bool(false)
bool(false)
bool(false)

Первое false — сохранённый ответ «доставка недоступна», второе — отсутствие записи. $found позволяет выбрать правильную ветку.

<?php
declare(strict_types=1);

apcu_store('shop:17', ['name' => 'Ключ']);
$keys = ['shop:17', 'shop:18'];
$found = apcu_fetch($keys, $batchProcessed);
foreach ($keys as $key) {
    echo $key, ': ', array_key_exists($key, $found) ? 'есть' : 'нужно загрузить', "\n";
}

shop:17: есть
shop:18: нужно загрузить

Проверка array_key_exists сохраняет смысл даже если кеш содержит null. После batch загружают только отсутствующие значения.

<?php
declare(strict_types=1);

apcu_store('shop:discount-enabled', false);
var_dump(apcu_exists('shop:discount-enabled'));
var_dump(apcu_exists('shop:unknown'));

bool(true)
bool(false)

Функция отвечает только о ячейке. Значение false не делает запись отсутствующей.

<?php
declare(strict_types=1);

apcu_store('shop:categories', ['Крепёж']);
$present = apcu_exists(['shop:categories', 'shop:brands']);
echo implode(', ', array_keys($present)), "\n";

shop:categories

При построении диагностического отчёта содержимое справочника не нужно. Если хотите сразу использовать данные, выбирайте fetch с $success.

<?php
declare(strict_types=1);

apcu_store('shop:v1:product:17', ['price' => 800]);
var_dump(apcu_delete('shop:v1:product:17'));
var_dump(apcu_exists('shop:v1:product:17'));
var_dump(apcu_delete('shop:v1:product:17'));

bool(true)
bool(false)
bool(false)

Сначала в реальном приложении успешно фиксируют изменение в основной базе, затем инвалидируют кеш. Здесь база намеренно не имитируется несуществующим вызовом.

<?php
declare(strict_types=1);

apcu_store('shop:17', 'Ключ');
$failed = apcu_delete(['shop:17', 'shop:18']);
echo implode(', ', $failed), "\n";

shop:18

Возвращаются ошибки, а не список удачных удалений. Повторное удаление уже отсутствующей кеш-копии в сценарии инвалидирования часто не требует аварии.

<?php
declare(strict_types=1);

apcu_store(['shop:v1:17' => 'Ключ', 'shop:v1:18' => 'Пила', 'other:17' => 'Не трогаем']);
apcu_delete(new APCUIterator('~^shop:v1:~', APC_ITER_KEY));
var_dump(apcu_exists('shop:v1:17'), apcu_exists('other:17'));

bool(false)
bool(true)

Шаблон явно ограничен нашим префиксом. Перебор не является транзакционным снимком: конкурентные новые записи требуют продуманного версионирования ключей.

<?php
declare(strict_types=1);

$calls = 0;
$build = function (string $key) use (&$calls): array {
    $calls++;
    return ['paid' => 'Оплачен', 'new' => 'Новый'];
};
$first = apcu_entry('shop:status-labels', $build, 60);
$second = apcu_entry('shop:status-labels', $build, 60);
echo $second['paid'], "\n", $calls, "\n";

Оплачен
1

Имя обработчика передают без скобок вызова. APCu сам вызывает его только на промахе; use (&$calls) здесь нужен лишь для видимого счётчика запусков.

<?php
declare(strict_types=1);

try {
    apcu_entry('shop:broken', function (string $key): array {
        throw new RuntimeException('Источник временно недоступен');
    }, 60);
} catch (RuntimeException $error) {
    echo $error->getMessage(), "\n";
}
echo apcu_entry('shop:broken', fn(string $key) => 'Восстановлено', 60), "\n";

Источник временно недоступен
Восстановлено

Не перехватываем ошибку внутри callback с return пустого каталога: такой пустой каталог стал бы закешированным нормальным результатом. Повтор возможен после устранения причины.

<?php
declare(strict_types=1);

echo apcu_inc('shop:events', 2, $ok, 60), "\n";
echo apcu_inc('shop:events', 3, $ok, 60), "\n";

2
5

На отсутствующем ключе исходной величиной служит ноль. Повторный вызов продолжает существующий счётчик, а не начинает его заново.

<?php
declare(strict_types=1);

apcu_store('shop:wrong', '10');
var_dump(apcu_inc('shop:wrong', 1, $ok), $ok);
apcu_store('shop:zero', 0);
var_dump(apcu_inc('shop:zero', 0, $ok), $ok);

bool(false)
bool(false)
int(0)
bool(true)

Строка с цифрами не стала счётчиком int автоматически. Ошибку не исправляют бездумным приведением чужой кеш-записи: сначала проверяют происхождение ключа.

<?php
declare(strict_types=1);

echo apcu_dec('shop:events', 2, $ok, 60), "\n";
echo apcu_dec('shop:events', 3, $ok, 60), "\n";

-2
-5

На отсутствующем ключе исходной величиной служит ноль. Повторный вызов продолжает существующий счётчик, а не начинает его заново.

<?php
declare(strict_types=1);

apcu_store('shop:wrong', '10');
var_dump(apcu_dec('shop:wrong', 1, $ok), $ok);
apcu_store('shop:zero', 0);
var_dump(apcu_dec('shop:zero', 0, $ok), $ok);

bool(false)
bool(false)
int(0)
bool(true)

Строка с цифрами не стала счётчиком int автоматически. Ошибку не исправляют бездумным приведением чужой кеш-записи: сначала проверяют происхождение ключа.

<?php
declare(strict_types=1);

apcu_store('shop:generation', 7);
var_dump(apcu_cas('shop:generation', 7, 8));
var_dump(apcu_cas('shop:generation', 7, 9));
echo apcu_fetch('shop:generation'), "\n";

bool(true)
bool(false)
8

Второй запрос всё ещё думал, что версия равна 7. CAS обнаружил устаревшее ожидание и не затёр 8 значением 9.

<?php
declare(strict_types=1);

var_dump(apcu_cas('shop:missing', 0, 1));
apcu_store('shop:text', '0');
var_dump(apcu_cas('shop:text', 0, 1));
apcu_add('shop:state', 0, 60);
var_dump(apcu_cas('shop:state', 0, 1));

bool(false)
bool(false)
bool(true)

Создание и условная замена — разные действия. add создаёт отсутствующее начальное значение, CAS работает с ожидаемым существующим.

<?php
declare(strict_types=1);

$usable = function_exists('apcu_enabled') && apcu_enabled();
echo $usable ? "Кеш доступен\n" : "Считаем напрямую\n";

Кеш доступен

Сначала function_exists, затем &&: правая часть не выполняется при отсутствующей функции. На хостинге без APCu этот же код выберет вторую строку.

<?php
declare(strict_types=1);

function categoryLabels(): array {
    if (!function_exists('apcu_enabled') || !apcu_enabled()) {
        return ['tools' => 'Инструменты'];
    }
    return apcu_entry('shop:labels', fn(string $key) => ['tools' => 'Инструменты'], 60);
}
echo categoryLabels()['tools'], "\n";

Инструменты

Ускорение не заменяет полезную работу. Для учебной демонстрации источник — фиксированный маленький массив; загрузку большого внешнего источника не стоит держать под глобальной блокировкой entry.

<?php
declare(strict_types=1);

// Выполнять только в отдельном учебном процессе.
apcu_store(['lab:a' => 1, 'lab:b' => 2]);
var_dump(apcu_clear_cache());
var_dump(apcu_exists('lab:a'), apcu_exists('lab:b'));

bool(true)
bool(false)
bool(false)

Команда убирает всё в данном кеше, а не только lab:. На сервере с несколькими приложениями это широкое действие; для одной сущности есть delete.

<?php
declare(strict_types=1);

apcu_store('shop:v1:labels', ['name' => 'Старая схема'], 60);
apcu_store('shop:v2:labels', ['title' => 'Новая схема'], 60);
$labels = apcu_fetch('shop:v2:labels', $found);
echo $labels['title'], "\n";
echo apcu_exists('shop:v1:labels') ? "Старая запись пока существует\n" : "Нет старой записи\n";

Новая схема
Старая запись пока существует

Это альтернатива общему сбросу при смене формата: новое приложение использует новые ключи, прежние удаляются согласно TTL и политике релиза. Пока они существуют, расход памяти остаётся.

<?php
declare(strict_types=1);

apcu_store('shop:17', 'Ключ');
apcu_fetch('shop:17');
apcu_fetch('shop:18');
$info = apcu_cache_info(true);
if ($info === false) throw new RuntimeException('Статистика недоступна');
var_dump($info['num_hits'] >= 1, $info['num_misses'] >= 1);
var_dump(array_key_exists('cache_list', $info));

bool(true)
bool(true)
bool(false)

Счётчики могут расти из других запросов. Здесь проверяем смысл полей, не обещаем фиксированное число попаданий на живом сервере.

<?php
declare(strict_types=1);

apcu_store('lab:catalog', ['Ключ']);
$info = apcu_cache_info(false);
$keys = [];
foreach ($info['cache_list'] as $entry) {
    if (str_starts_with($entry['info'], 'lab:')) $keys[] = $entry['info'];
}
sort($keys);
echo implode(', ', $keys), "\n";

lab:catalog

В APCu 5.1.28 имя записи в cache_list называется info; старые примеры APC с filename/device/типом file не описывают пользовательский кеш этой версии.

<?php
declare(strict_types=1);

apcu_store('shop:labels', ['new' => 'Новый'], 60);
$info = apcu_key_info('shop:labels');
echo $info['ttl'], "\n";
var_dump(apcu_key_info('shop:missing'));

60
NULL

null означает отсутствие метаданных. В обычной обработке запроса достаточно fetch: диагностические вызовы не нужны для каждого чтения.

<?php
declare(strict_types=1);

apcu_store('shop:labels', ['new' => 'Новый']);
$before = apcu_key_info('shop:labels');
apcu_fetch('shop:labels');
$after = apcu_key_info('shop:labels');
echo $after['hits'] - $before['hits'], "\n";

1

В изолированном процессе выполнено одно чтение. При нескольких обработчиках разность может включать их обращения. Метод не резервирует запись от удаления.

<?php
declare(strict_types=1);

$info = apcu_sma_info(true);
if ($info === false) throw new RuntimeException('Память кеша недоступна');
var_dump($info['num_seg'] === 1);
var_dump($info['avail_mem'] > 0, $info['avail_mem'] < $info['seg_size']);

bool(true)
bool(true)
bool(true)

Часть памяти занята служебными структурами ещё до первой пользовательской записи. Размер сегмента не равен полезному объёму значений.

<?php
declare(strict_types=1);

$info = apcu_sma_info(false);
$largest = 0;
foreach ($info['block_lists'] as $blocks) {
    foreach ($blocks as $block) $largest = max($largest, $block['size']);
}
var_dump($largest > 0);
var_dump($largest <= $info['avail_mem']);

bool(true)
bool(true)

Суммарно свободных байт может быть много, но распределение на блоки важно для новой большой записи. Современный APCu умеет уплотнять память; конкретный эффект зависит от версии и нагрузки.

<?php
declare(strict_types=1);

apcu_store(['shop:17' => 'Ключ', 'shop:18' => 'Пила', 'other:1' => 'Чужой раздел']);
$products = [];
foreach (new APCUIterator('~^shop:~', APC_ITER_KEY | APC_ITER_VALUE) as $entry) {
    $products[$entry['key']] = $entry['value'];
}
ksort($products);
foreach ($products as $key => $value) echo "$key: $value\n";

shop:17: Ключ
shop:18: Пила

Итератор читает внутренний порядок хеш-таблицы; сортировку для отчёта мы выполняем отдельно. Регулярное выражение ^shop: означает начало ключа, не поиск текста в значениях.

<?php
declare(strict_types=1);

apcu_store(['shop:17' => 'Ключ', 'shop:18' => 'Пила', 'other:1' => 'Чужой раздел']);
$names = [];
foreach (new APCUIterator(['shop:17', 'shop:18'], APC_ITER_KEY) as $entry) {
    $names[] = $entry['key'];
    if (array_key_exists('value', $entry)) throw new RuntimeException('Лишнее поле');
}
sort($names);
echo implode(', ', $names), "\n";

shop:17, shop:18

Не запрашиваем APC_ITER_VALUE, если нужен только список имён. Это уменьшает копирование и работу сериализатора; сама проверка ключей всё равно имеет стоимость.

<?php
declare(strict_types=1);

apcu_store(['shop:17' => 'Ключ', 'shop:18' => 'Пила', 'other:1' => 'Чужой раздел']);
$iterator = new APCUIterator(['shop:18'], APC_ITER_KEY | APC_ITER_VALUE, 1);
foreach ($iterator as $entry) echo $entry['value'], "\n";

Пила

Порция 1 относится к работе обхода. Список search содержит точный ключ и не требует знания регулярных выражений.

<?php
declare(strict_types=1);

apcu_store(['shop:17' => 'Ключ', 'shop:18' => 'Пила', 'other:1' => 'Чужой раздел']);
$count = 0;
foreach (new APCUIterator('~^shop:~', APC_ITER_KEY, 1) as $entry) $count++;
echo $count, "\n";

2

Получены обе записи, хотя chunk_size равен 1. Такой обход уменьшает длину отдельных удержаний блокировки, но не делает полный большой отчёт бесплатным.

<?php
declare(strict_types=1);

apcu_store('shop:17', 'Ключ');
$it = new APCUIterator(['shop:17'], APC_ITER_VALUE);
$it->rewind();
if ($it->valid()) echo $it->current()['value'], "\n";

Ключ

Сначала убеждаемся, что позиция существует. current не перемещает курсор, поэтому повтор вернёт тот же выбранный элемент до next.

<?php
declare(strict_types=1);

$it = new APCUIterator(['shop:missing']);
try { $it->current(); }
catch (Error $error) { echo "Нет текущей записи\n"; }

Нет текущей записи

В рабочем обходе эту ситуацию предупреждает valid. catch здесь демонстрирует реальное отличие актуального расширения от устаревшего текста справочника.

<?php
declare(strict_types=1);

apcu_store('shop:17', 'Ключ');
$it = new APCUIterator(['shop:17'], APC_ITER_VALUE);
$it->rewind();
if ($it->valid()) echo $it->key(), "\n";

shop:17

key() — метод протокола обхода, а поле current()[key] зависит от маски format. Не путайте их.

<?php
declare(strict_types=1);

apcu_store(['shop:17' => 'Ключ', 'shop:18' => 'Пила', 'other:1' => 'Чужой раздел']);
$keys = [];
foreach (new APCUIterator('~^shop:~', APC_ITER_NONE) as $key => $entry) {
    if ($entry !== []) throw new RuntimeException('Ожидали пустые поля');
    $keys[] = $key;
}
sort($keys);
echo implode(', ', $keys), "\n";

shop:17, shop:18

foreach использует key() для левой части key => entry. Имя доступно без копирования значения записи.

<?php
declare(strict_types=1);

apcu_store('shop:17', 'Ключ');
$it = new APCUIterator(['shop:17']);
$it->rewind();
var_dump($it->valid());
$it->next();
var_dump($it->valid());

bool(true)
bool(false)

Вызов next двигает состояние, а не выводит товар и не возвращает его.

<?php
declare(strict_types=1);

apcu_store(['shop:17' => 'Ключ', 'shop:18' => 'Пила', 'other:1' => 'Чужой раздел']);
$it = new APCUIterator('~^shop:~', APC_ITER_KEY);
$keys = [];
for ($it->rewind(); $it->valid(); $it->next()) $keys[] = $it->key();
sort($keys);
echo implode(', ', $keys), "\n";

shop:17, shop:18

В обычном коде foreach понятнее. Ручная запись нужна для понимания протокола или специального поэтапного обработчика.

<?php
declare(strict_types=1);

apcu_store('shop:17', 'Ключ');
$it = new APCUIterator(['shop:17'], APC_ITER_KEY);
$it->rewind(); echo $it->key(), "\n";
$it->next();
$it->rewind(); echo $it->key(), "\n";

shop:17
shop:17

Объект обхода тот же, позиция восстановлена. Это не повторная вставка в кеш.

<?php
declare(strict_types=1);

apcu_store(['shop:17' => 'Ключ', 'shop:18' => 'Пила', 'other:1' => 'Чужой раздел']);
$it = new APCUIterator('~^shop:~', APC_ITER_KEY);
foreach ([1, 2] as $pass) {
    $count = 0;
    for ($it->rewind(); $it->valid(); $it->next()) $count++;
    echo "$pass: $count\n";
}

1: 2
2: 2

В изолированном примере кеш не меняется. На живом сервере между проходами результаты могут отличаться — rewind не фиксирует снимок.

<?php
declare(strict_types=1);

$it = new APCUIterator(['shop:missing']);
$it->rewind();
echo $it->valid() ? "Есть запись\n" : "Выборка пуста\n";

Выборка пуста

Пустая выборка — нормальный результат поиска, а не сбой PHP.

<?php
declare(strict_types=1);

apcu_store(['shop:17' => 'Ключ', 'shop:18' => 'Пила', 'other:1' => 'Чужой раздел']);
$it = new APCUIterator('~^shop:~', APC_ITER_KEY, 1);
$it->rewind();
$count = 0;
while ($it->valid()) { $count++; $it->next(); }
echo $count, "\n";

2

Без next цикл оставался бы на одном элементе. valid не является обещанием, что исходная кеш-запись никогда не будет удалена конкурентным запросом.

<?php
declare(strict_types=1);

apcu_store(['shop:17' => 'Ключ', 'shop:18' => 'Пила', 'other:1' => 'Чужой раздел']);
$it = new APCUIterator('~^shop:~', APC_ITER_KEY);
echo $it->getTotalCount(), "\n";

2

Фильтр применяется к ключам. Size включает внутреннее представление и служебные расходы записи, а hits — чтения из кеша, не число просмотров страницы целиком.

<?php
declare(strict_types=1);

apcu_store('shop:17', 'Ключ');
$old = new APCUIterator('~^shop:~', APC_ITER_KEY);
$before = $old->getTotalCount(); // Заодно фиксируются hits и size.
apcu_store('shop:18', 'Пила');
$old->rewind();
$fresh = new APCUIterator('~^shop:~', APC_ITER_KEY);
echo $before, ':', $old->getTotalCount(), ':', $fresh->getTotalCount(), "\n";

1:1:2

Это общее правило всех трёх агрегатов. Если нужна текущая административная статистика, нельзя держать один объект и бесконечно перечитывать его сохранённую сводку.

<?php
declare(strict_types=1);

apcu_store(['shop:17' => 'Ключ', 'shop:18' => 'Пила', 'other:1' => 'Чужой раздел']);
$it = new APCUIterator('~^shop:~', APC_ITER_KEY);
apcu_fetch('shop:17');
apcu_fetch('shop:17');
echo $it->getTotalHits(), "\n";

2

Фильтр применяется к ключам. Size включает внутреннее представление и служебные расходы записи, а hits — чтения из кеша, не число просмотров страницы целиком.

<?php
declare(strict_types=1);

apcu_store('shop:17', 'Ключ');
$old = new APCUIterator('~^shop:~', APC_ITER_KEY);
$before = $old->getTotalCount(); // Заодно фиксируются hits и size.
apcu_store('shop:18', 'Пила');
$old->rewind();
$fresh = new APCUIterator('~^shop:~', APC_ITER_KEY);
echo $before, ':', $old->getTotalCount(), ':', $fresh->getTotalCount(), "\n";

1:1:2

Это общее правило всех трёх агрегатов. Если нужна текущая административная статистика, нельзя держать один объект и бесконечно перечитывать его сохранённую сводку.

<?php
declare(strict_types=1);

apcu_store(['shop:17' => 'Ключ', 'shop:18' => 'Пила', 'other:1' => 'Чужой раздел']);
$it = new APCUIterator('~^shop:~', APC_ITER_KEY);
var_dump($it->getTotalSize() > 0);
var_dump($it->getTotalSize() > strlen('Ключ') + strlen('Пила'));

bool(true)
bool(true)

Фильтр применяется к ключам. Size включает внутреннее представление и служебные расходы записи, а hits — чтения из кеша, не число просмотров страницы целиком.

<?php
declare(strict_types=1);

apcu_store('shop:17', 'Ключ');
$old = new APCUIterator('~^shop:~', APC_ITER_KEY);
$before = $old->getTotalCount(); // Заодно фиксируются hits и size.
apcu_store('shop:18', 'Пила');
$old->rewind();
$fresh = new APCUIterator('~^shop:~', APC_ITER_KEY);
echo $before, ':', $old->getTotalCount(), ':', $fresh->getTotalCount(), "\n";

1:1:2

Это общее правило всех трёх агрегатов. Если нужна текущая административная статистика, нельзя держать один объект и бесконечно перечитывать его сохранённую сводку.