English | العربية | বাংলা | Bosanski | Deutsch | Español | Français | हिन्दी | Italiano | 日本語 | 한국어 | मराठी | Português | Русский | Kiswahili | தமிழ் | తెలుగు | Türkçe | اردو | Tiếng Việt | 中文

• Введение
  • Основные возможности
  • Пример
• Установка
  • Требования
• Использование
  • Основная настройка
  • Как это работает
  • Интеграция с Octane
• Конфигурация
  • Включить/выключить
  • Хранилище Redis
  • Префиксы кэша
  • Конфигурация локального кэша
  • Слушатели Octane
• Расширенное использование
  • Обработка недействительностей вручную
  • Очистка локального кэша
  • Управление соединениями
• Оптимизация
  • Ограничения запросов рабочего процесса
  • Селективное кэширование с префиксами
  • Учет памяти
• Общие паттерны
  • Конфигурация приложения
  • Часто запрашиваемые справочные данные
  • Альтернатива тегам кэша
• Ограничения
  • Режим кластера Redis
• Руководство по поддержке
  • Поддержка, основанная на сообществе
  • Ошибки и приоритизация функций
• Лицензия - MIT Лицензия

🔗Введение

Recall — это высокопроизводительный пакет клиентского кэширования Redis для Laravel. Он использует возможность клиентского кэширования Redis 6 с автоматической недействительностью для значительного снижения количества обращений к Redis и задержки. Построен специально для сред Laravel Octane, он использует APCu или Swoole Table в качестве локального кэш-слоя, который остается синхронизированным с Redis через сообщения об недействительности.

Когда вы извлекаете значение из Redis, Recall сохраняет его локально. Когда это значение изменяется в Redis (с любого клиента), Redis автоматически уведомляет Recall о недействительности локальной копии. Это дает вам скорость кэширования в памяти с гарантиями согласованности Redis.

🔗Основные возможности

• Автоматическая недействительность: Redis уведомляет ваше приложение, когда изменяются закэшированные ключи, что обеспечивает согласованность кэша.
• Ноль конфигурации: Работает из коробки с разумными значениями по умолчанию.
• Интеграция с Octane: Автоматическая подготовка подключения, обработка недействительности на основе запросов и гладкое завершение работы.
• Поддержка двух драйверов: APCu для всех серверов Octane, Swoole Table для сред Swoole/OpenSwoole.
• Селективное кэширование: Настройка, какие префиксы ключей кешировать локально.
• Защита от условий гонки: Отслеживание ожидающих запросов предотвращает кэширование устаревших данных во время одновременной недействительности.

🔗Пример

// Настройте recall как ваш драйвер кэширования
// config/cache.php
'stores' => [
    'recall' => [
        'driver' => 'recall',
    ],
],
 
// Используйте его как любой кэш Laravel
use Illuminate\Support\Facades\Cache;
 
// Первый вызов: извлечение из Redis, хранение локально
$user = Cache::store('recall')->get('user:1');
 
// Последующие вызовы: предоставляются из локального APCu/Swoole Table (микросекунды)
$user = Cache::store('recall')->get('user:1');
 
// Когда user:1 обновляется где-либо, Redis уведомляет Recall о недействительности
Cache::store('recall')->put('user:1', $newUserData, 3600);
// Локальный кэш автоматически становится недействительным на всех рабочих процессах

🔗Установка

Установите пакет через Composer:

composer require defectivecode/laravel-recall

🔗Требования

• PHP >= 8.4
• Laravel 11.x или 12.x
• Laravel Octane
• Redis 6.0+ (для поддержки клиентского кэширования)
• ext-apcu ИЛИ ext-swoole (необходимо хотя бы одно для локального кэша)

🔗Использование

🔗Основная настройка

1. Добавьте хранилище кэша Recall в ваш config/cache.php:

'stores' => [
    // ... другие хранилища
 
    'recall' => [
        'driver' => 'recall',
    ],
],

2. Используйте хранилище кэша в своем приложении:

use Illuminate\Support\Facades\Cache;
 
// Сохранить значение (запись в Redis)
Cache::store('recall')->put('key', 'value', 3600);
 
// Извлечь значение (первый вызов обращается к Redis, последующие вызовы используют локальный кэш)
$value = Cache::store('recall')->get('key');
 
// Удалить значение
Cache::store('recall')->forget('key');

🔗Как это работает

