はじめに
Composer でフレームワークをインストールし、カーネルを作成して、最初の behavior を書き、それがコードの周りで実行される様子を確かめます。
このページは英語版からの翻訳です。基準となるのは英語版のページです。 原文を読む
ロギング、キャッシュ、セキュリティチェック、トランザクションといった behavior(振る舞い)は一度だけ書けば、フレームワークがそれを動的な middleware(ミドルウェア)として、選んだすべてのメソッドに付け加えます。コード上では、behavior は behavior class(振る舞いクラス)にまとめます。API での名前は aspect(アスペクト)です。各 behavior はメソッドで、その属性がいつ実行されるかを示し、どこで実行されるかを示す matching rule(マッチングルール)を持ちます。あなたのクラスに残るのはビジネスロジックだけです。API の名前とこのドキュメントで使う言葉の対応は用語表にまとめてあります。
- PHP 8.4 以降。 モダンな PHP のすべてのバージョンで動作します。
- PECL や PIE の拡張は不要。 純粋な PHP で書かれており、
php-aop、runkit、uopzもeval()も使いません。使うのはtokenizer拡張です。 - Composer。 フレームワークとその依存パッケージは、通常の Composer パッケージとしてインストールされます。
導入は 5 つのステップで終わります。
- Composer でフレームワークをインストールする。
- アプリケーションのカーネルを作成する。
- フロントコントローラーでカーネルを初期化する。
- behavior class を書く。
- behavior class をカーネルに登録する。
Composer でインストールする
Section titled “Composer でインストールする”composer require goaop/frameworkComposer はフレームワークを vendor/goaop/framework にインストールします。
このページのサンプルは次のディレクトリ構成を前提とし、app/ と src/ のクラスが Composer でオートロードされることを想定しています。たとえば composer.json の autoload セクションで設定します。
app/ApplicationAspectKernel.php the kernelpublic/index.php the front controllersrc/ your application code, compiled by the frameworksrc/Aspect/MonitorAspect.php your first behavior classvar/cache/aop/ the cache of generated codeカーネルを作成する
Section titled “カーネルを作成する”<?php
use Go\Core\AspectContainer;use Go\Core\AspectKernel;
/** * The application kernel */class ApplicationAspectKernel extends AspectKernel{ /** * Register the behavior classes in the container */ protected function configureAop(AspectContainer $container): void { }}カーネルは、アプリケーションのすべての behavior class を 1 か所で管理します。抽象クラス Go\Core\AspectKernel を継承し、configureAop() を実装します。今は空のままで構いません。最初の behavior class はこのあと、ここに登録します。
フロントコントローラーでカーネルを初期化する
Section titled “フロントコントローラーでカーネルを初期化する”<?php
include __DIR__ . '/../vendor/autoload.php'; // use composer
// Initialize the kernel$applicationAspectKernel = ApplicationAspectKernel::getInstance();$applicationAspectKernel->init([ 'debug' => true, // use 'false' for production mode 'appDir' => __DIR__ . '/..', // Application root directory 'cacheDir' => __DIR__ . '/../var/cache/aop', // Cache directory // Directories whose classes get behaviors; empty means all source files 'includePaths' => [ __DIR__ . '/../src/' ]]);
// Your application starts hereinit() は一度だけ、Composer のオートローダーの直後、アプリケーションが自身のクラスを読み込む前に呼び出します。始めるにはこの 4 つのオプションで十分です。
| オプション | 用途 |
|---|---|
debug |
true で開発モードになります。本番環境では false を使います。 |
appDir |
アプリケーションのルートです。この下にあるファイルだけがコンパイルされます。デフォルトは vendor/ を含むディレクトリです。 |
cacheDir |
生成されたコードの書き込み先です。このオプションは必須です。 |
includePaths |
コンパイルするディレクトリです。空の配列は appDir の下のすべてを意味します。 |
includePaths は狭く保ってください。vendor のコードのコンパイルは遅く、必要になることはまずありません。未知のオプションキーは Go\Aop\Exception\InvalidConfigurationException を投げるので、タイプミスは無視されずにその場で失敗します。オプションの一覧は設定と CLI のページにあります。
最初の behavior を書く
Section titled “最初の behavior を書く”<?php
namespace Aspect;
use Go\Aop\Aspect;use Go\Aop\Intercept\MethodInvocation;use Go\Lang\Attribute\Before;
/** * A monitoring behavior class */class MonitorAspect implements Aspect{ /** * Method that will be called before real method */ #[Before("execution(public Example->*(*))")] public function beforeMethodExecution(MethodInvocation $invocation): void { echo 'Calling Before Interceptor for: ', $invocation, ' with arguments: ', json_encode($invocation->getArguments()), "<br>\n"; }}behavior class は、Go\Aop\Aspect を実装する普通の PHP クラスです。各 behavior は public メソッドで、いつ実行されるかを示す Go\Lang\Attribute の属性を 1 つ持ちます。
#[Before]の behavior は、インターセプトされた呼び出しの前に実行されます。ほかの属性は#[After]、#[AfterThrowing]、#[Around]です。- 属性の文字列が matching rule です。
execution(public Example->*(*))は、クラスExampleのすべての public かつ非 static なメソッドの実行を選びます。 - behavior は
MethodInvocationを受け取ります。これがインターセプトされた呼び出しを表します。getArguments()はその引数を返し、invocation を文字列に変換するとメソッド名になります。
behavior のメソッドは public でなければなりません。フレームワークは behavior class のインスタンスに対してそれらを直接呼び出すため、protected や private の behavior メソッドはクラスの読み込み時に拒否されます。1 つのメソッドに付けられる behavior の属性は 1 つまでです。
behavior class を登録する
Section titled “behavior class を登録する”<?php
use Aspect\MonitorAspect;use Go\Core\AspectContainer;use Go\Core\AspectKernel;
class ApplicationAspectKernel extends AspectKernel{ /** * Register the behavior classes in the container */ protected function configureAop(AspectContainer $container): void { // Deferred (recommended): constructed on first use $container->addLazyService(MonitorAspect::class, static fn() => new MonitorAspect()); }}behavior class はカーネルのコンテナのサービスです。addLazyService() はファクトリを登録します。compile step(コンパイルステップ)は behavior class を読むだけなので、ファクトリが実行されるのは、その behavior のいずれかが初めて実行されるときです。それより前ではありません。
behavior class を最初から生成しておきたい場合は、代わりにインスタンスを登録します。
$container->add(MonitorAspect::class, new MonitorAspect());behavior class は、アプリケーションの PSR-11 コンテナから依存関係を受け取ることもできます。そのコンテナは setDelegate() でカーネルのコンテナに接続します。方法は設定と CLI のページで説明しています。
動かしてみる
Section titled “動かしてみる”matching rule が選ぶクラスを追加します。
<?php
class Example{ public function greet(string $name): string { return "Hello, {$name}"; }}そして、フロントコントローラーの init() の後でそれを使います。
<?php
include __DIR__ . '/../vendor/autoload.php';
ApplicationAspectKernel::getInstance()->init([/* … as above … */]);
$example = new Example();echo $example->greet('World');ブラウザーでページを開くか、php public/index.php を実行します。Hello, World の前に、メソッド名と引数 ["World"] を含む behavior の出力行が表示されます。Example は behavior class をまったく参照していません。behavior は、オートローダーがクラスを読み込んでコンパイルしたときに、そのクラスに付け加えられました。
behavior を自分で呼び出すことはありません。どのメソッドで実行するかを変えたいときは、クラスではなく matching rule を変更します。各 behavior がいつ実行されるか、そして matching rule の完全な構文は、振る舞いとマッチングルールのページで説明しています。
登録内容を確認する
Section titled “登録内容を確認する”bin/aspect コンソールには symfony/console が必要です。
composer require symfony/consolevendor/bin/aspect debug:aspect public/index.phpdebug:aspect は、登録された behavior class とその behavior を一覧表示します。bin/aspect のどのコマンドも、カーネルを初期化するファイル(ここではフロントコントローラー)へのパスを受け取り、そのファイルを実行します。debug:advisor --advisor=... は、1 つの advisor(アドバイザー。behavior とその matching rule の組み合わせ)がマッチするインターセプト対象の呼び出しを表示します。behavior が実行されないときは、これらのコマンドを使ってください。
compile step の仕組み
Section titled “compile step の仕組み”クラスは PHP が読み込むときにコンパイルされます。実行時にオブジェクトを何かで包むことはなく、eval() でコードを生成することもありません。コンパイルされたクラスはそれぞれキャッシュディレクトリ内の普通の PHP ファイルで、PHP が実行するのはそのファイルです。
生成されるコード
Section titled “生成されるコード”コンパイルされたクラスでは、元のクラス本体がトレイトに移されます。元のクラス名を持つ生成クラスがそのトレイトを使うので、クラス名、親クラス、self:: は元のままです。インターセプトされる各メソッドは、behavior を伴った call context(呼び出しコンテキスト)を持ちます。
static $__joinPoint = InterceptorInjector::forMethod( self::class, 'doSomething', [ Interceptor::before(The::aspect(MonitorAspect::class)->beforeMethodExecution(...)), ], $this->doSomethingOriginalAlias(...),);The::aspect() は、カーネルのコンテナから behavior class のインスタンスを取得します。->beforeMethodExecution(...) はあなたが書いた behavior メソッドで、first-class callable 構文で参照されています。IDE で Ctrl キーを押しながらクリックしてジャンプでき、その中にブレークポイントを置いて生成コードをステップ実行できます。最後の引数は元のメソッド本体を指します。
行番号は保たれるので、元のコードに置いた Xdebug のブレークポイントはそのまま機能します。クラス、そのメソッド、パラメーター、定数、プロパティの属性は生成コードにコピーされるため、リフレクションでそれらを読む処理も以前と同じように動きます。どの matching rule にも選ばれないメソッドは、インターセプト用のコードなしで実行されます。
キャッシュディレクトリ
Section titled “キャッシュディレクトリ”cacheDir には、コンパイル済みのソース、プロキシ、advisor のキャッシュ、クラスマップが置かれます。キャッシュのパスは、appDir を基準としたソースのパスと同じ構成になります。ファイルは普通の PHP なので、開いたり、diff を取ったり、セキュリティツールでスキャンしたりできます。
キャッシュディレクトリはコミットしないでください。開発中は、クラスが読み込まれるたびにフレームワークがキャッシュを埋めていきます。本番環境では、デプロイ時にキャッシュをビルドします。
'debug' => true では、すべてのクラスとすべての include がフレームワークのストリームフィルターを通して読み込まれ、そこでコンパイルされます。カーネルのファイルと behavior class のファイルを変更するとキャッシュは無効になり、変更されたファイルは次のリクエストで再びコンパイルされます。ビルドステップはありません。クラスや behavior を編集して、ページを再読み込みするだけです。
ホットなリクエストでは、開発モードは本番モードより目に見えて遅くなります。本番環境では使わないでください。
'debug' => false では、コンパイル済みのクラスが Composer のクラスマップを通してキャッシュから読み込まれます。ウォームなリクエストでは、パーサーとトランスフォーマーは読み込まれません。
デプロイでは、キャッシュを一度ビルドし、カーネルにそれを信頼させます。
-
キャッシュディレクトリを空にします。
-
キャッシュをウォームアップします。
ターミナルウィンドウ vendor/bin/aspect cache:warmup:aop public/index.phpファイルをコンパイルできないとコマンドは失敗するので、デプロイスクリプトは不完全なキャッシュを出荷する前に止まります。大きなプロジェクトは、たとえば
--workers=8を付けて並列にコンパイルすると速くなります。 -
'debug' => falseと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,]);
PREBUILT_CACHE を使うと、リクエストがコンパイルを行うことも、キャッシュディレクトリに書き込むことも一切ないため、読み取り専用のファイルシステムでも動作します。キャッシュは完全でなければなりません。include パスの下にあるクラスのうち、キャッシュに記録のないものがあると、そのリクエストは WeavingException で失敗します。コードや behavior class が変わるたびにキャッシュを再ビルドしてください。
OPcache、プリロード、Docker、Kubernetes については本番環境とパフォーマンスのページで扱います。
次に読むもの
Section titled “次に読むもの”フレームワークを使う場合
Section titled “フレームワークを使う場合”アプリケーションが Symfony、Laravel、Yii3 で動いているなら、フロントコントローラーのコードを自分で書く代わりに、そのフレームワーク用のブリッジをインストールしてください。ブリッジはアプリケーションのライフサイクルの早い段階でフレームワークを起動し、behavior class をフレームワークのコンテナのサービスとして登録できるようにします。インテグレーションのページ、またはリポジトリ goaop/goaop-symfony-bundle、goaop/goaop-laravel-bridge、goaop/goaop-yii3-bridge を参照してください。
3.x からのアップグレード
Section titled “3.x からのアップグレード”バージョン 3.x のアプリケーションをアップグレードする場合は、まず制限事項とアップグレードのページを読んでください。すべての変更点がまとめてあります。
AI コーディングエージェント
Section titled “AI コーディングエージェント”フレームワークのリポジトリは、コーディングエージェント向けのプラグインマーケットプレイスでもあります。その goaop プラグインには Agent Skill が含まれており、behavior class、behavior、matching rule の書き方、フレームワークの組み込み、キャッシュのデプロイ、behavior が実行されない原因の調べ方をエージェントに教えます。Claude Code では次のようにします。
/plugin marketplace add goaop/framework/plugin install goaop@goaop© 2026 Alexander Lisachenko
