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

設定と CLI

カーネルを設定し、フィーチャーフラグを選び、behavior class にアプリケーションのコンテナから依存関係を渡し、コンソールを実行します。

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

フレームワークがアプリケーションについて知る必要のあることは、すべて 1 つの呼び出し、つまりカーネルの init() を通して渡します。このページでは、カーネルが受け付けるすべてのオプション、フィーチャーフラグ、behavior class(振る舞いクラス)がアプリケーションのコンテナから依存関係を受け取る方法、そしてキャッシュのビルドと調査に使う vendor/bin/aspect コンソールを一覧にします。

カーネルは Go\Core\AspectKernel を継承し、configureAop() で behavior class(API では aspect(アスペクト)。用語表を参照)を登録します。

app/ApplicationAspectKernel.php
use Aspect\MonitorAspect;
use Go\Core\AspectContainer;
use Go\Core\AspectKernel;
class ApplicationAspectKernel extends AspectKernel
{
protected function configureAop(AspectContainer $container): void
{
// Deferred (recommended): constructed on first use
$container->addLazyService(MonitorAspect::class, static fn() => new MonitorAspect());
// Eager alternative: $container->add(MonitorAspect::class, new MonitorAspect());
}
}

カーネルは一度だけ、通常はフロントコントローラーで、Composer のオートローダーの直後に初期化します。

public/index.php
include __DIR__ . '/../vendor/autoload.php';
ApplicationAspectKernel::getInstance()->init([
'debug' => false,
'appDir' => __DIR__ . '/..',
'cacheDir' => __DIR__ . '/../var/cache/aop',
'includePaths' => [__DIR__ . '/../src'],
]);

受け付けるのは以下のオプションだけです。未知のキー、未知の containerClass、未知のフィーチャービットは Go\Aop\Exception\InvalidConfigurationException を投げるので、タイプミスは無視されずに起動時に失敗します。

オプション 型 デフォルト 用途
cacheDir string なし(必須) コンパイル済みのソース、プロキシ、advisor(アドバイザー)のキャッシュ、クラスマップを置くディレクトリ。
appDir string vendor/ を含むディレクトリ アプリケーションのルート。キャッシュのパスはこれを基準としたソースのパスと同じ構成になり、この下にあるファイルだけがコンパイルされます。
debug bool false 開発モード。カーネルのファイルや behavior class のファイルを変更するとキャッシュが無効になり、すべてのクラスと include がフレームワークのコンパイル用ストリームフィルターを通して読み込まれます。false では、コンパイル済みのクラスが Composer のクラスマップを通してキャッシュから読み込まれます。本番環境では false を使います。
includePaths string[] [](appDir の下のすべて) コンパイルするディレクトリ。狭く保ってください。vendor のコードのコンパイルは遅く、必要になることはまずありません。
excludePaths string[] [] 決してコンパイルしないディレクトリ。キャッシュディレクトリ、フレームワーク自身、その実行時の依存パッケージ(goaop/dissect、goaop/parser-reflection、nikic/php-parser、psr/container、symfony/finder)は常に除外されます。
features int 0 Go\Aop\Features のフラグのビットマスク。次のセクションを参照してください。
cacheFileMode int 0770 から umask を引いた値 キャッシュファイルのパーミッション。0600 から 0777 の間で、所有者に読み書きの権限を与える値でなければなりません。ディレクトリには対応する検索ビットが付きます。
containerClass class-string Go\Core\Container カーネルのコンテナの実装。Go\Core\AspectContainer(PSR-11 の ContainerInterface)を実装していなければなりません。
parsedFilesLimit int 100 コンパイル中に goaop/parser-reflection がメモリに保持する、パース済みソースファイル(構文木。1 つあたり約 0.2 MB)の数。正の整数でなければなりません。多ければ再パースが減り、少なければメモリ使用量が減ります。init() の前に ReflectionEngine::setMaximumCachedFiles() で設定した上限を置き換え、cache:warmup:aop --cached-files のデフォルトにもなります。

フィーチャーフラグは final クラス Go\Aop\Features の定数です。| で組み合わせます。

public/index.php
use Go\Aop\Features;
ApplicationAspectKernel::getInstance()->init([
'debug' => false,
'appDir' => __DIR__ . '/..',
'cacheDir' => __DIR__ . '/../var/cache/aop',
'includePaths' => [__DIR__ . '/../src'],
'features' => Features::INTERCEPT_INCLUDES | Features::PREBUILT_CACHE,
]);