1. Первое чтение: Значение извлекается из Redis и сохраняется в локальном кэше APCu/Swoole Table.
2. Последующие чтения: Значение предоставляется непосредственно из локальной памяти (подмиллисекунды).
3. Запись где угодно: Когда любой клиент модифицирует ключ в Redis, Redis отправляет сообщение о недействительности.
4. Автоматическая недействительность: Recall получает сообщение и удаляет ключ из локального кэша.
5. Следующее чтение: Новое значение извлекается из Redis и снова кэшируется локально.

Этот паттерн особенно мощен в средах Laravel Octane, где рабочие процессы сохраняются между запросами, позволяя локальному кэшу накапливаться и обслуживать множество запросов из памяти.

🔗Интеграция с Octane

Recall автоматически интегрируется с Laravel Octane, когда он доступен:

• Запуск рабочего процесса: Устанавливает соединение для недействительности Redis (теплый старт).
• Получение запроса: Обрабатывает любые ожидающие сообщения об недействительности.
• Остановка рабочего процесса: Гладкое закрытие соединений.

Дополнительная конфигурация не требуется. Интеграция происходит автоматически, когда установлен Octane.

🔗Конфигурация

Опубликуйте файл конфигурации:

php artisan vendor:publish --tag=recall-config

Это создаст config/recall.php со следующими параметрами:

🔗Включить/выключить

'enabled' => env('RECALL_ENABLED', true),

Когда отключено, Recall передает запросы непосредственно в Redis, не используя локальный кэш. Полезно для отладки или постепенного разворачивания.

🔗Хранилище Redis

'redis_store' => env('RECALL_REDIS_STORE', 'redis'),

Хранилище кэша Laravel для операций Redis. Это должно ссылаться на хранилище Redis, сконфигурированное в вашем config/cache.php.

🔗Префиксы кэша

'cache_prefixes' => [],

Кэшируйте только ключи, соответствующие этим префиксам, локально. Оставьте пустым, чтобы кэшировать все ключи.

// Кэшируйте только ключи пользователей и настроек локально
'cache_prefixes' => ['users:', 'settings:', 'config:'],

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

🔗Конфигурация локального кэша

'local_cache' => [
    // Драйвер: "apcu" или "swoole"
    'driver' => env('RECALL_LOCAL_DRIVER', 'apcu'),
 
    // Префикс для локальных ключей кэша
    'key_prefix' => env('RECALL_LOCAL_PREFIX', 'recall:'),
 
    // Стандартный TTL в секундах (страховочная мера, если недействительность пропущена)
    'default_ttl' => (int) env('RECALL_LOCAL_TTL', 3600),
 
    // Размер Swoole Table (степень 2, только для драйвера swoole)
    'table_size' => (int) env('RECALL_SWOOLE_TABLE_SIZE', 65536),
 
    // Максимум байтов на значение в Swoole Table (только для драйвера swoole)
    'value_size' => (int) env('RECALL_SWOOLE_VALUE_SIZE', 8192),
],

Драйвер APCu (По умолчанию)

Драйвер APCu работает со всеми окружениями PHP и серверами Octane (Swoole, RoadRunner, FrankenPHP). Он хранит закэшированные значения в общей памяти, доступной для всех процессов PHP.

Требования:

• установлен и включен ext-apcu
• apc.enable_cli=1 в php.ini для использования в CLI

Драйвер Swoole Table

Драйвер Swoole Table использует общие таблицы памяти Swoole, обеспечивая постоянный доступ через корутины в одном и том же рабочем процессе. Лучше всего подходит для сред Swoole/OpenSwoole.

Советы по конфигурации:

• table_size: Должен быть степенью 2 (например, 65536, 131072). Определяет максимальное количество записей.
• value_size: Максимум байтов для сериализованных значений. Более крупные значения безмолвно обрезаются.

🔗Слушатели Octane

'listeners' => [
    // Теплое соединение при старте рабочего процесса (уменьшает задержку первого запроса)
    'warm' => env('RECALL_LISTEN_WARM', true),
 
    // Обработка недействительностей на событиях тика (более отзывчиво, небольшие накладные расходы)
    'tick' => env('RECALL_LISTEN_TICK', false),
],

Теплые соединения

Когда включено, Recall устанавливает подписку на недействительность Redis, когда рабочий процесс Octane запускается. Это устраняет задержку соединения на первом запросе.

Обработка тиков

Когда включено, Recall обрабатывает сообщения о недействительности на событиях тика Octane в дополнение к событиям запросов. Это обеспечивает более отзывчивую недействительность кэша при небольших дополнительных накладных расходах.

