コンテンツにスキップ
ドキュメント · インテグレーション

Laravel

ルートだけでなく、あらゆるメソッドに middleware を。goaop/goaop-laravel-bridge 2.0 がクラスに behavior を取り付け、あとは Laravel のコンテナ、設定、Artisan が引き受けます。

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

middleware(ミドルウェア)は、Laravel の優れたアイデアの 1 つです。リクエストは小さなクラスの積み重ねを通り抜け、各クラスはコントローラーに手を触れずに、1 つのこと(認証、スロットリング、セッション)だけを加えます。ブリッジ goaop/goaop-laravel-bridge 2.0 は、このアイデアを、public、protected、private を問わず アプリケーションのあらゆるメソッドとプロパティ に広げます。behavior(振る舞い)を一度書き、どこに適用するかを指定すれば、それがその呼び出しを包む動的な middleware として動きます:サービス、アクション、ジョブ、そのほか app/ にあるあらゆるクラスで。

app/Services/OrderService.php
use App\Attributes\Transactional;
final class OrderService
{
public function __construct(private readonly Inventory $inventory) {}
#[Transactional]
public function place(Cart $cart): Order
{
$order = Order::create(['customer_id' => $cart->customerId]);
$order->lines()->createMany($cart->lines());
$this->inventory->reserve($cart);
return $order;
}
}
app/Behaviors/TransactionalBehavior.php
namespace App\Behaviors;
use Go\Aop\Aspect;
use Go\Aop\Intercept\MethodInvocation;
use Go\Lang\Attribute\Around;
use Illuminate\Support\Facades\DB;
final class TransactionalBehavior implements Aspect
{
#[Around('@execution(App\Attributes\Transactional)')]
public function inTransaction(MethodInvocation $invocation): mixed
{
return DB::transaction(fn () => $invocation->proceed());
}
}

パターンはこれだけです。middleware の handle($request, $next) を書いたことがあれば、もう知っている形です:$invocation->proceed() が $next($request) にあたります。#[Transactional] を付けたメソッドはすべて、1 つの単位としてコミットまたはロールバックされるようになり、OrderService はビジネスロジックだけを保ったままです。基底クラスも、インターフェースも、デコレーターも、app()->extend() の呼び出しも要りません。

Laravel の一部のように感じられる理由

Section titled “Laravel の一部のように感じられる理由”
  • 他のパッケージと同じようにインストールできる。 composer require を実行すれば、パッケージディスカバリーがサービスプロバイダーを登録します。公開できる設定ファイルは config/go_aop.php の 1 つだけで、GOAOP_* 環境変数で上書きできます。
  • behavior class(振る舞いクラス)はコンテナサービス。 Laravel のコンテナは、各 behavior class を、その behavior のいずれかが初めて実行されたときに生成します。コンストラクターインジェクションが使え、ファサード、config()、アプリケーションがバインドしたあらゆるサービスも使えます。
  • 他のものと同じ場所で登録する。 設定にクラスを列挙するか、サービスプロバイダーでサービスに goaop.aspect タグを付けます。これにより、パッケージが独自の behavior を提供することもできます。
  • 本番向けの作業は Artisan が担う。 php artisan aop:warmup はデプロイ時にキャッシュをビルドし、必要なら並列ワーカーで処理します。composer install と php artisan optimize の後に置けば、今のデプロイ手順にそのまま収まります。php artisan about には、キャッシュの場所とデバッグモードが表示されます。
  • 開発時にビルドステップは不要。 debug をオンにすると、変更されたクラスは次のリクエストで再びコンパイルされ、ブレークポイントは元のファイルで動作します。

デコレーターには届かず、behavior には届くもの

Section titled “デコレーターには届かず、behavior には届くもの”

デコレーターはコンテナから解決したオブジェクトを包むため、見えるのは public メソッドだけで、しかもその経路を通った場合に限られます。behavior は、クラスの読み込み時にクラス自体に取り付けられます。そのため:

  • すべてのインスタンスに適用される。 コンテナから得たオブジェクトも、new で生成したオブジェクトも、同じように振る舞います。ラッパーオブジェクトが存在しないので、型ヒント、instanceof、クラス名は変わりません。
  • あらゆる種類のメソッドが対象になる。 private、protected、final、static メソッド、そして final クラスや readonly クラスのメソッドも対象です(Intercept anything)。
  • プロパティも対象になる。 public、protected、private のプロパティ(コンストラクターでプロモートされたものを含む)の読み書きを、PHP 8.4 ネイティブのプロパティフックで扱います:access(private App\Domain\Order->status) や @access(App\Attributes\Audited)(プロパティへの behavior)。
  • 1 つのルールで名前空間全体を扱える。 execution(public App\Services\**->*(*)) は、App\Services 配下のすべての public メソッドを選びます。来月追加するクラスも含まれます(matching rule(マッチングルール))。
  • コストは小さい。 behavior のないメソッドとプロパティには、追加のコストはかかりません。behavior を持つメソッドやプロパティでも、呼び出しあたり 1 µs 未満です(実測したコスト)。
  • 素の PHP である。 PECL 拡張も eval() も使いません。コンパイルされたクラスは storage/framework/aop にある普通の .php ファイルなので、中身を読めます(Pure PHP)。
  • PHP 8.4 以降
  • Laravel 12 または 13
  • goaop/framework ^4.0(behavior は属性で宣言)。ブリッジと一緒にインストールされます