Features::ALL はすべてのフラグを組み合わせたものです。AspectKernel::hasFeature() はフラグが設定されているかどうかを返し、未知のフラグには例外を投げます。

フラグ 使う場面
INTERCEPT_INCLUDES アプリケーションが Composer ではなく include/require でコードを読み込む場合。
PREBUILT_CACHE デプロイ時にキャッシュをビルドし、リクエストにそれを完全に信頼させたい場合。本番環境向けの設定です。
PARTIAL_REFLECTION コンパイルしたいクラスが、フレームワークが見つけられない何かを継承または実装している場合。

コンパイルされたファイル内の include と require を、コンパイラーを通すようにします。Composer で読み込まれないレガシーコードに使います。

デプロイ時にビルドしたキャッシュを完全に信頼します。カーネルは、キャッシュディレクトリと書き込み可能かどうかの確認、ソースの filemtime の比較、追跡しているリソースのチェック、advisor のキャッシュの鮮度チェックを省略します。リクエストがコンパイルを行うことも、キャッシュディレクトリに書き込むことも一切ないため、読み取り専用のファイルシステムでも動作します。

その代わり、キャッシュは完全でなければなりません。コンパイラーが扱わないファイル(include パスの外にあるもの、除外されたもの、.php でないもの。たとえば include されるテンプレート)は、そのまま読み込まれます。それ以外の、include パスの下にあるものはすべて、キャッシュに記録がなければなりません。

cache:warmup:aop 自体は、自分がビルドするキャッシュを信頼しません。既存のディレクトリに対して実行すると、ソースが変わった(サイズまたは更新日時)ファイルをすべてコンパイルし直します。そのローダーファイルは、ビルドの開始前に、キャッシュがまだ知らないクラスを読み込むことがあります。それらはその時点ではコンパイルされずに読み込まれ、ビルドによってコンパイルされます。

親クラス、インターフェース、トレイトが見つからないクラスをコンパイルします。実行時に生成されたコード、class_alias()、Composer のオートローダーの外にあるファイルで宣言されたものが該当します。そのクラスは、自身のメソッドとプロパティ、そして利用できる祖先のものを対象としてマッチングされ、コンパイルされます。見つからない祖先から継承したメンバーはインターセプトされません。

このフラグがないと、そのようなクラスはコンパイルに失敗します。その失敗に遭遇したら有効にしてください。

関数と初期化のルールにフラグは不要

Section titled “関数と初期化のルールにフラグは不要”

これらの matching rule(マッチングルール)のための仕組みは、登録された behavior class(遅延登録されたものも含む)からフレームワークが有効にします。features に何かを設定する必要はありません。

  • execution(Namespace\function(*)) ルールは、マッチする名前空間に関数のプロキシを追加します。
  • initialization(...) ルールは、コンパイルされたファイル内の new Foo(...) 式の書き換えを有効にします。そのようなルールが 1 つでも登録されている間は、書き換えられたすべての new がインターセプターを通るので、こうしたルールは必要なコードに限ってください。

matching rule の構文は振る舞いとマッチングルールにあります。

アプリケーションのコンテナからの behavior class

Section titled “アプリケーションのコンテナからの behavior class”

カーネルのコンテナは PSR-11 コンテナです(Go\Core\AspectContainer は Psr\Container\ContainerInterface を継承しています)。このコンテナは、Symfony、Laravel、PHP-DI、その他あらゆる PSR-11 コンテナといった、アプリケーションのコンテナに処理を委譲できます。get()、getService()、has() は、カーネルのコンテナに登録されていない ID についてデリゲートにフォールバックします。

カーネルは、アプリケーションがコンテナを構築する前に初期化されます。そのため、behavior class はいつもどおりに登録し、依存関係は遅延して解決させます。

app/ApplicationAspectKernel.php
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)),
);
// or take the whole behavior class from the application container, by the id it has there
// $container->addLazyService(MonitorAspect::class, static fn(AspectContainer $c) => $c->get('app.monitor_aspect'));
}

アプリケーションのコンテナができたら、たとえばフレームワークのカーネルが起動した直後に、それを接続します。

ApplicationAspectKernel::getInstance()->getContainer()->setDelegate($psrContainer);

