Zum Inhalt springen
Dokumentation

Caching-Behavior

Cachen Sie die Ergebnisse langsamer Methoden mit einem einzigen Attribut. Ein #[Cacheable]-Behavior mit PSR-16-Storage, das mit finalen Klassen, readonly-Klassen und statischen Methoden funktioniert.

Aus dem Englischen übersetzt. Maßgeblich ist die englische Seite. Original lesen

Ihr Manager leitet eine Beschwerde weiter: Die Checkout-Seite braucht drei Sekunden. Der Profiler zeigt auf eine Methode, die bei jedem Aufruf einen entfernten Dienst nach einem Wechselkurs fragt, obwohl sich der Kurs nur ein paar Mal am Tag ändert. Die Antwort liegt auf der Hand: cachen. Spannend ist die Frage, wohin der Caching-Code gehört.

Diese Seite führt vom schnellen Fix zu einem Caching-Behavior (Verhalten): Sie markieren eine Methode mit #[Cacheable], und das Framework führt den Cache-Lookup als Middleware um sie herum aus. Die Begriffe Behavior-Klasse (Verhaltensklasse), Behavior und Matching-Rule (Auswahlregel) erklärt die Begriffstabelle.

Der langsame Service:

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

Der schnelle Fix baut den Cache in die Methode ein:

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

Das funktioniert, und es beginnt sich auszubreiten:

  • Die Klasse hat zwei Aufgaben. Sie holt Kurse und verwaltet einen Cache. Jeder Test von ExchangeRates braucht jetzt einen Cache, und die Cache-Abhängigkeit wandert in jeden Konstruktoraufruf.
  • Dieselben Zeilen werden in jede langsame Methode kopiert. Jede Kopie baut ihren eigenen Schlüssel, wählt ihre eigene Lebensdauer und behandelt Cache-Misses auf ihre eigene Art. Früher oder später vergisst eine Kopie ein Argument im Schlüssel und liefert falsche Daten.
  • Es gibt keine zentrale Stelle für Änderungen. Den Cache für einen Testlauf abzuschalten, Schlüssel umzubenennen oder den Storage zu wechseln heißt, jede Kopie anzufassen.

Das objektorientierte Design kennt zwei klassische Antworten, und moderner PHP-Code verbaut beide:

  • Eine cachende Unterklasse überschreibt die langsamen Methoden und ruft bei einem Miss parent::rate() auf. Sie kann keine final-Klasse erweitern, und viele moderne Services sind final readonly.
  • Ein Decorator umhüllt den Service und implementiert dasselbe Interface. Er braucht ein Interface für jeden Service und eine weiterleitende Methode für jede Methode, ob gecacht oder nicht. Ein generischer __call()-Proxy spart die Tipparbeit, ist aber kein ExchangeRates mehr, und jeder Type-Hint weist ihn ab.
  • Keiner von beiden kann eine statische Methode cachen. Aufrufer nennen die Klasse direkt, es gibt also nichts zu umhüllen.

Die Caching-Logik wandert in eine einzige Behavior-Klasse, und die Methoden, die sie brauchen, werden mit einem Attribut markiert. Vier kleine Dateien.

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

Ein gewöhnliches PHP-Attribut. Es trägt die Einstellung, die sich von Methode zu Methode unterscheidet, die Lebensdauer in Sekunden, und hängt nicht vom Framework ab.

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

Die Methode ist wieder eine Zeile lang, und die Klasse hat wieder genau eine Abhängigkeit.

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] führt das Behavior anstelle der Methode aus. Die Matching-Rule @execution(App\Attribute\Cacheable) wählt jede Methode aus, die das Attribut trägt. Im Inneren:

  • Der Schlüssel nennt die Klasse, die Methode und die Argumente, sodass rate('EUR', 'USD') und rate('USD', 'EUR') getrennte Einträge bekommen. Er wird gehasht, weil PSR-16 die Zeichen {}()/\@: reserviert und nur Schlüssel mit bis zu 64 Zeichen garantiert.
  • $miss ist ein frisches Objekt, das kein Cache zurückgeben kann, sodass auch Methoden gecacht werden, die null oder false zurückgeben.
  • proceed() führt die ursprüngliche Methode aus, und zwar nur bei einem Miss. Die Lebensdauer stammt aus dem Attribut an dieser Methode.
  • getScope() liefert den Klassennamen, bei Instanzaufrufen wie bei statischen Aufrufen. getThis() wäre bei einem statischen Aufruf 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)),
);
}
}

Der Cache kommt aus Ihrem Anwendungscontainer, sobald dieser mit setDelegate() angebunden ist (siehe Abhängigkeiten). Mit der Bridge für Symfony, Laravel oder Yii3 entfällt dieser Schritt: Die Behavior-Klasse ist ein per Autowiring erzeugter Service wie jeder andere (Integrationen). Jede PSR-16-Implementierung funktioniert, zum Beispiel symfony/cache mit 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
  • Finale und readonly-Klassen funktionieren. Die Klasse behält ihren Namen und ihre Deklaration final readonly. Type-Hints, instanceof und new ExchangeRates(...) bleiben unverändert, weil kein Wrapper-Objekt existiert.

  • Statische Methoden funktionieren ebenfalls, was kein Decorator leisten kann:

    final class Countries
    {
    #[Cacheable(ttl: 86400)]
    public static function all(): array
    {
    // reads a large file
    }
    }
  • Eine zentrale Stelle für Änderungen. Schlüsselschema, Storage und Regeln liegen in CachingAspect. Eine Methode zu markieren oder die Markierung zu entfernen ist eine einzeilige Änderung in einem gut reviewbaren Diff.

  • Sie können es prüfen. vendor/bin/aspect debug:advisor public/index.php --advisor=... listet jede Methode auf, die die Regel auswählt (siehe debug:advisor), und ein Breakpoint in cache() hält bei jedem gecachten Aufruf an.

  • Die Kosten sind gering. Das Abfangen eines Aufrufs kostet unter 1 µs (gemessene Kosten), gegenüber den Sekunden eines entfernten Aufrufs.

  • Argumente müssen serialisierbar sein. serialize() wirft bei Closures und bei manchen Objekten eine Exception. Übergeben Sie gecachten Methoden bei Entities deren Identifikatoren, oder bauen Sie den Schlüssel aus den Teilen, die Sie brauchen.
  • Der Zustand des Objekts steckt nicht im Schlüssel. Zwei ExchangeRates-Instanzen mit unterschiedlichen Quellen teilen sich Einträge. Hängt das Ergebnis von der Instanz ab, nehmen Sie einen Wert in den Schlüssel auf, der sie identifiziert.
  • Invalidierung. Phil Karltons Satz gilt nach wie vor: Es gibt nur zwei schwierige Dinge in der Informatik, Cache-Invalidierung und die Benennung von Dingen. Eine Lebensdauer ist die einfachste Strategie. Wenn Daten in dem Moment verschwinden müssen, in dem sie sich ändern, verwenden Sie einen Cache mit Tag-Unterstützung (zum Beispiel TagAwareCacheInterface von Symfony) und ein zweites Behavior an den Methoden, die die Daten schreiben.
  • Grenzen Sie die Regel bei Bedarf ein. Kombinieren Sie das Attribut mit anderen Regeln, zum Beispiel @execution(App\Attribute\Cacheable) && within(App\Service\**). Die Syntax steht unter Matching-Rules.

© 2026 Alexander Lisachenko