README

Удобная обёртка для работы с кешем в Битрикс через fluent interface или по PSR-16. Защита от "cache stampede" ("давки в кеше") по PSR-6: Caching Interface

Возможности

Основное назначение этой библиотеки - максимальное ускорение написания кода, требующего использования кеширования. Дополнительное - защита от "давки в кеше"("cache stampede" или "dog piling") для высоконагруженных проектов методами "блокировки"("locking") и "вероятностного преждевременного устаревания"("probabilistic early expiration"), адаптированная из Symfony Cache 5.1.

запись, чтение, валидация и удаление закешированной информации через fluent interface с поддержкой всех Битрикс-специфичных параметров:
- baseDir
- path
- тегированный кеш (в том числе теги инфоблоков)
кеширование результата выполнения замыкания
поддержка интерфейса Psr\SimpleCache\CacheInterface по PSR-16: Common Interface for Caching Libraries
адаптер AntiStampedeCacheAdapter с двойной защитой от "давки в кеше", соответствующий PSR-6: Caching Interface и Symfony Cache Contracts

Под "капотом" только Bitrix\Main\Data\Cache и Bitrix\Main\Data\TaggedCache из ядра D7.

Установка

Установить через composer:

composer require webarchitect609/bitrix-cache

Добавить подключение автозагрузчика composer в самое начало файла init.php
```
require_once $_SERVER['DOCUMENT_ROOT'] . '/../../vendor/autoload.php';
```

Помочь проекту

Вы можете использовать эту библиотеку совершенно бесплатно, а можете поблагодарить автора за проделанную работу и поддержать желание делать новые полезные проекты:

ЮMoney

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

Для ленивых и торопливых:

use WebArch\BitrixCache\Cache;

$result = Cache::create()
               ->callback(
                   function () {
                       /**
                        * Результат выполнения кода здесь
                        * кешируется на 1 час.
                        */
                       return date(DATE_ISO8601);
                   }
               );

Кеширование с использованием замыкания.

use WebArch\BitrixCache\Cache;

$result = Cache::create()
               ->setPath('/myPath')
               ->setKey('myKey')
               ->setTTL(60)
               ->callback(
                   function () {
                       /**
                        * Результат выполнения этого
                        * замыкания кешируется.
                        */
                       return date(DATE_ISO8601);
                   }
               );

Сброс кеша по key.

Для очистки кеша из предыдущего примера необохдимо вызвать метод delete(string $key), предварительно установив path и baseDir соответствующие ранее созданному кешу(по умолчанию baseDir === 'cache').
```
use WebArch\BitrixCache\Cache;

Cache::create()
     ->setPath('/myPath')
     ->delete('myKey');
```

Запись тегированного кеша.

Кеш по пути /myPath будет снабжён двумя тегами: myTag и тегом инфоблока iblock_id_1.

use WebArch\BitrixCache\Cache;

$result = Cache::create()
               ->setPath('/myPath')
               ->addTag('myTag')
               ->addIblockTag(1)
               ->callback(
                   function () {
                       return date(DATE_ISO8601);
                   }
               );

Тег кеша также можно установить внутри замыкания:

use WebArch\BitrixCache\Cache;

$cache = Cache::create();
$result = $cache->callback(
                    function () use($cache) {
                        $cache->addTag('closureTag');

                        return date(DATE_ISO8601);
                    }
                );

Удаление тегированного кеша.

Кеш из предыдущего примера может быть очищен по тегу. Важно, что при очистке по тегу не требуется устанавливать никакие другие параметры.
```
use WebArch\BitrixCache\Cache;

Cache::create()
     ->clearByTag('myTag'); 
```

Использование всех возможностей fluent-интерфейса.

В результате запись ведётся не в папку cache, а в папку myBaseDir по пути /myPath с ключом myKey на 60 секунд и только с тегом TheOnlyTag, т.к. все предыдущие теги были сброшены вызовом clearTags()

use WebArch\BitrixCache\Cache;

