本番環境とパフォーマンス
フレームワークが実行時に何をコストとして払うのか。そして、behavior を持つ呼び出しの分だけを本番で払うように、キャッシュをビルドし、チューニングし、出荷する方法。
このページは英語版からの翻訳です。基準となるのは英語版のページです。 原文を読む
フレームワークは、クラスとその behavior(振る舞い)を一度だけコンパイルし、結果を素の PHP ファイルとして保存します。以降、これらのファイルは他のコードと同じように扱われます。OPcache がキャッシュし、Composer が読み込み、リクエスト時にはパーサーもリフレクションも eval() も動きません。ウォームアップ済みのキャッシュで処理される本番リクエストは、メタデータファイルを 1 つ読み、生成されたクラスを Composer に渡し、実際にインターセプトされる呼び出しの分だけコストを払います。behavior のないメソッドとプロパティのコストはゼロです。
このページでは、計測した数値を示し、コストがどこから来るのかを説明したうえで、キャッシュを本番に届ける方法を紹介します:デプロイ時のウォームアップ、OPcache、Composer、Docker、Kubernetes。カーネルのオプションは設定と CLI で説明しています。図による概要は Performance の機能ページにあります。
実測したコスト
Section titled “実測したコスト”このページの数値はすべて、goaop/framework の upstream にある docs/performance.md から取っています。1 台のマシンで計測したものなので、モード間の比率として読んでください。他のマシンにも当てはまるのは、この比率です。
ベンチマークの環境
Section titled “ベンチマークの環境”- 小さなショップアプリケーション:include パス配下に約 250 ファイル(コンパイルされるクラスは 94 個)、その外にライブラリのクラス 120 個、そして
#[Before]、#[Around]、#[AfterThrowing]とプロパティの behavior を使う behavior class(振る舞いクラス)が 6 個。 - 1 リクエストで 50 件の注文を処理します。インターセプトされるメソッド呼び出しは約 2,600 回、インターセプトされるプロパティアクセスは約 950 回です。
- PHP 8.5.12 NTS、4 CPU、共有メモリ上の OPcache、
opcache.jit=disable、opcache.file_update_protection=0。
計測方法の全体は、下のベンチマークの再現にあります。
モード別のリクエスト時間
Section titled “モード別のリクエスト時間”3 つのキャッシュ状態:
- ホット(hot):コンパイル済みキャッシュがあり、OPcache も埋まっている状態。本番ワーカーの定常状態です。
- ウォーム(warm):コンパイル済みキャッシュはあるが、OPcache は空の状態。起動直後の PHP-FPM や新しい Pod です。
- コールド(cold):まだ何もキャッシュされていない状態。最初のリクエストが、読み込むすべてのクラスをコンパイルします。
| モード | ホット | ウォーム | ピークメモリ(ホット) |
|---|---|---|---|
debug => false + PREBUILT_CACHE |
5.4 ms | 59 ms | 1.3 MB |
debug => false |
5.5 ms | 62 ms | 1.3 MB |
debug => true |
13.0 ms | 63 ms | 2.2 MB |
| フレームワークなしの同じアプリケーション(behavior は動かない) | 2.1 ms | 36 ms | 0.7 MB |
- 実際の処理を持つ behavior(ロギング、キャッシュの参照、タイマー)による約 3,500 回のインターセプトで、リクエストは約 3.3 ms 長くなります。そのうちカーネルの起動は約 0.15 ms です。
- インターセプトされた呼び出し 1 回のコストは約 3 分の 1 マイクロ秒で、behavior が 1 つ増えるごとに約 70 ns 加わります。
- キャッシュ全体は
cache:warmup:aopで 0.5 秒未満でビルドできます。2,000 ファイルのアプリケーションでは、4 ワーカーで 1.1 秒です。 - コンテナはホットな状態で起動します。事前に充填した OPcache のファイルキャッシュがあれば、新しい PHP-FPM の最初のリクエストは 71 ms ではなく 19 ms で済みます。さらにプリロードを加えると 10 ms になり、フレームワークを使わない素のアプリケーション(9 ms)と同等です。
呼び出しあたりのコスト
Section titled “呼び出しあたりのコスト”これらの値は空の behavior で計測しているため、フレームワーク自身の処理だけを表します:call context(呼び出しコンテキスト)、インターセプターのチェーン、元のメソッドの呼び出しです。
| 呼び出し | 呼び出しあたりのオーバーヘッド |
|---|---|
| コンパイル済みクラスにある、behavior のないメソッドまたはプロパティ | 0 |
#[Before] または #[Around] を 1 つ持つメソッド |
~0.33 µs |
#[Around] を 3 つ持つメソッド |
~0.48 µs |
#[Around] を 1 つ持つ static メソッド |
~0.34 µs |
#[Around] を 1 つ持つプロパティの読み取り |
~0.22 µs |
#[Around] を 1 つ持つプロパティの書き込み |
~0.26 µs |
インターセプトされる呼び出し 100 万回のコストは、約 3 分の 1 秒です。数百回のインターセプトを含む典型的なリクエストなら、払うのは 1 ミリ秒にも満たない時間です。
CLI プロセス
Section titled “CLI プロセス”CLI のプロセスは、どれも空の OPcache で起動します。事前に充填した opcache.file_cache があれば、短命なコマンドもホットな Web リクエストに近い速さで起動します。
| プロセスあたりのスクリプト時間 | OPcache オフ | OPcache オン(メモリのみ) | opcache.file_cache(事前に充填) |
|---|---|---|---|
PREBUILT_CACHE |
33 ms | 69 ms | 21 ms |
debug => false |
30 ms | 69 ms | 22 ms |
| フレームワークなし | 19 ms | 34 ms | 10 ms |
何にどれだけかかるか
Section titled “何にどれだけかかるか”behavior のないメンバー
Section titled “behavior のないメンバー”プロキシがオーバーライドするのは、behavior を持つメンバーだけです。それ以外のメソッドとプロパティは元のコードのままで、フルスピードで動きます。オーバーヘッドは 0 です。どの matching rule(マッチングルール)にも選ばれないクラスは、そもそもコンパイルされません。
インターセプトされる呼び出しと behavior の積み重ね
Section titled “インターセプトされる呼び出しと behavior の積み重ね”インターセプトされる各メソッドは、静的な call context を 1 つ宣言します:
static $__joinPoint = InterceptorInjector::forMethod(...)call context とそのインターセプターのリストは、最初の呼び出しで構築されます。以降の呼び出しは、すべて 1 回の $__joinPoint->__invoke($this, [$args]) です。このリストには behavior class のメソッドを直接指す first-class callable が入っているため、behavior の検索も、リフレクションも、__call() もありません。
メソッドの最初の behavior のコストは約 0.33 µs です。behavior が 1 つ増えるごとに約 70 ns 加わるので、#[Around] が 3 つなら約 0.48 µs です。#[Around] を 1 つ持つ static メソッドは約 0.34 µs です。
behavior 用のリフレクション(getMethod()、getField())は、behavior が要求したときにだけ生成されます。
プロパティアクセス
Section titled “プロパティアクセス”プロパティのインターセプトは、プロキシ上の PHP 8.4 ネイティブの get フックと set フックにコンパイルされます。__get() や __set() のマジックはなく、アクセスごとのリフレクションもありません。#[Around] を 1 つ持つプロパティの読み取りは約 0.22 µs、書き込みは約 0.26 µs です。
カーネルの起動
Section titled “カーネルの起動”ベンチマークでは、カーネルの起動に約 0.15 ms かかります。フレームワークのサービス、トランスフォーマー、そして behavior class はファクトリとして登録され、それぞれ配列への書き込み 1 回で済みます。起動時には何もオートロードされず、リフレクションも生成も行われないため、ウォームなリクエストがパーサー、matching rule の文法、behavior のマッチャー、トランスフォーマーを読み込むことはありません。
- キャッシュインデックス(
CachePathManager)は、init()で構築される唯一のサービスです。オートローダーがすぐにクラスマップを読むためです。 - behavior class は、その behavior のいずれかが初めて呼ばれたときに、PHP 8.4 ネイティブの lazy オブジェクトとして生成されます。compile step(コンパイルステップ)とキャッシュのウォームアップは behavior class を生成せず、読み取るだけです。
- 本番では登録リスナーを一切有効にしません。デバッグモードでは、behavior class のファイルの変更をリスナーで追跡します。このリスナーは、クラスを読み込まずに Composer 経由でファイルを解決します。
- matching rule の文法の構文解析表は生成済みの PHP で、ルールは初めて使われたときにだけパースされます。
コールドスタートとウォームスタート
Section titled “コールドスタートとウォームスタート”ウォームなリクエスト(コンパイル済みキャッシュあり、OPcache は空)は、PREBUILT_CACHE で 59 ms かかります。素のアプリケーションでは 36 ms です。この差は、事前に充填した opcache.file_cache とプリロードで縮められます。Docker と Kubernetes を参照してください。
コールドなリクエストは、読み込むすべてのクラスをコンパイルします。デプロイ時にキャッシュをビルドし、PREBUILT_CACHE を使えば、本番リクエストがコンパイルすることはありません。
コンパイル時間
Section titled “コンパイル時間”コンパイルはデプロイ時に一度だけ行われます。
- ベンチマーク用アプリケーションのキャッシュは、0.5 秒未満でビルドできます。
- 2,047 ファイルのアプリケーションでは、1 ワーカーで 2.2 秒、4 CPU 上の 4 ワーカーで 1.1 秒でした。
- コンパイル中にメモリに保持されるパース済みファイルは、1 つあたり約 0.2 MB を使います。保持する数の上限は、カーネルオプション
parsedFilesLimit(デフォルト100)で決まります。
コンパイルを速く保っている仕組み:
- キャッシュヒットの経路では何もパースしません。最新のレコードは、トランスフォーマーが 1 つも生成される前に、キャッシュ済みの内容として返されます。ストリームフィルターとトランスフォーマーのチェーンは、最初のキャッシュミスのときにだけ構築されます。
- 書き換えルールはすべて、構文木の 1 回の走査を共有します。ソース上の目印がファイルに現れないルールはスキップされ、適用できるルールが 1 つもないファイルは走査すらされません。ほとんどのファイルがこれに当たります。
- 仕組みを動かすきっかけは behavior class です。
new式が書き換えられるのは、initialization(...)ルールが登録されている間だけです。関数プロキシは、関数のルールがあるときにだけ作られます。 - すべての祖先をリフレクションする behavior class のチェックは、behavior を持つクラスに対してだけ実行されます。
- behavior class の behavior は、静的なコンストラクター式からなる素の PHP ファイルとしてキャッシュされ、
unserialize()の約 2 倍の速さで読み込めます。 - プロキシは構文木として組み立てられ、一度だけ出力されます(コンパイル時間 −43 %)。生成されるトレイトはトークン単位の編集で作られ、Xdebug のために行番号を保ちます。
本番リクエストが行うこと
Section titled “本番リクエストが行うこと”| ステップ | debug => false(+ PREBUILT_CACHE) |
debug => true |
|---|---|---|
カーネルの init() |
オプション、コンテナ、サービスのファクトリ(何も生成しない) | 同じ。加えて、カーネルと behavior class のファイルの変更を追跡 |
_include.cache(クラスマップ、スキップセット) |
include 1 回、OPcache から提供、キャッシュディレクトリへの stat() なし |
同じ |
| コンパイル済みクラス | Composer のクラスマップ → キャッシュ済みファイル、OPcache から | 鮮度チェックの後、ストリームフィルター。Xdebug のブレークポイントとマジック定数は元のファイルを指す |
| include パス配下の変換されないクラス | スキップセット → 元のファイル、OPcache から | 鮮度チェック → 元のファイル、OPcache から |
| パーサー、トランスフォーマー、ストリームフィルター | 一切読み込まない | ストリームフィルターを登録、トランスフォーマーは構築しない |
| 変更されたソースファイル | デプロイ時にビルドしたキャッシュをそのまま提供 | 次のリクエストで再コンパイル |
プロファイラーで数えた、ホットなリクエスト 1 回あたりのファイルシステム呼び出し:
| 呼び出し | PREBUILT_CACHE |
debug => false |
debug => true |
フレームワークなし |
|---|---|---|---|---|
filemtime / filesize |
0 | 0 | 323 / 239 | 0 |
file_get_contents |
0 | 0 | 94 | 0 |
file_exists(Composer PSR-4) |
307 | 307 | 412 | 357 |
本番リクエストはソースファイルを 1 つもチェックしません。生成されたクラスがクラスマップから直接読み込まれるため、Composer の検索回数は素のアプリケーションより少なくなります。最適化した Composer のクラスマップを使えば、残りの検索もなくなります。Composer オートローダーを参照してください。
ランタイムインデックスについて、さらに 2 点:
_include.cacheには、リクエストに必要なものだけが入っています:クラスマップ、スキップセット、include マップです。ビルドの全レコードは_transformation.cacheにあり、本番はこれを読みません。- どちらのメタデータファイルも、
__DIR__相対のパスを持つ配列をvar_export()で書き出したものです。OPcache はこれを共有メモリ上でイミュータブルに保持するため、include してもコピーは発生せず、アプリケーションのディレクトリを移動してもキャッシュは有効なままです。
デバッグモードは開発用です。ベンチマークでは、そのホットなリクエストは約 13 ms、本番は約 5.5 ms です。デバッグモードでも、最新の変換されないファイルは元のパスで include されるため、OPcache がキャッシュします(ファイルあたり約 38 µs → 約 10 µs、デバッグ時のリクエストは 27–40 % 高速化)。
本番チェックリスト
Section titled “本番チェックリスト”-
'debug' => falseと'features' => Features::PREBUILT_CACHEを設定します。 -
デプロイ時またはイメージのビルド時に、
cache:warmup:aopでキャッシュをビルドします。 -
includePathsは狭く保ちます:vendor/ではなく、自分のsrc/だけにします。 -
behavior class は
addLazyService()で登録します。 -
依存パッケージは
composer install --no-dev --classmap-authoritativeでインストールします。 -
OPcache は
opcache.validate_timestamps=0で動かし、生成ファイルのための十分なメモリとファイルスロットを確保します。 -
コンテナでは、キャッシュをイメージに焼き込み、事前に充填した
opcache.file_cacheかプリロードを加えます。
本番用のカーネル:
use Go\Aop\Features;
ApplicationAspectKernel::getInstance()->init([ 'debug' => false, 'appDir' => __DIR__ . '/..', 'cacheDir' => __DIR__ . '/../var/cache/aop', 'includePaths' => [__DIR__ . '/../src'], 'features' => Features::PREBUILT_CACHE,]);デプロイ時のキャッシュのビルド
Section titled “デプロイ時のキャッシュのビルド”rm -rf var/cache/aopvendor/bin/aspect cache:warmup:aop public/index.php --workers=$(nproc)空のディレクトリから始めて、キャッシュが現在のリリースだけを正確に含むようにします。引数はカーネルを初期化するファイル、つまりフロントコントローラーかブートストラップファイルです。コマンドはこのファイルを実行するので、カーネルは本番と同じオプションで起動します。
このコマンドは:
includePaths配下(excludePathsを除く)のすべてのファイルをコンパイルし、生成ファイル、プロキシ、behavior class のキャッシュ、2 つのメタデータファイルを書き出します。- コンパイルできないファイルをすべて stderr に報告し、0 以外の終了コードで終了します。そのため、デプロイスクリプトや
docker buildは不完全なキャッシュを出荷せず、その場で止まります。
コード、behavior class、カーネルのオプション、composer.lock のいずれかが変わったら、キャッシュを再ビルドします。実際には、デプロイのたびにということです。デバッグモードでは再ビルドは不要です。変更されたクラス、behavior class、カーネルのファイルを自動で再コンパイルします。
コマンドの完全なシグネチャ:
cache:warmup:aop [<loader>] [--fail-fast] [--workers=N] [--cached-files=N] [--cache-dir=DIR] [--preload[=FILE]]すでにカーネルを初期化したアプリケーションの中(フレームワーク連携のコンソール)では、ローダー引数を省略でき、コマンドはそのプロセスのカーネルを使います。インテグレーションを参照してください。
--workers=N は N 個のワーカープロセスでコンパイルし、大きいファイルから順に処理します。デフォルトは 1 で、コマンドのプロセス内でコンパイルします。CPU の数を指定してください。メタデータはコーディネーターが一度だけ書き出し、各プロセスがメモリに保持する構文木の数には上限があります。
--cached-files=N は、プロセスごとのその上限を設定します。デフォルトはカーネルオプション parsedFilesLimit(100)です。キャッシュするファイルを増やせば再パースが減り、減らせばメモリ使用量が減ります。-v を付けると、進捗バーの代わりにすべてのファイルを一覧表示します。
稼働中のリリースの隣でビルドする
Section titled “稼働中のリリースの隣でビルドする”--cache-dir=DIR は、カーネルが自身のディレクトリから提供を続けている間に、別のディレクトリでキャッシュをゼロからビルドします。稼働中のリリースの隣で次のリリースのキャッシュを用意し、たとえばシンボリックリンクの差し替えでアトミックに切り替えるのに使います。
この方法でビルドしたキャッシュは完全で、配置場所にも依存しません。本番カーネルが自身のキャッシュがウォームな状態でビルドした場合も同じです。コンパイラーは、リフレクションするクラスについて常に元のソースを読み、本番で Composer が提供する生成ファイルを読むことはありません。
既存のディレクトリに対して実行すると、ソースが変わった(サイズまたは更新日時)ファイルをすべて再コンパイルし、それ以外はそのまま残します。これは PREBUILT_CACHE でも同じです:キャッシュをそのまま信頼するのはリクエストだけで、ウォームアップコマンドは信頼しません。
PREBUILT_CACHE と読み取り専用ファイルシステム
Section titled “PREBUILT_CACHE と読み取り専用ファイルシステム”Features::PREBUILT_CACHE を指定すると、リクエストはデプロイ時にビルドしたキャッシュを完全に信頼します。次の処理を省略します:
- キャッシュディレクトリの存在と書き込み可否の確認
- ソースの
filemtimeの比較 - 追跡対象リソースのチェック
- behavior class のキャッシュの鮮度チェック
リクエストはコンパイルせず、キャッシュディレクトリに書き込むこともないため、読み取り専用のファイルシステムでも動作します。そのぶん、キャッシュは完全でなければなりません。include パス配下にあるクラスや include されるファイルのうち、キャッシュにレコードがないもの、あるいはレコードはあってもキャッシュ済みファイルが消えているものがあると、何もコンパイルされないうちに WeavingException でリクエストが失敗します。ビルド後に追加されたファイルも、コンパイル不要なものを含めて対象です。
コンパイラーが扱わないファイルは、そのまま読み込まれます:include パスの外にあるファイル、除外されたファイル、そして include されるテンプレートのような .php 以外のファイルです。
キャッシュファイルはすべて一意な一時ファイルに書き出され、所定の場所へリネームされたあと、OPcache 上で無効化されます。並行するリクエストが書きかけのファイルを目にすることはなく、ロックも不要で、メタデータを同時に書き込むプロセス同士はレコードをマージします。
Composer オートローダー
Section titled “Composer オートローダー”コンパイルされないクラスは、通常どおり Composer が見つけます。最適化したクラスマップを使うと、検索のたびに file_exists() を呼ぶ代わりに配列アクセスで済み、生成されたクラスのクラスマップは addClassMap() でそこにマージされます。こうして、生成されたクラスと変換されないクラスが同じ方法で提供されます。
ベンチマークのホットなリクエスト:
| オートローダー | PREBUILT_CACHE |
debug => false |
フレームワークなし |
|---|---|---|---|
PSR-4(composer install) |
5.5 ms | 6.7 ms | 2.3 ms |
--optimize-autoloader(-o) |
5.2 ms | 5.0 ms | 1.6 ms |
--classmap-authoritative(-a) |
4.8 ms | 4.6 ms | 1.9 ms |
--classmap-authoritative を指定すると、Composer はクラスマップの外でクラスを探しません。コード生成を行ったあと、ウォームアップの前に dump-autoload を実行してください。
OPcache のチューニング
Section titled “OPcache のチューニング”コンパイルされたクラスは、それぞれ 2 つのキャッシュファイルになります:トレイトとしての元の本体と、プロキシです。behavior class にも、それぞれ専用のキャッシュファイルがあります。OPcache には、その分の余裕を持たせてください。
| 設定 | 本番での値 | 理由 |
|---|---|---|
opcache.enable |
1 |
生成コードは素の PHP で、アプリケーションの他の部分と同じようにキャッシュされます。 |
opcache.memory_consumption |
128–256(MB) |
負荷をかけた状態で opcache_get_status()['memory_usage'] を確認します。 |
opcache.interned_strings_buffer |
16–32(MB) |
プロキシと生成されたトレイトは、クラス名とメソッド名を共有します。 |
opcache.max_accelerated_files |
アプリケーションと vendor/ の PHP ファイル数の 2 倍以上 |
コンパイルされたクラスごとに、ファイルが 1 つ増えます。 |
opcache.validate_timestamps |
0 |
イミュータブルなリリースとコンテナ向け:include のたびの stat がなくなります。デプロイ後は PHP-FPM をリロードします。 |
opcache.file_update_protection |
0 |
フレームワークはすべてのキャッシュファイルをアトミックに書き込むため、OPcache は生成直後のファイルを、2 秒(デフォルト)待たずにすぐキャッシュできます。 |
opcache.file_cache |
ディレクトリ | ディスク上の第 2 レベルのキャッシュ:新しい PHP-FPM マスターや CLI プロセスが、スクリプトをコンパイルする代わりにコンパイル済みのものを読み込みます。ビルド時に充填しておきます。 |
opcache.preload |
任意 | 生成されたクラスを、サーバーの起動時に一度だけリンクします。プリロードを参照してください。 |
realpath_cache_size / realpath_cache_ttl |
4096K / 600 |
validate_timestamps=1 の場合:include ごとのパス検索が減ります。 |
生成コードは普通の PHP で、アプリケーションの他の部分と同様に JIT でコンパイルされます。典型的な Web リクエストは短い呼び出しを大量にこなすことに時間を使い、そこでは JIT の効果は小さいため、有効にする前に計測してください。
生成ファイルは普通のクラス宣言なので、ビルド済みのキャッシュはプリロードできます。--preload は、ビルドするキャッシュ用の opcache.preload スクリプトを書き出します。出力先は、キャッシュディレクトリの _preload.php、または --preload=FILE で指定したファイルです。
vendor/bin/aspect cache:warmup:aop public/index.php --workers=$(nproc) --preloadopcache.preload=/app/var/cache/aop/_preload.phpopcache.preload_user=www-data値なしの --preload は、ローダー引数の後ろに置く必要があります。そうしないと、ローダーを自分の値として受け取ってしまいます。
PHP-FPM の起動時、このスクリプトは Composer のオートローダーを require し、生成されたクラスのクラスマップを渡したうえで、コンパイルされたすべてのクラス、そのプロキシ、キャッシュが把握している変換されないすべてのクラスを OPcache にリンクします。
- Composer の
filesオートロード(ヘルパー関数、polyfill のブートストラップ)はプリロードされません。リクエストはこれまでどおり、それらを include します。 - スクリプトには絶対パスが含まれません。メタデータファイルと同じく、すべて
__DIR__から位置を求めるため、アプリケーションと一緒に移動したキャッシュも有効なままです。 - スクリプトに並ぶのは、ビルドに使ったキャッシュのクラスだけです。キャッシュと一緒に再ビルドしてください。
- プリロード中にリンクできないクラス(任意の依存パッケージが欠けている場合)は、エラーログに記録され、リクエスト時のオートローダーに任されます。
- 静的初期化に behavior を持つクラスも、オートローダーに任されます:その behavior にはカーネルが必要なので、リクエストが読み込みます。
カーネルはこれまでどおり、リクエストごとに初期化されます。プリロードされたクラスを、オートローダーが読み込む必要がなくなるだけです。ベンチマークでは、プリロードによってリクエストあたりの include ファイル数が 517 から 174 に、ホットなリクエストが 5.2 ms から 4.9 ms に、サーバー起動後の最初のリクエストが 71 ms から 24 ms に(事前に充填したファイルキャッシュとの併用で 10 ms)短縮されました。
プリロードされたクラスが変わるのは PHP-FPM の再起動時だけで、コンテナのデプロイではもともとそうなります。opcache.enable_cli=1 を設定しない限り、CLI では何もプリロードされません。
Docker と Kubernetes
Section titled “Docker と Kubernetes”フレームワークのキャッシュは、イメージに焼き込みます。そうすれば、どのコンテナも完全で読み取り専用のキャッシュを持って起動し、すべてのレプリカがまったく同じ生成コードを提供し、どの Pod もコンパイルを行いません。shop demo は、この構成を動作するイメージとして提供しています。
Dockerfile
Section titled “Dockerfile”FROM php:8.5-fpm
# OPcache is part of PHP 8.5, no docker-php-ext-install neededCOPY docker/opcache.ini /usr/local/etc/php/conf.d/opcache.iniCOPY --from=composer:2 /usr/bin/composer /usr/bin/composer
WORKDIR /appCOPY composer.json composer.lock ./RUN composer install --no-dev --no-scripts --no-autoloader --prefer-distCOPY . .RUN composer dump-autoload --no-dev --classmap-authoritative
# 1. The framework's cache: generated classes, proxies, behavior caches, metadata, owned by the user that serves it# (cache files get the `cacheFileMode` kernel option, by default 0770 minus the umask)RUN rm -rf var/cache/aop \ && php vendor/bin/aspect cache:warmup:aop public/index.php --workers="$(nproc)" --preload \ && chown -R www-data:www-data var/cache/aop \ && chmod -R a-w var/cache/aop
# 2. The OPcache file cache: a new PHP-FPM master loads compiled scripts instead of compiling them.# Built in the final image, as the file cache belongs to this PHP build and these paths.RUN mkdir -p /var/cache/opcache \ && php -d opcache.enable_cli=1 -d opcache.file_cache_only=1 -d opcache.file_cache=/var/cache/opcache \ vendor/bin/aspect cache:warmup:opcache public/index.php --file-cache=/var/cache/opcache --entry=public/index.php \ && chown -R www-data /var/cache/opcache
USER www-datacache:warmup:opcache は、アプリケーションが読み込むものをコンパイルします:フレームワークのキャッシュ(生成ファイル、プロキシ、behavior class のキャッシュ、メタデータ)、Composer のクラスマップとオートロードされるファイル、include パス配下でコンパイルされないソース、ローダーファイル、そして --entry で指定したエントリーポイントです。
- コンパイル済みスクリプトがディスクに書き出されるのは、
opcache.enable_cli=1、opcache.file_cache_only=1、opcache.file_cache=DIRを付けて起動したプロセスだけです。これらは実行時には設定できません。コマンドはこれらの設定と、--file-cache=DIRが設定済みのディレクトリと一致することを確認し、そうでなければ実行すべきコマンドをそのまま表示します。 - フレームワークのキャッシュ、ローダー、エントリーポイントはコンパイルできなければならず、できなければコマンドは失敗します。Composer のクラスマップにあるファイルでコンパイルできないもの(新しい PHP 向けに書かれた vendor のテストスタブなど)は、一覧表示されてスキップされます。コンパイルエラーは PHP がログに記録します。
cache:warmup:aopの後に、最終イメージの中で、リクエストを処理するのと同じ PHP バイナリで実行してください。ファイルキャッシュのキーは、PHP のビルドとファイルの絶対パスです。
opcache.ini
Section titled “opcache.ini”opcache.enable=1opcache.memory_consumption=192opcache.interned_strings_buffer=32opcache.max_accelerated_files=50000opcache.validate_timestamps=0opcache.file_cache=/var/cache/opcacheopcache.file_cache_consistency_checks=0; PHP 8.5: the primed file cache is only read at runtime, also on a read-only root file systemopcache.file_cache_read_only=1; required on PHP 8.5.11 / 8.5.12, see "JIT"opcache.jit=disable; optional, see "Preloading" (written by cache:warmup:aop --preload); opcache.preload=/app/var/cache/aop/_preload.php; opcache.preload_user=www-dataイメージのカーネルは、チェックリストにある本番用のカーネルです:debug => false、src/ に限定した includePaths、そして Features::PREBUILT_CACHE。
ベンチマークでは、この構成で起動直後のサーバーの最初のリクエストが、ファイルキャッシュありで 19 ms、ファイルキャッシュとプリロードの併用で 10 ms でした。どちらもない場合は 71 ms です。Pod は最初のリクエストから高速です。
Kubernetes
Section titled “Kubernetes”- 読み取り専用のルートファイルシステム(
readOnlyRootFilesystem: true)。PREBUILT_CACHEはイメージに焼き込まれたキャッシュを読み、実行時には何も書き込みません。 - 1 イメージに 1 キャッシュ。 キャッシュは共有ボリュームではなく、イメージの中に置きます。そうすれば、どのリリースも、ビルド元のコードを正確に提供します。
- ローリングアップデート に特別な対応は不要です。新しい Pod は自分のキャッシュを持ち込み、古い Pod は自分のキャッシュを使い続けます。
- イメージにキャッシュを含められない場合 は、init コンテナで
cache:warmup:aopを実行し、アプリケーションコンテナのキャッシュパスにマウントしたemptyDirボリュームへ書き出します。こうすればPREBUILT_CACHEを維持でき、Pod は完全なキャッシュを持った状態で Ready になります。 - CLI コンテナ(キューのコンシューマー、cron ジョブ)は、同じイメージとキャッシュを使います。事前に充填した
opcache.file_cacheと一緒にopcache.enable_cli=1を有効にしてください。CLI プロセスを参照してください。
長時間稼働するワーカー
Section titled “長時間稼働するワーカー”長時間稼働するワーカー(RoadRunner、FrankenPHP のワーカーモード、Swoole、ReactPHP)は、ワーカーごとに一度だけカーネルを起動します。call context は、リクエストをまたいで初期化済みのまま保たれます。
速い behavior の書き方
Section titled “速い behavior の書き方”- 対象を正確に絞る。 インターセプトされるのはマッチしたメンバーだけ、コンパイルされるのはマッチしたクラスだけなので、正確なルールほど速くなります。
execution(public App\Service\*->*(*))はコンストラクターにもマッチします。不要なら&& !execution(**->__construct(*))を加えてください。 initialization(...)よりメソッドのルールを選ぶ。initializationルールが登録されている間は、生成ファイル内のすべてのnewがトランスフォーマーを通ります。初期化の behavior を持たない(かつ public なコンストラクターを持つ)クラスは、引き続きネイティブのnewで生成されますが、素のnewより約 130 ns 余分にかかります。初期化の behavior を持つクラスは、call context の処理をすべて経由します。- behavior class は遅延登録する。
addLazyService()を使います。behavior class とその依存は、リクエストのたびではなく、behavior が初めて呼ばれたときに生成されます。 - behavior を軽く保つ。
getMethod()とgetField()は、call context ごとに、初めて使われたときにリフレクションオブジェクトを生成します。そこから属性や名前を一度だけ取り出し、class::methodをキーにして behavior class の中に保持してください。 - call context の文字列化は必要なときだけ。
(string) $invocationは、呼び出しのたびに文字列を組み立てます。実際に書き出すメッセージにだけ使ってください。 - ネイティブの include。
Features::INTERCEPT_INCLUDESは、Composer で読み込まれないレガシーコード向けに、生成ファイル内のinclude/requireをコンパイラー経由にします。これを有効にしても、キャッシュが把握しているファイルのincludeは、本番ではストリームフィルターを通さず、元のパスまたはキャッシュ済みのパスで提供されます(include あたり約 250 µs → 約 11 µs)。
遅延登録する behavior class:
use Go\Core\AspectContainer;use Go\Core\AspectKernel;use Psr\Log\LoggerInterface;
class ApplicationAspectKernel extends AspectKernel{ protected function configureAop(AspectContainer $container): void { // Runs when one of its behaviors first runs, after the application container is attached $container->addLazyService( MonitorAspect::class, static fn(AspectContainer $container) => new MonitorAspect($container->getService(LoggerInterface::class)), ); }}behavior と matching rule の書き方は、振る舞いとマッチングルールで説明しています。
トラブルシューティング
Section titled “トラブルシューティング”ウォームアップとビルド済みキャッシュ
Section titled “ウォームアップとビルド済みキャッシュ”| メッセージまたは症状 | 意味と対処 |
|---|---|
cache:warmup:aop が stderr にエラーを書き出し、0 以外の終了コードで終了する |
コンパイルできないファイルがあります。不完全なキャッシュを出荷しないよう、デプロイや docker build はそこで止まります。ファイルを修正して、もう一度ウォームアップを実行してください。 |
WeavingException: ... is missing from the prebuilt AOP cache in ... |
PREBUILT_CACHE で、include パス配下のクラスまたは include されるファイルにキャッシュ上のレコードがないか、キャッシュ済みファイルが消えています。cache:warmup:aop でキャッシュを再ビルドしてください。 |
cache:warmup:opcache がキャッシュを充填せず、コマンドを表示する |
プロセスが -d opcache.enable_cli=1 -d opcache.file_cache_only=1 -d opcache.file_cache=DIR 付きで起動されていないか、--file-cache が別のディレクトリを指しています。表示されたコマンドを実行してください。 |
プリロードのエラー
Section titled “プリロードのエラー”PHP はプリロードの問題を、PHP-FPM マスター(または php -S)の起動時に一度だけ、そのエラーログに報告します。
| メッセージ | 意味と対処 |
|---|---|
Fatal Error "opcache.preload" requires "opcache.preload_user" when running under uid 0 |
マスターが root で動いています。opcache.preload_user に、ワーカーを動かすユーザー(www-data)を設定してください。 |
Failed opening required '.../_preload.php' |
スクリプトがありません:キャッシュが --preload なしでビルドされたか、opcache.preload が別のキャッシュディレクトリを指しています。cache:warmup:aop --preload で再ビルドしてください。 |
Go! AOP preload: <class> is left to the autoloader: ... |
スクリプトがキャッシュ内のクラスを読み込めませんでした。主な原因は、任意の依存パッケージがインストールされていないことです(--no-dev のイメージ)。害はありません:そのクラスはプリロードされず、必要とするリクエストが通常どおりオートロードします。 |
Can't preload unlinked class <class>: Unknown parent/trait/interface <name> in <file> |
プリロードが include したファイルのクラスを、同じ理由で OPcache がリンクできませんでした。キャッシュ内のクラスについては、上の行と一緒に出ます。害はありません:そのクラスがプリロードされないだけです。 |
vendor のヘルパーファイルでの Can't preload unlinked class class@anonymous: Unknown trait ... |
Composer の files オートロードにある無名クラスです。たとえば Laravel の Illuminate/Reflection/helpers.php。キャッシュのスクリプトはこれらのファイルを除外しています。この警告は、それより前に vendor/autoload.php を require する別のスクリプトから出ています。キャッシュのスクリプトを先に require してください:そうすれば Composer はファイルを再度 include せず、ローダーを返すだけです。 |
ベンチマークの再現
Section titled “ベンチマークの再現”アプリケーション、ベンチマークのスクリプト、Docker イメージは goaop/shop-demo にあります。このページのすべての表は、1 つのスクリプトで再現できます:
bash bench/run-all.sh数値の計測方法
Section titled “数値の計測方法”- アプリケーション: 手書きのクラス約 45 個(ドメイン、リポジトリ、サービス、コントローラー、インメモリのインフラ)、生成されたモジュール 40 個(サービスとリポジトリはコンパイル対象。DTO、バリデーター、イベントは対象外)、include パスの外にあるライブラリのクラス 120 個。
- behavior class: ロギング(属性に対する
#[Before])、キャッシュとトランザクション(属性に対する#[Around])、モニタリング(リポジトリに対する#[Around]、サービスに対する#[AfterThrowing])、在庫の監査(プロパティに対する#[Around])、セキュリティ(モジュールのサービスに対する#[Before])。 - ベースライン: カーネルなしの同じコード。その behavior は動きません。
- ランタイム: PHP 8.5.12 NTS、4 CPU、
opcache.jit=disableとopcache.file_update_protection=0を指定した OPcache。 - Web リクエスト: ビルトイン Web サーバー(
php -S、ワーカー 1 つ、OPcache の共有メモリはリクエスト間で保持)。ウォームは起動直後のサーバーの最初のリクエスト(7 サンプル)、ホットは 350 リクエストの中央値です。時間はスクリプト内でhrtime()を使って計測しています。 - プロファイル: すべてのモードと状態について Xdebug 3.5 の
xdebug.mode=profileで実行し、呼び出し回数と時間の内訳の把握に使いました。時間そのものは、Xdebug なしの実行から得ています。
モード間の比率こそが、他のマシンにも当てはまる部分です。
© 2026 Alexander Lisachenko
