コンテンツにスキップ
ドキュメント

キャッシュの振る舞い

遅いメソッドの結果を属性 1 つでキャッシュします。PSR-16 ストレージを使う #[Cacheable] の behavior は、final クラス、readonly クラス、static メソッドでも動作します。

このページは英語版からの翻訳です。基準となるのは英語版のページです。 原文を読む

マネージャーから苦情が転送されてきました。チェックアウトのページに 3 秒かかるというのです。プロファイラーが指し示したのは 1 つのメソッドで、為替レートは 1 日に数回しか変わらないのに、呼び出しのたびにリモートサービスへ問い合わせています。答えは明らかで、キャッシュすればよいのです。面白いのは、そのキャッシュのコードをどこに置くかです。

このページでは、その場しのぎの修正から出発して、キャッシュの 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;
}
}

これは動きますが、広がり始めます。

  • クラスが 2 つの仕事を抱える。 レートを取得し、キャッシュも管理します。ExchangeRates のどのテストにもキャッシュが必要になり、キャッシュへの依存がコンストラクターの呼び出しのたびについて回ります。
  • 同じ行が遅いメソッドのすべてにコピーされる。 コピーごとに独自のキーを組み立て、独自の有効期間を選び、キャッシュミスを独自に扱います。遅かれ早かれ、どれかのコピーがキーに引数を入れ忘れ、間違ったデータを返します。
  • 変更する場所が 1 か所にまとまっていない。 テスト実行のためにキャッシュを無効にする、キーの名前を変える、ストレージを切り替える。そのたびにすべてのコピーを編集することになります。

デコレーターやプロキシでは足りない理由

Section titled “デコレーターやプロキシでは足りない理由”

オブジェクト指向設計には古典的な答えが 2 つありますが、モダンな PHP のコードはそのどちらも阻みます。

  • キャッシュ用のサブクラスは遅いメソッドをオーバーライドし、キャッシュミスのときに parent::rate() を呼びます。しかし final クラスは継承できず、モダンなサービスの多くは final readonly です。
  • デコレーターはサービスを包み、同じインターフェースを実装します。サービスごとにインターフェースが、メソッドごとに(キャッシュするかどうかにかかわらず)転送用のメソッドが必要です。汎用の __call() プロキシなら記述は減りますが、もはや ExchangeRates ではないので、どの型宣言にも拒否されます。
  • どちらも static メソッドはキャッシュできない。 呼び出し側がクラス名を直接書くため、包むものがありません。

キャッシュのロジックは 1 つの behavior class にまとめ、それを必要とするメソッドには属性で目印を付けます。小さなファイルが 4 つです。

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

メソッドは 1 行に戻り、クラスの依存関係もまた 1 つになりました。

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() は、インスタンスメソッドの呼び出しでも static メソッドの呼び出しでもクラス名を返します。getThis() は static メソッドの呼び出しでは 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() で接続したアプリケーションのコンテナから取得します(依存関係を参照)。Symfony、Laravel、Yii3 のブリッジを使う場合、このステップは不要です。behavior class は、ほかのサービスと同じようにオートワイヤリングされるサービスになります(インテグレーション)。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(...) は何も変わりません。

  • static メソッドでも動作する。 これはどのデコレーターにもできないことです。

    final class Countries
    {
    #[Cacheable(ttl: 86400)]
    public static function all(): array
    {
    // reads a large file
    }
    }
  • 変更する場所は 1 か所。 キーの組み立て方、ストレージ、ルールは CachingAspect にまとまっています。メソッドに目印を付けたり外したりするのは、レビューしやすい diff での 1 行の変更です。

  • 確認できる。 vendor/bin/aspect debug:advisor public/index.php --advisor=... は、ルールが選ぶすべてのメソッドを一覧表示します(debug:advisor を参照)。cache() の中に置いたブレークポイントは、キャッシュされる呼び出しのたびに止まります。

  • コストは小さい。 リモート呼び出しにかかる数秒に対して、呼び出しのインターセプトにかかるコストは 1 µs 未満です(実測したコスト)。

  • 引数はシリアライズ可能でなければならない。 serialize() はクロージャーや一部のオブジェクトに対して例外を投げます。エンティティについては、キャッシュするメソッドに識別子を渡すか、必要な部分からキーを組み立ててください。
  • オブジェクトの状態はキーに含まれない。 取得元が異なる 2 つの ExchangeRates インスタンスは、エントリーを共有します。結果がインスタンスに依存する場合は、インスタンスを識別する値をキーに加えてください。
  • 無効化。 Phil Karlton の言葉は今も当てはまります。「コンピューターサイエンスで難しいことは 2 つしかない。キャッシュの無効化と、名前を付けることだ」。有効期間は最も単純なポリシーです。データが変わった瞬間に消えなければならない場合は、タグをサポートするキャッシュ(たとえば Symfony の TagAwareCacheInterface)を使い、データを書き込むメソッドに 2 つ目の behavior を付けます。
  • 必要ならルールを絞り込む。 属性をほかのルールと組み合わせます。たとえば @execution(App\Attribute\Cacheable) && within(App\Service\**) です。構文は matching rule にあります。

© 2026 Alexander Lisachenko