ターミナルウィンドウ
composer require goaop/goaop-laravel-bridge

パッケージディスカバリーが、サービスプロバイダーを自動で登録します。設定を変更したい場合は、設定ファイルを公開します:

ターミナルウィンドウ
php artisan vendor:publish --tag=goaop-config

API で言う aspect(アスペクト)にあたる behavior class は、Go\Aop\Aspect を実装する普通のクラスです。#[Before]、#[After]、#[Around]、#[AfterThrowing] が付いた public メソッドの 1 つ 1 つが behavior です。その属性に書く文字列が matching rule で、API で言う pointcut(ポイントカット)にあたります:behavior がどこで動くかを指定するものです。

  1. 属性を作成し、メソッドに目印を付けられるようにします。この手順を飛ばして、メソッドを名前で選ぶこともできます(次のセクションを参照)。

    app/Attributes/Transactional.php
    namespace App\Attributes;
    use Attribute;
    #[Attribute(Attribute::TARGET_METHOD)]
    final class Transactional {}
  2. behavior class を書きます。 このページの冒頭にある TransactionalBehavior で完成です。#[Around] はメソッドの代わりに behavior を実行し、@execution(App\Attributes\Transactional) はこの属性が付いたすべてのメソッドを選びます。

  3. config/go_aop.php で behavior class を登録します:

    config/go_aop.php
    'aspects' => [
    App\Behaviors\TransactionalBehavior::class,
    ],
  4. メソッドに #[Transactional] で 目印を付け、呼び出します。次のリクエストから、そのメソッドはトランザクションの中で実行されます。

behavior には、対象側の属性は必要ありません。matching rule は名前、名前空間、可視性でメソッドを選べるので、アプリケーションの 1 つの層全体に、そのクラスを一切変更せずに behavior を適用できます:

app/Behaviors/ServiceTimingBehavior.php
namespace App\Behaviors;
use Go\Aop\Aspect;
use Go\Aop\Intercept\MethodInvocation;
use Go\Lang\Attribute\Around;
use Go\Lang\Attribute\Before;
use Illuminate\Support\Facades\Log;
final class ServiceTimingBehavior implements Aspect
{
#[Before('execution(public App\Services\**->*(*))')]
public function logCall(MethodInvocation $invocation): void
{
Log::debug('Calling ' . $invocation->getMethod()->getName());
}
#[Around('execution(public App\Services\PaymentService->charge(*))')]
public function measureCharge(MethodInvocation $invocation): mixed
{
$start = hrtime(true);
try {
return $invocation->proceed();
} finally {
Log::info('charge() took ' . (hrtime(true) - $start) / 1e6 . ' ms');
}
}
}

logCall() は、App\Services 配下のすべての public メソッドの前に実行されます。measureCharge() は 1 つのメソッドを包み、例外が投げられた場合も含めて時間を計測します。4 つの属性、call context(呼び出しコンテキスト)である $invocation、そしてルールの構文の全体は、振る舞いとマッチングルールにあります。一通りの実例は、キャッシュの振る舞いとロギングの振る舞いを参照してください。

behavior class を自分でエンジンに渡すことはありません。ブートフェーズの間、すべてのサービスプロバイダーが登録を終えた後、アプリケーションのコードが動く前に、ブリッジが 2 つのソースからそれらを集めます。

設定のリスト。 上の手順のように、config/go_aop.php にクラスを列挙します。列挙したクラスは、クラスを読み込むことなく、カーネルの起動と同時に登録されます。Laravel のコンテナは、behavior のいずれかが初めて呼ばれたときにそのクラスを解決するので、behavior class は、アプリケーションが完全に起動して初めて存在するサービスに依存しても構いません。behavior を 1 つも実行しないリクエストでは、behavior class は生成されません。

goaop.aspect タグ。 サービスプロバイダーの中で、サービスにタグを付けます:

app/Providers/AppServiceProvider.php
use App\Behaviors\ServiceTimingBehavior;
use Psr\Log\LoggerInterface;
// in register()
$this->app->singleton(ServiceTimingBehavior::class, function ($app) {
return new ServiceTimingBehavior($app->make(LoggerInterface::class));
});
$this->app->tag([ServiceTimingBehavior::class], 'goaop.aspect');

behavior class の生成に込み入った処理が必要な場合や、パッケージが設定に手を触れずに behavior class を提供する場合は、タグを使ってください。タグ付けされたサービスは、ブリッジのプロバイダーが起動したときに解決されます。Laravel のタグは、そのサービスを解決しなければ列挙できないためです。コンストラクターが重い、あるいは起動処理に依存する behavior class には、設定のリストを使ってください。