compile step(コンパイルステップ)とキャッシュのウォームアップに必要なのは behavior class そのものだけです。これらは vendor/bin/aspect の中でも setDelegate() より前に実行され、behavior class のインスタンスを生成することはありません。ファクトリは、その behavior(振る舞い)のいずれかが初めて実行されるときに実行されます。その時点でまだ依存関係が見つからなければ、ServiceNotFoundException が投げられます。

Symfony、Laravel、Yii 3 のブリッジはインテグレーションで扱います。

behavior class のファクトリのルール

Section titled “behavior class のファクトリのルール”
  • ファクトリは、カーネルのコンテナに自分自身の ID を問い合わせてはならない。 その ID は、今まさに構築中の behavior class に解決されます。インスタンスはアプリケーションのコンテナから、そこでの ID で取得するか、依存関係から構築してください。
  • behavior class がデリゲートから自動で検出されることはない。 PSR-11 コンテナは内部を調べることができず、インターフェースやタグでサービスを探す標準的な方法がありません。すべての behavior class は configureAop() で登録します。特定のフレームワーク向けのブリッジなら、そのフレームワーク自身のコンテナからタグやインターフェースでサービスを集め、addLazyService() で登録できます。
  • compile step が behavior class のインスタンスを生成することはない。 compile step は behavior class を読み、生成コードは各 behavior をクラス名とメソッド名で参照します。インスタンスプロパティを持たないもの(PHP はそれを lazy にできません)も含め、すべての behavior class は、その behavior のいずれかが初めて実行されるとき、アプリケーションのコンテナが接続された後に、ファクトリによって生成されます。
  • behavior class の生成で、そのクラス自身の behavior が実行されてはならない。 behavior class が依存するサービスの構築(そのサービスのコンストラクター、またはコンストラクターが呼ぶメソッド)を、その behavior class の behavior のいずれかがインターセプトしていると、その behavior はまだ存在しないインスタンスの上で実行されることになります。インターセプターはこれを AspectCircularReferenceException で報告し、behavior class、インターセプトされた呼び出し、生成から behavior に至るまでの呼び出しを示します。依存関係を遅延して注入する(遅延サービス、クロージャー、サービスロケーター)か、behavior class が自身の依存関係の生成をインターセプトしないように matching rule を絞り込んでください。

カーネルのコンテナを置き換えるには、独自のクラスを containerClass として渡します。そのクラスは Go\Core\AspectContainer を実装していなければなりません。つまり PSR-11 の get() と has()、そして setDelegate() です。未知の ID には ServiceNotFoundException を投げます。これは Psr\Container\NotFoundExceptionInterface を実装しています。

debug オプションで 2 つのモードを切り替えます。behavior class と matching rule はどちらのモードでも同じです。

'debug' => true 'debug' => false
クラスの読み込み すべてのクラスと include が、コンパイル用ストリームフィルターを通ります。 コンパイル済みのクラスが、Composer のクラスマップを通してキャッシュから読み込まれます。
ソース、behavior class、カーネルのファイルの変更 次のリクエストで再びコンパイルされます。 キャッシュがそのまま使われます。
キャッシュの再ビルド 不要です。 デプロイのたびに、cache:warmup:aop で行います。
用途 ローカルでの開発。 本番環境。Features::PREBUILT_CACHE を加えます。

開発中にビルドステップはありません。クラスや behavior を編集して再読み込みすれば、フレームワークが変更された部分をコンパイルし直します。ブレークポイントは元のコードで機能します。

本番環境では、フレームワークはキャッシュのクラスマップを Composer に渡し、ウォームなリクエストではパーサーとトランスフォーマーは読み込まれません。さらに PREBUILT_CACHE を加えると、リクエストはソースファイルとキャッシュの鮮度のチェックもすべて省略します。さらなるチューニングの方法(OPcache、プリロード、コンテナ)は本番環境とパフォーマンスにあります。

必須のオプションは cacheDir だけです。このディレクトリには次のものが置かれます。

  • コンパイル済みのソース:元の各クラス本体が <Class>OriginalTrait トレイトとして、ソースファイルの相対パスに置かれます。
  • プロキシ:コンパイル済みのソースの隣に、元のクラス名で置かれます。
  • behavior class の advisor のキャッシュ:素の PHP ファイルとして、コンパイル済みのソースの隣に置かれます。
  • メタデータ:Composer に渡すクラスマップ _include.cache を含みます。
  • _preload.php:cache:warmup:aop --preload でキャッシュをビルドした場合に置かれます。

