Перейти к содержимому
Документация

Кеширование результатов

Кешируйте результаты медленных методов одним атрибутом. Поведение #[Cacheable] с хранилищем PSR-16, которое работает с final- и readonly-классами и статическими методами.

Перевод с английского. Эталоном считается английская версия страницы. Читать оригинал

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

На этой странице мы пройдём путь от быстрого решения до behavior (поведения) для кеширования: вы помечаете метод атрибутом #[Cacheable], и фреймворк выполняет поиск в кеше как middleware (промежуточный слой) вокруг этого метода. Слова behavior class (класс поведений), behavior и matching rule (правило выбора) объяснены в таблице терминов.

Медленный сервис:

src/Service/ExchangeRates.php
final readonly class ExchangeRates
{
public function __construct(private RateSource $source) {}
public function rate(string $from, string $to): float
{
return $this->source->fetch($from, $to); // a remote call, ~1 s
}
}

Быстрое решение кладёт кеш прямо в метод:

src/Service/ExchangeRates.php
use Psr\SimpleCache\CacheInterface;
final readonly class ExchangeRates
{
public function __construct(
private RateSource $source,
private CacheInterface $cache,
) {}
public function rate(string $from, string $to): float
{
$key = "rate.$from.$to";
$rate = $this->cache->get($key);
if ($rate === null) {
$rate = $this->source->fetch($from, $to);
$this->cache->set($key, $rate, 600);
}
return $rate;
}
}

Это работает — и начинает расползаться:

  • У класса две обязанности. Он получает курсы и управляет кешем. Каждому тесту ExchangeRates теперь нужен кеш, а зависимость от кеша проникает в каждый вызов конструктора.
  • Одни и те же строки копируются в каждый медленный метод. Каждая копия строит свой ключ, выбирает своё время жизни и по-своему обрабатывает промахи. Рано или поздно одна из копий забудет включить аргумент в ключ и вернёт чужие данные.
  • Нет единого места для изменений. Чтобы отключить кеш на время тестов, переименовать ключи или сменить хранилище, придётся править каждую копию.

Почему декораторы и прокси не справляются

Заголовок раздела «Почему декораторы и прокси не справляются»

У объектно-ориентированного проектирования есть два классических ответа, и современный PHP-код блокирует оба:

  • Кеширующий подкласс переопределяет медленные методы и при промахе вызывает parent::rate(). Унаследоваться от final-класса он не может, а многие современные сервисы объявлены как final readonly.
  • Декоратор оборачивает сервис и реализует тот же интерфейс. Ему нужен интерфейс для каждого сервиса и пробрасывающий метод для каждого метода, кешируется тот или нет. Универсальный прокси на __call() избавляет от набора кода, но уже не является ExchangeRates, поэтому его отвергает каждая подсказка типа.
  • Ни тот, ни другой не закеширует статический метод. Вызывающий код обращается к классу напрямую, так что оборачивать нечего.

Логика кеширования переезжает в один behavior class, а методы, которым она нужна, помечаются атрибутом. Четыре небольших файла.

src/Attribute/Cacheable.php
namespace App\Attribute;
use Attribute;
#[Attribute(Attribute::TARGET_METHOD)]
final readonly class Cacheable
{
public function __construct(public int $ttl = 300) {}
}

Обычный PHP-атрибут. Он хранит настройку, которая отличается от метода к методу, — время жизни в секундах — и не зависит от фреймворка.

src/Service/ExchangeRates.php
use App\Attribute\Cacheable;
final readonly class ExchangeRates
{
public function __construct(private RateSource $source) {}
#[Cacheable(ttl: 600)]
public function rate(string $from, string $to): float
{
return $this->source->fetch($from, $to);
}
}

Метод снова занимает одну строку, а у класса снова одна зависимость.

src/Aspect/CachingAspect.php
namespace App\Aspect;
use App\Attribute\Cacheable;
use Go\Aop\Aspect;
use Go\Aop\Intercept\MethodInvocation;
use Go\Lang\Attribute\Around;
use Psr\SimpleCache\CacheInterface;
final class CachingAspect implements Aspect
{
public function __construct(private readonly CacheInterface $cache) {}
#[Around('@execution(App\Attribute\Cacheable)')]
public function cache(MethodInvocation $invocation): mixed
{
$method = $invocation->getMethod();
$key = 'call.' . hash('xxh128', $invocation->getScope() . '::' . $method->name . serialize($invocation->getArguments()));
$miss = new \stdClass();
$value = $this->cache->get($key, $miss);
if ($value !== $miss) {
return $value;
}
$ttl = $method->getAttributes(Cacheable::class)[0]->newInstance()->ttl;
$value = $invocation->proceed();
$this->cache->set($key, $value, $ttl);
return $value;
}
}