2 つのソースは併用でき、重複は 1 回だけ登録されます。見つかったクラスが Go\Aop\Aspect を実装していない場合は、内容のわかる例外で失敗します。Laravel のコンテナは、PSR-11 のデリゲートとしてカーネルのコンテナに接続されるので、behavior や behavior class のファクトリは、それを通じてアプリケーションのサービスを取得できます。

config/go_aop.php の主なオプションです。それぞれ環境変数で上書きできます。

オプション デフォルト 用途
debug GOAOP_DEBUG → APP_DEBUG ソースが変わったら再コンパイルし、ブレークポイントを元のファイルで使えるようにする。本番ではオフにする
appDir base_path() コンパイラーが触れてよいルートディレクトリ
cacheDir storage_path('framework/aop')(GOAOP_CACHE_DIR) コンパイルされたソースとプロキシのキャッシュ先
cacheFileMode 0770(GOAOP_CACHE_PERMISSIONS、8 進数の数字。例:"770") キャッシュファイルの chmod
parsedFilesLimit 100(GOAOP_PARSED_FILES_LIMIT) コンパイル中にメモリに保持するパース済みソースファイルの数(1 つあたり約 0.2 MB)。aop:warmup --cached-files のデフォルト
includePaths [app_path()] コンパイルするのはこれらのディレクトリだけ
excludePaths [] これらは決してコンパイルしない
features 0(GOAOP_FEATURES) Go\Aop\Features フラグのビットマスク:INTERCEPT_INCLUDES = 4、PREBUILT_CACHE = 64、PARTIAL_REFLECTION = 256
aspects [] 登録する behavior class

関数呼び出しやオブジェクト生成への behavior は、その matching rule によって有効になり、フラグは不要です。php artisan about には、フレームワークのキャッシュの現在の場所とデバッグモードが表示されます。

ターミナルウィンドウ
php artisan aop:warmup

ウォームアップしない場合、各クラスは最初の読み込み時にコンパイルされます。デプロイ時に aop:warmup を実行すると、すべてを事前にコンパイルできます。debug をオフにするなら、これを推奨します。コンパイルできないファイルがあるとコマンドは 0 以外のステータスで終了するため、デプロイスクリプトは不完全なキャッシュを出荷せずに止まります。最初のエラーで止めるには、--fail-fast を付けます。

ターミナルウィンドウ
php artisan aop:warmup --workers=8
php artisan aop:warmup --cache-dir=/srv/app/releases/next/storage/framework/aop
php artisan aop:warmup --preload
  • --workers=N は、並列のワーカープロセスでコンパイルします。各ワーカーはアプリケーション自身の artisan なので、同じ環境、設定、behavior class で起動します。
  • --cache-dir=DIR は、稼働中のリリースの隣で、新しいリリースのキャッシュをビルドします。この方法でビルドしたキャッシュは完全で、配置場所に依存しません。
  • --preload は opcache.preload スクリプトを書き出します。出力先は、ビルド中のキャッシュディレクトリの _preload.php、または --preload=FILE で指定したファイルです。

コンパイル済みのスクリプトをコンテナイメージと一緒に出荷するには、最終イメージの中で、ウォームアップと php artisan optimize の後に opcache.file_cache を充填します:

ターミナルウィンドウ
php artisan optimize
mkdir -p /var/cache/opcache && php -d opcache.enable_cli=1 -d opcache.file_cache_only=1 \
-d opcache.file_cache=/var/cache/opcache \
artisan aop:warmup-opcache --file-cache=/var/cache/opcache
ターミナルウィンドウ
composer install --no-dev --optimize-autoloader # runs package:discover, with an empty framework cache
php artisan optimize # the cached configuration carries GOAOP_FEATURES
php artisan aop:warmup

GOAOP_FEATURES=64(PREBUILT_CACHE)では、リクエストがコンパイルすることはありません。キャッシュにない include パス配下のクラスは WeavingException で失敗するので、デプロイのたびに aop:warmup を実行してください。Laravel のキャッシュコマンド(package:discover、optimize、optimize:clear、そして config、event、route、view のキャッシュコマンドとクリアコマンド)はリクエストを処理しないため、クラスを元のソースから読み込みます。上の順序で問題なく動くのは、このためです。

設定がキャッシュされると、env() は読まれなくなります。optimize(または config:cache)は、GOAOP_FEATURES を含む本番の環境で実行してください。完全なチェックリストは本番環境とパフォーマンスにあります。

  • compile step(コンパイルステップ)は、ブートフェーズの最初に始まります。それより前に読み込まれたクラス(ごく初期のブートストラップコード、他のパッケージの register() の内部、自分のサービスプロバイダー)には、behavior を付けられません。
  • 対象になるのは、appDir と includePaths 配下のクラスだけです。vendor のコードはコンパイルされません。
  • 例外ハンドラーは excludePaths で除外してください:致命的エラーが起きたとき、コンパイルされたハンドラーはコールドなキャッシュから読み込めない可能性があります。

© 2026 Alexander Lisachenko