🔗Расширенное использование

🔗Обработка недействительностей вручную

Если вам нужно вручную обработать недействительности (например, в длительном процессе):

use DefectiveCode\Recall\RecallManager;
 
$manager = app(RecallManager::class);
$manager->processInvalidations();

🔗Очистка локального кэша

Чтобы очистить только локальный кэш без затрагивания Redis:

use DefectiveCode\Recall\RecallManager;
 
$manager = app(RecallManager::class);
$manager->flushLocalCache();

🔗Управление соединениями

use DefectiveCode\Recall\RecallManager;
 
$manager = app(RecallManager::class);
 
// Проверьте, подключена ли подписка на недействительность
if ($manager->isConnected()) {
    // ...
}
 
// Вручную отключить
$manager->disconnect();

🔗Оптимизация

🔗Ограничения запросов рабочего процесса

Laravel Octane циклирует рабочие процессы после настраиваемого количества запросов, чтобы предотвратить утечки памяти. Когда рабочий процесс циклируется, его локальный кэш очищается. Увеличение этого лимита позволяет локальному кэшу Recall сохраняться дольше, улучшая показатели попадания кэша.

В вашем config/octane.php:

// По умолчанию 500 запросов перед циклом
'max_requests' => 10000,

Более высокие значения означают лучшее использование кэша, но требуют уверенности в том, что ваше приложение не имеет утечек памяти. Следите за использованием памяти вашего рабочего процесса, изменяя это значение.

🔗Селективное кэширование с префиксами

Используйте cache_prefixes, чтобы контролировать, какие ключи кэшируются локально. Это особенно ценно, когда:

• Ключи с высокой частотой изменений: Некоторые ключи изменяются так часто, что локальное кэширование дает мало пользы.
• Большие значения: Уменьшите нагрузку на память, кэшируя только более мелкие, часто читаемые ключи.
• Конфиденциальные данные: Храните определенные данные только в Redis по соображениям безопасности или соответствия.

// config/recall.php
'cache_prefixes' => [
    'users:',      // Кэшируйте пользовательские данные локально
    'settings:',   // Кэшируйте настройки приложения
    'products:',   // Кэшируйте каталог продуктов
],

Ключи, не соответствующие этим префиксам, все равно будут работать, но будут обходить локальное кэширование, обращаясь напрямую к Redis.

🔗Учет памяти

Память APCu

APCu делит память между всеми процессами PHP. Настройте лимит памяти в php.ini:

; По умолчанию 32MB, увеличьте для больших нужд кэша
apc.shm_size = 128M

Следите за использованием APCu с помощью apcu_cache_info():

$info = apcu_cache_info();
$memory = $info['mem_size']; // Текущая память в байтах

Размерирование Swoole Table

Таблицы Swoole имеют фиксированную емкость, настраиваемую при создании. Планируйте ожидаемый размер вашего кэша:

'local_cache' => [
    // Максимальное количество записей (должно быть степенью 2)
    'table_size' => 65536,  // 64K записей
 
    // Максимальный размер сериализованного значения в байтах
    'value_size' => 8192,   // 8KB на значение
],

Использование памяти: table_size × (value_size + накладные расходы). Таблица с 65536 записями и 8KB значениями использует примерно 512MB.

🔗Общие паттерны

🔗Конфигурация приложения

// Кэшируйте флаги и настройки функций
$features = Cache::store('recall')->remember('config:features', 3600, function () {
    return Feature::all()->pluck('enabled', 'name')->toArray();
});
 
// Когда настройки изменяются, все рабочие процессы автоматически получают обновления

🔗Часто запрашиваемые справочные данные

// Кэшируйте категории продуктов
$categories = Cache::store('recall')->remember('categories:all', 3600, function () {
    return Category::with('children')->whereNull('parent_id')->get();
});
 
// Кэшируйте валютные курсы
$rates = Cache::store('recall')->remember('rates:exchange', 300, function () {
    return ExchangeRate::all()->pluck('rate', 'currency')->toArray();
});

🔗Альтернатива тегам кэша

Recall не поддерживает теги кэша, но вы можете достичь подобной функциональности с помощью префиксов:

// Вместо тегов используйте согласованные префиксы
Cache::store('recall')->put("blog:posts:{$id}", $post, 3600);
Cache::store('recall')->put("blog:comments:{$postId}", $comments, 3600);
 