知っておくべきこと:

  • appDir と同じ構成になる。 キャッシュのパスはアプリケーションのルートを基準とし、メタデータ内のパスは __DIR__ を基準として保存されるので、アプリケーションのディレクトリを移動してもキャッシュは有効なままです。
  • コンパイルされることはない。 excludePaths に何を指定しても、キャッシュディレクトリは常に除外されます。
  • パーミッションは cacheFileMode で決まる。 デフォルトは 0770 から umask を引いた値です。キャッシュは、リクエストを処理するユーザーとして、またはそのユーザーのためにビルドしてください。
  • 3.x からアップグレードするときは削除する。 3.x のキャッシュファイルが再利用されることはなく、PREBUILT_CACHE では、別のバージョンのフレームワークでビルドされたキャッシュは拒否されます。
ターミナルウィンドウ
vendor/bin/aspect cache:warmup:aop public/index.php

vendor/bin/aspect には symfony/console(^7.4 || ^8.0)が必要です。アプリケーションにまだなければ、Composer でインストールしてください。

どのコマンドも、カーネルを初期化するファイル(通常はフロントコントローラーかブートストラップファイル)へのパスを受け取ります。そのファイルが実行されるので、コマンドはアプリケーションと同じオプションを持つカーネルを扱います。すでにカーネルを初期化しているアプリケーションの中(コマンドがサービスとして登録される、フレームワークのインテグレーションのコンソール)では、引数を省略します。コマンドはそのプロセスのカーネルを使います。

どのコマンドも Command::SUCCESS か Command::FAILURE を返します。スクリプトでは終了コードを確認してください。

コマンド 用途
cache:warmup:aop include パスの下にあるすべてのファイルをキャッシュにコンパイルします。
cache:warmup:opcache フレームワークのキャッシュと、リクエストが読み込むものを opcache.file_cache に事前に用意します。
debug:aspect 登録された behavior class とその behavior を一覧表示します。
debug:advisor advisor(各 behavior とその matching rule の組み合わせ)を一覧表示します。または、1 つの advisor がマッチするインターセプト対象の呼び出しを表示します。
debug:weaving キャッシュを 2 回ウォームアップし、生成結果が異なるプロキシを報告します。
ターミナルウィンドウ
rm -rf var/cache/aop
vendor/bin/aspect cache:warmup:aop public/index.php --workers=8

このコマンドは、includePaths の下(excludePaths を除く)にあるすべてのファイルをコンパイルし、コンパイル済みのファイル、プロキシ、advisor のキャッシュ、メタデータを書き出します。進捗バーを表示します。コンパイルできないファイルはすべて stderr に報告し、0 以外の終了コードで終了するので、デプロイスクリプトや docker build は不完全なキャッシュを出荷せずにそこで止まります。

オプション デフォルト 用途
--workers=N 1(コマンドのプロセス内でコンパイル) N 個のワーカープロセスで並列にコンパイルします。CPU の数を指定してください。
--cached-files=N カーネルのオプション parsedFilesLimit、100 各プロセスがメモリに保持するパース済みファイルの数。
--fail-fast オフ コンパイルできない最初のファイルで停止します。
--cache-dir=DIR カーネルの cacheDir カーネルとワーカーは自身のキャッシュを使い続けたまま、別のディレクトリにキャッシュを一からビルドします。
--preload[=FILE] オフ キャッシュの opcache.preload スクリプトも書き出します。キャッシュディレクトリ内の _preload.php、または FILE です。
-v オフ 進捗バーだけでなく、すべてのファイルを表示します。