#[Around] выполняет behavior вместо метода. Matching rule @execution(App\Attribute\Cacheable) выбирает каждый метод с этим атрибутом. Внутри:

  • Ключ включает класс, метод и аргументы, поэтому rate('EUR', 'USD') и rate('USD', 'EUR') получают отдельные записи. Ключ хешируется, потому что PSR-16 резервирует символы {}()/\@: и гарантирует поддержку ключей длиной только до 64 символов.
  • $miss — свежий объект, который никакой кеш не может вернуть, поэтому кешируются и методы, возвращающие null или false.
  • proceed() выполняет исходный метод — только при промахе. Время жизни берётся из атрибута на этом методе.
  • getScope() возвращает имя класса и для вызовов на экземпляре, и для статических вызовов. getThis() для статического вызова вернул бы null.
src/AppKernel.php
use App\Aspect\CachingAspect;
use Go\Core\AspectContainer;
use Go\Core\AspectKernel;
use Psr\SimpleCache\CacheInterface;
final class AppKernel extends AspectKernel
{
protected function configureAop(AspectContainer $container): void
{
$container->addLazyService(
CachingAspect::class,
static fn(AspectContainer $c) => new CachingAspect($c->getService(CacheInterface::class)),
);
}
}

Кеш берётся из контейнера вашего приложения, как только тот подключён через setDelegate() (см. Зависимости). С мостом (bridge) для Symfony, Laravel или Yii3 этот шаг не нужен: behavior class — такой же автоматически связываемый (autowired) сервис, как любой другой (Интеграции). Подойдёт любая реализация PSR-16, например symfony/cache с Psr16Cache.

$rates->rate('EUR', 'USD'); // calls the remote service, stores the result for 600 s
$rates->rate('EUR', 'USD'); // returns the stored rate
$rates->rate('USD', 'EUR'); // other arguments: calls the remote service
  • Final- и readonly-классы работают. Класс сохраняет своё имя и объявление final readonly. Подсказки типов, instanceof и new ExchangeRates(...) не меняются, потому что объекта-обёртки не существует.

  • Статические методы тоже работают, чего не умеет ни один декоратор:

    final class Countries
    {
    #[Cacheable(ttl: 86400)]
    public static function all(): array
    {
    // reads a large file
    }
    }
  • Одно место для изменений. Схема ключей, хранилище и правила живут в CachingAspect. Пометить метод или снять пометку — изменение в одну строку, которое легко проверить на ревью.

  • Это можно проверить. vendor/bin/aspect debug:advisor public/index.php --advisor=... выводит все методы, которые выбирает правило (см. debug:advisor), а точка останова внутри cache() срабатывает на каждом кешируемом вызове.

  • Цена невелика. Перехват вызова стоит меньше 1 мкс (измеренные затраты) против секунд удалённого вызова.

  • Аргументы должны сериализоваться. serialize() выбрасывает исключение для замыканий и некоторых объектов. Для сущностей передавайте в кешируемые методы их идентификаторы или стройте ключ из нужных частей.
  • Состояние объекта не входит в ключ. Два экземпляра ExchangeRates с разными источниками делят одни и те же записи. Если результат зависит от экземпляра, добавьте в ключ значение, которое его идентифицирует.
  • Инвалидация. Фраза Фила Карлтона по-прежнему верна: в информатике есть только две трудные вещи — инвалидация кеша и придумывание имён. Время жизни — самая простая политика. Если данные должны исчезать в момент изменения, используйте кеш с поддержкой тегов (например, TagAwareCacheInterface из Symfony) и второй behavior на методах, которые эти данные записывают.
  • При необходимости сузьте правило. Комбинируйте атрибут с другими правилами, например @execution(App\Attribute\Cacheable) && within(App\Service\**). Синтаксис описан в разделе Matching rules.

© 2026 Alexander Lisachenko