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

はじめに

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 つのステップで終わります。

  1. Composer でフレームワークをインストールする。
  2. アプリケーションのカーネルを作成する。
  3. フロントコントローラーでカーネルを初期化する。
  4. behavior class を書く。
  5. behavior class をカーネルに登録する。
ターミナルウィンドウ
composer require goaop/framework

Composer はフレームワークを vendor/goaop/framework にインストールします。

このページのサンプルは次のディレクトリ構成を前提とし、app/ と src/ のクラスが Composer でオートロードされることを想定しています。たとえば composer.json の autoload セクションで設定します。

app/ApplicationAspectKernel.php the kernel
public/index.php the front controller
src/ your application code, compiled by the framework
src/Aspect/MonitorAspect.php your first behavior class
var/cache/aop/ the cache of generated code
app/ApplicationAspectKernel.php
<?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 “フロントコントローラーでカーネルを初期化する”
public/index.php
<?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 here

init() は一度だけ、Composer のオートローダーの直後、アプリケーションが自身のクラスを読み込む前に呼び出します。始めるにはこの 4 つのオプションで十分です。

オプション 用途
debug true で開発モードになります。本番環境では false を使います。
appDir アプリケーションのルートです。この下にあるファイルだけがコンパイルされます。デフォルトは vendor/ を含むディレクトリです。
cacheDir 生成されたコードの書き込み先です。このオプションは必須です。
includePaths コンパイルするディレクトリです。空の配列は appDir の下のすべてを意味します。

includePaths は狭く保ってください。vendor のコードのコンパイルは遅く、必要になることはまずありません。未知のオプションキーは Go\Aop\Exception\InvalidConfigurationException を投げるので、タイプミスは無視されずにその場で失敗します。オプションの一覧は設定と CLI のページにあります。

src/Aspect/MonitorAspect.php
<?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 つまでです。

app/ApplicationAspectKernel.php
<?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 のページで説明しています。

matching rule が選ぶクラスを追加します。

src/Example.php
<?php
class Example
{
public function greet(string $name): string
{
return "Hello, {$name}";
}
}

そして、フロントコントローラーの init() の後でそれを使います。

public/index.php
<?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 の完全な構文は、振る舞いとマッチングルールのページで説明しています。

bin/aspect コンソールには symfony/console が必要です。

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

debug:aspect は、登録された behavior class とその behavior を一覧表示します。bin/aspect のどのコマンドも、カーネルを初期化するファイル(ここではフロントコントローラー)へのパスを受け取り、そのファイルを実行します。debug:advisor --advisor=... は、1 つの advisor(アドバイザー。behavior とその matching rule の組み合わせ)がマッチするインターセプト対象の呼び出しを表示します。behavior が実行されないときは、これらのコマンドを使ってください。

クラスは PHP が読み込むときにコンパイルされます。実行時にオブジェクトを何かで包むことはなく、eval() でコードを生成することもありません。コンパイルされたクラスはそれぞれキャッシュディレクトリ内の普通の PHP ファイルで、PHP が実行するのはそのファイルです。

コンパイルされたクラスでは、元のクラス本体がトレイトに移されます。元のクラス名を持つ生成クラスがそのトレイトを使うので、クラス名、親クラス、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 にも選ばれないメソッドは、インターセプト用のコードなしで実行されます。

cacheDir には、コンパイル済みのソース、プロキシ、advisor のキャッシュ、クラスマップが置かれます。キャッシュのパスは、appDir を基準としたソースのパスと同じ構成になります。ファイルは普通の PHP なので、開いたり、diff を取ったり、セキュリティツールでスキャンしたりできます。

キャッシュディレクトリはコミットしないでください。開発中は、クラスが読み込まれるたびにフレームワークがキャッシュを埋めていきます。本番環境では、デプロイ時にキャッシュをビルドします。

'debug' => true では、すべてのクラスとすべての include がフレームワークのストリームフィルターを通して読み込まれ、そこでコンパイルされます。カーネルのファイルと behavior class のファイルを変更するとキャッシュは無効になり、変更されたファイルは次のリクエストで再びコンパイルされます。ビルドステップはありません。クラスや behavior を編集して、ページを再読み込みするだけです。

ホットなリクエストでは、開発モードは本番モードより目に見えて遅くなります。本番環境では使わないでください。

'debug' => false では、コンパイル済みのクラスが Composer のクラスマップを通してキャッシュから読み込まれます。ウォームなリクエストでは、パーサーとトランスフォーマーは読み込まれません。

デプロイでは、キャッシュを一度ビルドし、カーネルにそれを信頼させます。

  1. キャッシュディレクトリを空にします。

  2. キャッシュをウォームアップします。

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

    ファイルをコンパイルできないとコマンドは失敗するので、デプロイスクリプトは不完全なキャッシュを出荷する前に止まります。大きなプロジェクトは、たとえば --workers=8 を付けて並列にコンパイルすると速くなります。

  3. '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 については本番環境とパフォーマンスのページで扱います。

アプリケーションが Symfony、Laravel、Yii3 で動いているなら、フロントコントローラーのコードを自分で書く代わりに、そのフレームワーク用のブリッジをインストールしてください。ブリッジはアプリケーションのライフサイクルの早い段階でフレームワークを起動し、behavior class をフレームワークのコンテナのサービスとして登録できるようにします。インテグレーションのページ、またはリポジトリ goaop/goaop-symfony-bundle、goaop/goaop-laravel-bridge、goaop/goaop-yii3-bridge を参照してください。

バージョン 3.x のアプリケーションをアップグレードする場合は、まず制限事項とアップグレードのページを読んでください。すべての変更点がまとめてあります。

フレームワークのリポジトリは、コーディングエージェント向けのプラグインマーケットプレイスでもあります。その goaop プラグインには Agent Skill が含まれており、behavior class、behavior、matching rule の書き方、フレームワークの組み込み、キャッシュのデプロイ、behavior が実行されない原因の調べ方をエージェントに教えます。Claude Code では次のようにします。

/plugin marketplace add goaop/framework
/plugin install goaop@goaop

© 2026 Alexander Lisachenko