$result = Cache::create()
               ->setBaseDir('myBaseDir')
               ->setPath('/myPath')
               ->setKey('myKey')
               ->setTTL(60)
               ->addIblockTag(2)
               ->addTag('myTagOne')
               ->addTag('myTagTwo')
               ->clearTags()
               ->addTag('TheOnlyTag')
               ->callback(
                   function () {
                       return date(DATE_ISO8601);
                   }
               );

Отмена записи кеша в момент исполнения замыкания.

Метод abort() используется для предотвращения записи кеша вне зависимости от того, что вернёт замыкание.

use WebArch\BitrixCache\Cache;
    
$cache = Cache::create();
$result = $cache->callback(
                    function () use ($cache) {
                        /**
                         * Например, API вернул ответ, что товар не найден.
                         */
                        $productNotFound = true;
                        if($productNotFound){
                            $cache->abort();
                        }

                        return date(DATE_ISO8601);
                    }
                );

Задание TTL в виде интервала DateInterval.

В результате значение будет закешировано на 1 месяц и 15 минут.

use WebArch\BitrixCache\Cache;

$result = Cache::create()
               ->setTTLInterval(new DateInterval('P1MT15M'))
               ->callback(
                   function () {
                       return date(DATE_ISO8601);
                   }
               );

Задание TTL к заданному времени.

В результате значение будет закешировано до 31 декабря 2020. Но если указанная дата и время уже прошли, будет ошибка. Метод полезен, чтобы, например, задавать время жизни кеша по дате окончания активности.
```
use WebArch\BitrixCache\Cache;

Cache::create()
     ->setExpirationTime(new DateTimeImmutable('2020-12-30T23:59:59', new DateTimeZone('+03:00')))
     ->set('myKey', 'someValue');
```

Использование PSR-16.

Все методы по PSR-16 работают только внутри указанных baseDir и path. Т.е. вызов clear() не очистит полностью весь кеш Битрикс.

use WebArch\BitrixCache\Cache;

$cache = Cache::create()
             ->setBaseDir('myBaseDir')
             ->setPath('/myPath');

$cache->set('myKey', 'myValue', 86400);
$result = $cache->get('myKey', 'defaultValue');
$cache->delete('myKey');
$cache->clear();
$cache->setMultiple(
   [
       'key1' => 'value1',
       'key2' => 'value2',
   ]
);
$multipleResult = $cache->getMultiple(['key1', 'key2', 'key3'], 'defaultValueForMissingMultiple');
$cache->deleteMultiple(['key1', 'key2', 'key3', 'key4']);
/**
* Внимание! Этот метод можно использовать только для прогрева кеша. См. примечание к методу.
*/
$cache->has('key2');

Защита от "давки в кеше"

Отдельно должен быть собран адаптер, обслуживающий кеш с защитой от "давки".

use \WebArch\BitrixCache\AntiStampedeCacheAdapter;

$path = '/some/path';
$defaultLifetime = 60;
$baseDir = 'someBaseDir';
$cacheAdapter = new AntiStampedeCacheAdapter($path, $defaultLifetime, $baseDir);

Затем следует использовать этот адаптер в тех местах кода, где такая защита требуется.

use \WebArch\BitrixCache\AntiStampedeCacheAdapter;
use \WebArch\BitrixCache\CacheItem;

/** @var AntiStampedeCacheAdapter $cacheAdapter */
$cacheAdapter->get(
    'myKey',
    function (CacheItem $cacheItem) {
        $cacheItem->expiresAfter(3600);
        
        return date(DATE_ISO8601);
    }
);

Дополнительная информация описана в документации компонента Symfony Cache и соглашения Cache Contracts.

Известные особенности

Очистка кеша

Метод \WebArch\BitrixCache\Cache::clear() очищает кеш только внутри $baseDir и подкаталога $path. Эти параметры относятся только к Битрикс и никак не описаны в PSR-16.

Лицензия и информация об авторах

BSD-3-Clause

webarchitect609 / bitrix-cache

Maintainers

Details