Pular para o conteúdo
Documentação

Behavior de cache

Coloque em cache os resultados de métodos lentos com um único atributo. Um behavior #[Cacheable] com armazenamento PSR-16 que funciona em classes final, classes readonly e métodos estáticos.

Traduzido do inglês. A página em inglês é a referência. Ler o original

Seu gerente encaminha uma reclamação: a página de checkout leva três segundos. O profiler aponta para um método que consulta um serviço remoto para obter uma taxa de câmbio a cada chamada, embora a taxa mude poucas vezes por dia. A resposta é óbvia: colocar em cache. A parte interessante é onde o código de cache vai ficar.

Esta página vai da correção rápida até um behavior (comportamento) de cache: você marca um método com #[Cacheable], e o framework roda a consulta ao cache como middleware em torno dele. Os termos behavior class (classe de comportamento), behavior e matching rule (regra de correspondência) são explicados na tabela de termos.

O serviço lento:

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
}
}

A correção rápida coloca o cache dentro do método:

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;
}
}

Funciona, e começa a se espalhar:

  • A classe tem duas responsabilidades. Ela busca taxas e gerencia um cache. Todo teste de ExchangeRates agora precisa de um cache, e a dependência do cache viaja para cada chamada do construtor.
  • As mesmas linhas são copiadas em todo método lento. Cada cópia monta sua própria chave, escolhe seu próprio tempo de vida e trata os misses do seu jeito. Mais cedo ou mais tarde, uma cópia esquece um argumento na chave e retorna o dado errado.
  • Não existe um lugar único para mudar. Desligar o cache numa rodada de testes, renomear chaves ou trocar o armazenamento significa editar cada cópia.

O design orientado a objetos tem duas respostas clássicas, e o código PHP moderno bloqueia as duas:

  • Uma subclasse com cache sobrescreve os métodos lentos e chama parent::rate() num miss. Ela não consegue estender uma classe final, e muitos serviços modernos são final readonly.
  • Um decorator envolve o serviço e implementa a mesma interface. Ele exige uma interface para cada serviço e um método de repasse para cada método, com cache ou não. Um proxy genérico com __call() poupa a digitação, mas deixa de ser um ExchangeRates, então todo type hint o rejeita.
  • Nenhum dos dois coloca em cache um método estático. Quem chama cita a classe diretamente, então não há nada para envolver.

A lógica de cache vai para uma behavior class, e os métodos que precisam dela são marcados com um atributo. Quatro arquivos pequenos.

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

Um atributo PHP comum. Ele traz a configuração que muda de um método para outro, o tempo de vida em segundos, e não depende do framework.

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);
}
}

O método volta a ter uma linha, e a classe volta a ter uma única dependência.

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] roda o behavior no lugar do método. A matching rule @execution(App\Attribute\Cacheable) seleciona todo método que tem o atributo. Por dentro:

  • A chave identifica a classe, o método e os argumentos, então rate('EUR', 'USD') e rate('USD', 'EUR') ganham entradas separadas. Ela passa por hash porque a PSR-16 reserva os caracteres {}()/\@: e só garante chaves de até 64 caracteres.
  • $miss é um objeto novo que nenhum cache pode retornar, então métodos que retornam null ou false também ficam em cache.
  • proceed() roda o método original, só num miss. O tempo de vida vem do atributo desse método.
  • getScope() retorna o nome da classe tanto em chamadas de instância quanto em chamadas estáticas. getThis() seria null numa chamada estática.
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)),
);
}
}

O cache vem do container da sua aplicação depois que ele é ligado com setDelegate() (veja Dependências). Com a bridge de Symfony, Laravel ou Yii3, você pula este passo: a behavior class é um serviço com autowiring como qualquer outro (Integrações). Qualquer implementação de PSR-16 serve, por exemplo symfony/cache com 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
  • Classes final e readonly funcionam. A classe mantém seu nome e sua declaração final readonly. Type hints, instanceof e new ExchangeRates(...) não mudam, porque não existe nenhum objeto wrapper.

  • Métodos estáticos também funcionam, o que nenhum decorator consegue:

    final class Countries
    {
    #[Cacheable(ttl: 86400)]
    public static function all(): array
    {
    // reads a large file
    }
    }
  • Um só lugar para mudar. O esquema de chaves, o armazenamento e as regras ficam em CachingAspect. Marcar ou desmarcar um método é uma mudança de uma linha num diff fácil de revisar.

  • Dá para conferir. vendor/bin/aspect debug:advisor public/index.php --advisor=... lista todo método que a regra seleciona (veja debug:advisor), e um breakpoint dentro de cache() para em cada chamada com cache.

  • O custo é pequeno. Interceptar uma chamada custa menos de 1 µs (custos medidos), contra os segundos de uma chamada remota.

  • Os argumentos precisam ser serializáveis. serialize() lança exceção para closures e para alguns objetos. No caso de entidades, passe os identificadores delas para os métodos com cache, ou monte a chave com as partes de que você precisa.
  • O estado do objeto não entra na chave. Duas instâncias de ExchangeRates com fontes diferentes compartilham entradas. Se o resultado depende da instância, adicione à chave um valor que a identifique.
  • Invalidação. A frase de Phil Karlton continua valendo: só existem duas coisas difíceis em ciência da computação, invalidação de cache e dar nome às coisas. Um tempo de vida é a política mais simples. Quando o dado precisa sumir no momento em que muda, use um cache com suporte a tags (por exemplo a TagAwareCacheInterface do Symfony) e um segundo behavior nos métodos que gravam o dado.
  • Restrinja a regra se precisar. Combine o atributo com outras regras, por exemplo @execution(App\Attribute\Cacheable) && within(App\Service\**). A sintaxe está em Matching rules.

© 2026 Alexander Lisachenko