オプションについての注意:

  • --cache-dir を使うと、デプロイの際に、稼働中のキャッシュの隣で次のリリースのキャッシュを用意し、それをアトミックに切り替えられます。たとえばシンボリックリンクの差し替えです。この方法でビルドしたキャッシュは完全で、場所に依存しません。本番用のカーネルが自身のキャッシュをウォームにしたままビルドする場合も同様です。コンパイラーは常に元のソースを読み、Composer が提供するコンパイル済みのファイルを読むことはありません。
  • --preload を値なしで使う場合は、ローダー引数の後に置かなければなりません。そうしないと、ローダーを自身の値として受け取ってしまいます。このスクリプトは PHP の起動時に、コンパイル済みのすべてのクラスと、キャッシュが知っている変換されないすべてのクラスをリンクします。静的初期化に behavior を持つクラスはオートローダーに任されます。スクリプトには絶対パスが含まれず、まさにこのキャッシュのクラスを列挙するので、キャッシュと一緒に再ビルドします。プリロードの設定は本番環境とパフォーマンスで扱います。
  • 既存のディレクトリに対して実行すると、コマンドはソースが変わった(サイズまたは更新日時)ファイルをすべてコンパイルし直し、ほかのファイルはそのまま残します。PREBUILT_CACHE でも同様です。キャッシュの中身を現在のリリースとぴったり一致させたいときは、空のディレクトリから始めてください。
ターミナルウィンドウ
vendor/bin/aspect cache:warmup:opcache public/index.php --file-cache=/var/cache/opcache --entry=public/index.php

本番のリクエストが読み込むもの、つまりフレームワークのキャッシュ、Composer のクラスマップとオートロードされるファイル、変換されないソース、ローダー、エントリーポイントを opcache.file_cache にコンパイルします。こうすると、新しい PHP-FPM のマスタープロセスや CLI のプロセスは、スクリプトをコンパイルする代わりに、コンパイル済みのスクリプトをディスクから読みます。

オプション 用途
--file-cache=DIR opcache.file_cache のディレクトリ。設定されているものと一致していなければなりません。
--entry=FILE コンパイルするエントリーポイント。複数のファイルには繰り返し指定します。

コンパイル済みのスクリプトがディスクに書き込まれるのは、-d opcache.enable_cli=1 -d opcache.file_cache_only=1 -d opcache.file_cache=DIR 付きで起動したプロセスだけです。これらなしでコマンドを実行すると、実行すべき正確なコマンドが表示されます。

ファイルキャッシュは、PHP のビルドとファイルの絶対パスに結び付いています。このコマンドは最終的なイメージの中で、cache:warmup:aop の後に、リクエストを処理する PHP のバイナリで実行してください。フレームワークのキャッシュ、ローダー、エントリーポイントはコンパイルできなければならず、できなければコマンドは失敗します。Composer のクラスマップに含まれるファイルでコンパイルできないものは、一覧表示されてスキップされます。

ターミナルウィンドウ
vendor/bin/aspect debug:aspect public/index.php

登録された behavior class とその behavior を一覧表示します。--aspect=... オプションも受け付けます。

ターミナルウィンドウ
vendor/bin/aspect debug:advisor public/index.php

advisor を一覧表示します。--advisor=... を付けると、その advisor がマッチするインターセプト対象の呼び出しを表示するので、matching rule が期待どおりのメソッドを選んでいるかどうかがわかります。

ターミナルウィンドウ
vendor/bin/aspect debug:weaving public/index.php

キャッシュを 2 回ウォームアップし、2 回の実行で生成結果が異なるプロキシを報告します。違いがあれば、非決定的な behavior class があることを示しています。

ターミナルウィンドウ
rm -rf var/cache/aop
vendor/bin/aspect cache:warmup:aop public/index.php --workers=8
  1. キャッシュディレクトリを空にします。
  2. cache:warmup:aop でキャッシュをウォームアップします。ファイルをコンパイルできないとコマンドは失敗するので、デプロイは不完全なキャッシュを出荷する前に止まります。大きなプロジェクトは、--workers で並列にコンパイルすると速くなります。
  3. 'debug' => false と Features::PREBUILT_CACHE で実行します。
public/index.php
use Go\Aop\Features;
ApplicationAspectKernel::getInstance()->init([
'debug' => false,
'appDir' => __DIR__ . '/..',
'cacheDir' => __DIR__ . '/../var/cache/aop',
'includePaths' => [__DIR__ . '/../src'],
'features' => Features::PREBUILT_CACHE,
]);

コード、behavior class、カーネルのオプション、composer.lock が変わるたびにキャッシュを再ビルドしてください。実際には、デプロイのたびにということです。開発モードでは再ビルドは不要です。

OPcache のチューニング、プリロード、Composer のオートローダーのフラグ、Docker イメージへのキャッシュの組み込みは本番環境とパフォーマンスにあります。キャッシュのフォーマットの変更を含む 3.x からのアップグレードは制限事項とアップグレードにあります。

© 2026 Alexander Lisachenko