Aller au contenu
Documentation

Behavior de mise en cache

Mettez en cache les résultats des méthodes lentes avec un seul attribut. Un behavior #[Cacheable] avec un stockage PSR-16, qui fonctionne sur les classes final, les classes readonly et les méthodes statiques.

Traduit de l’anglais. La page anglaise fait référence. Lire l’original

Votre responsable vous transfère une plainte : la page de paiement met trois secondes à s’afficher. Le profileur désigne une méthode qui interroge un service distant pour obtenir un taux de change à chaque appel, alors que ce taux ne change que quelques fois par jour. La réponse est évidente : le mettre en cache. Toute la question est de savoir où placer le code de cache.

Cette page part du correctif rapide pour arriver à un behavior (comportement) de mise en cache : vous marquez une méthode avec #[Cacheable], et le framework exécute la recherche dans le cache comme middleware autour d’elle. Les termes behavior class (classe de comportement), behavior et matching rule (règle de correspondance) sont expliqués dans le tableau des termes.

Le service lent :

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

Le correctif rapide place le cache dans la méthode :

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

Ça marche, et ça commence à se répandre :

  • La classe a deux rôles. Elle récupère des taux et gère un cache. Chaque test d’ExchangeRates a désormais besoin d’un cache, et la dépendance au cache se propage dans chaque appel du constructeur.
  • Les mêmes lignes sont recopiées dans chaque méthode lente. Chaque copie construit sa propre clé, choisit sa propre durée de vie et gère les absences dans le cache à sa façon. Tôt ou tard, une copie oublie un argument dans la clé et renvoie de mauvaises données.
  • Il n’y a pas d’endroit unique où le modifier. Désactiver le cache le temps d’une série de tests, renommer les clés ou changer de stockage oblige à modifier chaque copie.

Pourquoi les décorateurs et les proxies ne suffisent pas

Section intitulée « Pourquoi les décorateurs et les proxies ne suffisent pas »

La conception orientée objet offre deux réponses classiques, et le code PHP moderne les bloque toutes les deux :

  • Une sous-classe de cache redéfinit les méthodes lentes et appelle parent::rate() quand la valeur est absente du cache. Elle ne peut pas étendre une classe final, et beaucoup de services modernes sont final readonly.
  • Un décorateur enveloppe le service et implémente la même interface. Il lui faut une interface pour chaque service et une méthode de délégation pour chaque méthode, mise en cache ou non. Un proxy générique basé sur __call() épargne la saisie, mais ce n’est plus un ExchangeRates : chaque déclaration de type le rejette.
  • Aucun des deux ne peut mettre en cache une méthode statique. Les appelants nomment directement la classe : il n’y a rien à envelopper.

La logique de cache va dans une seule behavior class, et les méthodes qui en ont besoin sont marquées par un attribut. Quatre petits fichiers.

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

Un attribut PHP ordinaire. Il porte le réglage qui varie d’une méthode à l’autre, la durée de vie en secondes, et ne dépend en rien du 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);
}
}

La méthode tient de nouveau en une ligne, et la classe n’a plus qu’une seule dépendance.

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] exécute le behavior à la place de la méthode. La matching rule @execution(App\Attribute\Cacheable) sélectionne toutes les méthodes qui portent l’attribut. À l’intérieur :

  • La clé nomme la classe, la méthode et les arguments : rate('EUR', 'USD') et rate('USD', 'EUR') ont donc des entrées distinctes. Elle est hachée parce que PSR-16 réserve les caractères {}()/\@: et ne garantit que des clés de 64 caractères au plus.
  • $miss est un objet neuf qu’aucun cache ne peut renvoyer : les méthodes qui renvoient null ou false sont donc mises en cache elles aussi.
  • proceed() exécute la méthode d’origine, uniquement quand la valeur est absente du cache. La durée de vie vient de l’attribut de cette méthode.
  • getScope() renvoie le nom de la classe, pour les appels d’instance comme pour les appels statiques. getThis() vaudrait null pour un appel statique.
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)),
);
}
}

Le cache vient du conteneur de votre application, une fois celui-ci rattaché avec setDelegate() (voir Dépendances). Avec le bridge Symfony, Laravel ou Yii3, vous sautez cette étape : la behavior class est un service autowiré comme un autre (Intégrations). N’importe quelle implémentation PSR-16 convient, par exemple symfony/cache avec 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
  • Les classes final et readonly fonctionnent. La classe garde son nom et sa déclaration final readonly. Les déclarations de type, instanceof et new ExchangeRates(...) restent inchangés, puisqu’aucun objet enveloppe n’existe.

  • Les méthodes statiques fonctionnent aussi, ce qu’aucun décorateur ne sait faire :

    final class Countries
    {
    #[Cacheable(ttl: 86400)]
    public static function all(): array
    {
    // reads a large file
    }
    }
  • Un seul endroit à modifier. Le schéma des clés, le stockage et les règles vivent dans CachingAspect. Marquer ou démarquer une méthode est une modification d’une ligne, dans un diff facile à relire.

  • Vous pouvez le vérifier. vendor/bin/aspect debug:advisor public/index.php --advisor=... liste chaque méthode que sélectionne la règle (voir debug:advisor), et un point d’arrêt dans cache() s’arrête à chaque appel mis en cache.

  • Le coût est faible. Intercepter un appel coûte moins de 1 µs (coûts mesurés), contre des secondes pour un appel distant.

  • Les arguments doivent être sérialisables. serialize() lève une exception pour les closures et pour certains objets. Pour les entités, passez leurs identifiants aux méthodes mises en cache, ou construisez la clé à partir des éléments dont vous avez besoin.
  • L’état de l’objet ne fait pas partie de la clé. Deux instances d’ExchangeRates avec des sources différentes partagent leurs entrées. Si le résultat dépend de l’instance, ajoutez à la clé une valeur qui l’identifie.
  • L’invalidation. La formule de Phil Karlton tient toujours : il n’y a que deux choses difficiles en informatique, l’invalidation de cache et le nommage des choses. Une durée de vie est la politique la plus simple. Quand une donnée doit disparaître dès qu’elle change, utilisez un cache qui gère les tags (par exemple TagAwareCacheInterface de Symfony) et un second behavior sur les méthodes qui écrivent ces données.
  • Restreignez la règle si nécessaire. Combinez l’attribut avec d’autres règles, par exemple @execution(App\Attribute\Cacheable) && within(App\Service\**). La syntaxe est décrite dans Matching rules.

© 2026 Alexander Lisachenko