// Очистите весь кэш, связанный с блогом, по префиксу (требуется ручная реализация)
// Либо полагайтесь на автоматическую недействительность, когда данные изменяются

🔗Ограничения

🔗Режим кластера Redis

Recall не поддерживает режим кластера Redis. Опция REDIRECT команды CLIENT TRACKING требует, чтобы как соединение данных, так и соединение подписчика недействительности находились на одном и том же узле Redis. В кластере ключи распределяются по нескольким узлам на основе хэш-слотов, что делает невозможным получение недействительностей для ключей, хранящихся на разных узлах.

Для развертываний Redis в кластере рассмотрите возможность:

• Использования единственного экземпляра Redis для кэшируемых данных, которые выигрывают от клиентского кэширования.
• Использования Redis Cluster для других данных, при этом сохраняя часто читаемые, стабильные данные на отдельном экземпляре.

🔗Руководство по поддержке

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

🔗Поддержка, основанная на сообществе

Наш проект с открытым исходным кодом поддерживается нашим замечательным сообществом. Если у вас есть вопросы или требуется помощь, StackOverflow и другие онлайн-ресурсы — ваши лучшие помощники.

🔗Ошибки и приоритизация функций

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

1. Ошибки, влияющие на наши платные продукты

Ошибки, которые затрагивают наши платные продукты, всегда будут нашим приоритетом. В некоторых случаях мы можем рассматривать только те ошибки, которые влияют на нас напрямую.

2. Запросы на внесение изменений от сообщества

Если вы выявили ошибку и у вас есть решение, пожалуйста, отправьте запрос на внесение изменений. После вопросов, касающихся наших продуктов, мы придаем следующий высокий приоритет этим исправлениям, инициированным сообществом. После проверки и одобрения мы объединим ваше решение и отметим ваш вклад.

3. Финансовая поддержка

Для вопросов за пределами упомянутых категорий вы можете выбрать финансирование их решения. Каждая открытая проблема связана с формой заказа, через которую вы можете внести финансовый вклад. Мы приоритизируем эти вопросы на основе суммы финансирования.

Вклад сообщества

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

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

🔗Лицензия - MIT Лицензия

Авторские права © Defective Code, LLC. Все права защищены

Настоящим предоставляется разрешение, безвозмездно, любому лицу, получающему копию этого программного обеспечения и сопутствующих документационных файлов (далее «Программное обеспечение»), пользоваться Программным обеспечением без ограничений, включая, но не ограничиваясь правами использовать, копировать, изменять, сливать, публиковать, распространять, предоставлять сублицензии и/или продавать копии Программного обеспечения, а также разрешать лицам, которым предоставляется Программное обеспечение, делать это, при соблюдении следующих условий:

Указанные выше авторские права и данное разрешение должны быть включены во все копии или значительные части Программного обеспечения.

ПРОГРАММНОЕ ОБЕСПЕЧЕНИЕ ПРЕДОСТАВЛЯЕТСЯ «КАК ЕСТЬ», БЕЗ ГАРАНТИЙ ЛЮБОГО ВИДА, ЯВНЫХ ИЛИ ИМПЛИЦИТНЫХ, ВКЛЮЧАЯ, НО НЕ ОГРАНИЧИВАЯСЬ, ГАРАНТИЯМИ ТОРГОВОЙ ПРИГОДНОСТИ, ПРИГОДНОСТИ ДЛЯ ОПРЕДЕЛЁННЫХ ЦЕЛЕЙ И НАРУШЕНИЯ ПРАВ. В НИКАКОМ СЛУЧАЕ АВТОРЫ ИЛИ ДЕРЖАТЕЛИ АВТОРСКИХ ПРАВ НЕ НЕСУТ ОТВЕТСТВЕННОСТЬ ЗА ЛЮБЫЕ ИСКИ, УЩЕРБ ИЛИ ДРУГИЕ ОБЯЗАТЕЛЬСТВА, НИ В КАКОМ УКАЗАНИИ, ДОГОВОРЕ, ДЕЛИКТЕ ИЛИ ИНОМ, ВЫТЕКАЮЩИЕ ИЗ, ИЛИ В СВЯЗИ С ПРОГРАММНЫМ ОБЕСПЕЧЕНИЕМ ИЛИ ИСПОЛЬЗОВАНИЕМ ИЛИ ДРУГИМИ СДЕЛКАМИ С ПРОГРАММНЫМ ОБЕСПЕЧЕНИЕМ.