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 problema
Seção intitulada “O problema”O serviço lento:
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:
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
ExchangeRatesagora 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.
Por que decorators e proxies não bastam
Seção intitulada “Por que decorators e proxies não bastam”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 classefinal, e muitos serviços modernos sãofinal 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 umExchangeRates, 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.
O behavior de cache
Seção intitulada “O behavior de cache”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.
1. O atributo
Seção intitulada “1. O atributo”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.
2. Marque o método
Seção intitulada “2. Marque o método”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.
3. A behavior class
Seção intitulada “3. A behavior class”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')erate('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 retornamnulloufalsetambé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()serianullnuma chamada estática.
4. Registre a behavior class
Seção intitulada “4. Registre a behavior class”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.
O que você ganha
Seção intitulada “O que você ganha”$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,instanceofenew 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 decache()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.
Detalhes a decidir
Seção intitulada “Detalhes a decidir”- 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
ExchangeRatescom 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
TagAwareCacheInterfacedo 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
