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

Symfony

goaop/goaop-symfony-bundle 4.0 による Symfony との連携:自動設定される behavior class、Web プロファイラーのパネル、キャッシュのウォームアップ。

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

バンドル goaop/goaop-symfony-bundle 4.0 は、サービスが読み込まれる時点で behavior(振る舞い)をサービスに取り付けます。基底クラスもデコレーターも必要ありません。

namespace App\Aspect;
use Go\Aop\Aspect;
use Go\Aop\Intercept\MethodInvocation;
use Go\Lang\Attribute\Around;
use Psr\Log\LoggerInterface;
final class TimingAspect implements Aspect
{
public function __construct(private readonly LoggerInterface $logger) {}
#[Around('execution(public App\Service\**->*(*))')]
public function measure(MethodInvocation $invocation): mixed
{
$start = hrtime(true);
try {
return $invocation->proceed();
} finally {
$this->logger->info('{method} took {ms} ms', [
'method' => (string) $invocation,
'ms' => (hrtime(true) - $start) / 1e6,
]);
}
}
}

連携に必要なのはこれだけです。このクラスは Go\Aop\Aspect を実装しているので、オートコンフィギュレーションによって behavior class(振る舞いクラス)として登録され、オートワイヤリングでロガーが渡されます。次のリクエストから、App\Service 配下にあるすべてのクラスの、すべての public メソッドの実行時間が計測されます。

  • PHP 8.4 以降
  • Symfony 7.4 または 8.x
  • goaop/framework ^4.0(behavior は属性で宣言)

バンドルのインストールと有効化

Section titled “バンドルのインストールと有効化”
ターミナルウィンドウ
composer require goaop/goaop-symfony-bundle

バンドルを、config/bundles.php の 最初の エントリーとして登録します:

config/bundles.php
return [
Go\Symfony\GoAopBundle\GoAopBundle::class => ['all' => true],
Symfony\Bundle\FrameworkBundle\FrameworkBundle::class => ['all' => true],
// ...
];

compile step(コンパイルステップ)が適用されるのは、カーネルの初期化後に読み込まれたクラスだけで、バンドルは登録順に起動します。バンドルはこの順序を強制します:最初に登録されていなければ、コンテナのビルドがわかりやすいメッセージとともに失敗します。

設定ファイルは任意です。以下のデフォルトでは、バンドルは src/ ディレクトリをカーネルのモードでコンパイルし、本番ではビルド済みキャッシュを有効にします:

config/packages/go_aop.yaml
go_aop:
include_paths: ['%kernel.project_dir%/src']
when@prod:
go_aop:
features: [PREBUILT_CACHE]

bin/console config:dump-reference go_aop で、完全なリファレンスを表示できます。すべてのオプションとそのデフォルト値:

config/packages/go_aop.yaml
go_aop:
# Development mode: changed sources and behavior classes are compiled again on the next request,
# breakpoints work in the original files. Keep it off in production.
debug: '%kernel.debug%'
# Application root: only files below it can be compiled, cache paths mirror source paths relative to it.
app_dir: '%kernel.project_dir%'
# Directory for generated sources, proxies and behavior caches. Anchor it on %kernel.cache_dir%
# or %kernel.build_dir% so that cache:clear and cache:warmup manage it.
cache_dir: '%kernel.cache_dir%/aop'
# Permissions of the cache files: an octal literal (0o770), an octal string ("0770") or an integer.
# Defaults to 0770 minus the umask.
cache_file_mode: ~
# Directories that are compiled. Keep the list narrow: compiling vendor code is slow and rarely needed.
include_paths: ['%kernel.project_dir%/src']
# Directories below the include paths that are never compiled (the cache directory and the
# framework itself are always excluded).
exclude_paths: []
# Number of parsed source files the compiler keeps in memory (about 0.2 MB each).
parsed_files_limit: 100
# Framework features, by the name of the Go\Aop\Features constant:
# PREBUILT_CACHE trust the deployed cache completely, never check or write it at runtime
# INTERCEPT_INCLUDES route include/require in compiled files through the compiler (legacy code)
# PARTIAL_REFLECTION compile classes whose parent class, interface or trait Composer can not
# locate, with their own members
features: []
# Kernel class; extend Go\Symfony\GoAopBundle\Kernel\AspectSymfonyKernel to customize
# the transformation pipeline.
kernel_class: Go\Symfony\GoAopBundle\Kernel\AspectSymfonyKernel
# Compile every file below the include paths during cache:warmup and cache:clear.
cache_warmer: true
# Doctrine ORM integration, enabled automatically when DoctrineBundle is registered.
doctrine: ~

環境変数は、Symfony の他の場所と同じように使えます。たとえば debug: '%env(bool:GOAOP_DEBUG)%' です。関数と initialization() の matching rule(マッチングルール)には、フィーチャーフラグは不要です:必要な仕組みは、ルール自身が有効にします。

behavior class は、普通のオートワイヤリングされるサービスです。オートコンフィギュレーションは、Go\Aop\Aspect を実装するすべてのサービスを登録します。オートコンフィギュレーションを使わない場合は、サービスに goaop.aspect タグを付けます:

services:
Acme\Audit\AuditAspect:
tags: [goaop.aspect]

behavior class はシングルトンです:2 つのサービスとして登録すると、コンテナのコンパイルエラーになります。

コンパイラーが必要とするのは、behavior class だけです。Symfony のコンテナは、behavior class の behavior のいずれかが初めて実行されたときにそのクラスを生成し、compile step やキャッシュのウォームアップの間に生成することはありません。カーネルのコンテナ(AspectContainer)も Symfony のコンテナに委譲するため、$aspectContainer->get(LoggerInterface::class) が動作します。Go\Core\AspectKernel と Go\Core\AspectContainer はオートワイヤリング可能なサービスで、goaop.aspect_kernel は public です。

behavior class が何にマッチするかは、それを頼りにする前に確認してください:

ターミナルウィンドウ
bin/console debug:aspect # behavior classes with their rules and behaviors
bin/console debug:advisor --advisor='App\Aspect\TimingAspect->measure' # the methods one behavior matches

デバッグモードでは、include パス配下のクラスは最初の読み込み時にコンパイルされ、そのソースか behavior class が変わると再びコンパイルされます。

symfony/web-profiler-bundle をインストールしていると、ツールバーに behavior class の数が表示されます。Go! AOP パネルには、次のものが一覧表示されます:

  • behavior class と、その advisor(アドバイザー)、behavior の属性、matching rule
  • リクエスト中に読み込まれたコンパイル済みクラスと、そのプロキシファイル
  • include パス配下のクラスのうち、カーネルの初期化 前 に読み込まれたもの(パネルが黄色になります)
  • カーネルの実効設定

3 番目のリストは、GoAopBundle より先に起動するバンドルと、コンテナを再ビルドした 1 回のリクエストを診断するためのものです。そのリクエストは、バンドルが起動する前にサービスのクラスを読み込まなければならないため、それらを一度だけ behavior なしで実行します。次のリクエストからは、完全にコンパイルされた状態で動きます。デプロイには影響しません。cache:clear と cache:warmup が、コンテナとフレームワークのキャッシュを一緒にビルドするためです。

バンドルは、設定で指定されていない限り、Symfony の .container.dumper.inline_class_loader も無効にします。このオプションはサービスのファイルを直接 include するため、クラスローダーを、ひいては compile step を迂回してしまいます。

ターミナルウィンドウ
composer install --no-dev --optimize-autoloader # runs cache:clear through the auto-scripts
# or explicitly
bin/console cache:clear
bin/console cache:warmup

cache:clear と cache:warmup は、キャッシュウォーマーを通じてアプリケーション全体をコンパイルします。cache:clear は、稼働中のキャッシュの隣に新しいキャッシュをビルドし、その後でリネームします。ウォーマーはその新しいディレクトリに、フレームワークのキャッシュをゼロからビルドするので、普段のデプロイ手順を変える必要はありません。コンパイルできないファイルがあるとウォームアップは失敗するため、デプロイは不完全なキャッシュを出荷せずに止まります。ファイルとエラーを確認するには、cache:warmup:aop --fail-fast -vvv を実行してください。

フレームワークのコマンドは、アプリケーションのコンソールに登録されます。これらは稼働中のカーネルに対して動くので、vendor/bin/aspect のローダー引数は省きます。

コマンド 用途
cache:warmup:aop [--fail-fast] [--cache-dir=DIR] [--cached-files=N] [--preload[=FILE]] include パス配下のすべてのファイルをキャッシュにコンパイルします。コンパイルできないファイルがあると失敗します。--preload を付けると、キャッシュ用の opcache.preload スクリプトも書き出します。
cache:warmup:opcache [--file-cache=DIR] [--entry=FILE] フレームワークのキャッシュとアプリケーションで、OPcache のファイルキャッシュ(opcache.file_cache)を充填します。最終イメージの中で実行してください。
debug:aspect [--aspect=FQCN] behavior class を、その matching rule と advisor とともに一覧表示します。
debug:advisor [--advisor=ID] advisor を一覧表示します。--advisor を付けると、その advisor が何にマッチするかを表示します。
debug:weaving [-v] アプリケーションを 2 回コンパイルし、内容の異なるプロキシを報告します。差分は、非決定的な behavior class があることを示します。

ここでは、cache:warmup:aop --workers=N は 1 プロセスでコンパイルします:ワーカープロセスはローダーファイルを使ってカーネルを起動しますが、アプリケーションのコンソールにはローダーファイルがないためです。

config/packages/go_aop.yaml
when@prod:
go_aop:
features: [PREBUILT_CACHE]

PREBUILT_CACHE を指定すると、ランタイムはキャッシュに関するファイルシステムのチェックをすべて省略し、コンパイルもキャッシュディレクトリへの書き込みも一切行いません。キャッシュが把握していない include パス配下のクラスは、WeavingException(「… is missing from the prebuilt AOP cache …」)で失敗します。デプロイのたびにキャッシュを再ビルドしてください。これが推奨の本番設定で、読み取り専用のファイルシステムやイミュータブルなイメージでも動作するようになります。

kernel.build_dir が kernel.cache_dir と異なる場合は、デプロイ時にビルドするディレクトリにフレームワークのキャッシュを置きます:cache_dir: '%kernel.build_dir%/aop'。

OPcache のプリロードでは、コンテナのプリロードファイルより前に、フレームワークのキャッシュのプリロードスクリプトを require します:

config/preload.php
if (is_file($aop = dirname(__DIR__).'/var/cache/prod/aop/_preload.php')) {
require $aop;
}
if (is_file($container = dirname(__DIR__).'/var/cache/prod/App_KernelProdContainer.preload.php')) {
require $container;
}

本番モードでは、キャッシュウォーマーが _preload.php をフレームワークのキャッシュディレクトリに書き出します。cache_dir が %kernel.cache_dir%/aop でない場合は、そのパスを合わせてください。config/preload.php でカーネルを起動しないでください:「Cannot redeclare class」で失敗します。本番ビルドの詳細は本番環境とパフォーマンスにあります。

DoctrineBundle が登録されている場合、または doctrine: true を設定した場合、バンドルは次のことを行います:

  • すべての ORM 属性ドライバーのディレクトリスキャンを、Go\Bridge\Doctrine\WovenEntityClassLocator に置き換えます。これはクラスローダーを通じてエンティティを読み込むので、エンティティは behavior を保ちます。
  • Go\Bridge\Doctrine\MetadataLoadInterceptor を loadClassMetadata リスナーとして登録します。これは、ネイティブの lazy オブジェクトが無効なときにインターセプトされたエンティティのプロパティがあれば、メタデータの読み込み時に報告します。

エンティティをコンパイルするには、include パス配下に置く必要があります。そうすれば、コードで生成した場合も ORM がハイドレートした場合も、behavior が適用されます。両クラスの詳細は Doctrine ORM のページで説明しています。

  • behavior が適用されない。 まず debug:advisor --advisor=... を実行してください:matching rule が何を選んでいるかが一覧表示されます。次に、そのクラスが include パス配下にあり、バンドルの起動前に読み込まれていないこと(プロファイラーのパネルの classes loaded before weaving)を確認します。vendor のコードは、そのディレクトリが include パスになっている場合にだけコンパイルされます。

  • 「Class … is missing from the prebuilt AOP cache」。 キャッシュのビルド対象になっていないコードがデプロイされています。コードを配置した後に、bin/console cache:clear(または cache:warmup)を実行してください。

  • 「Circular reference detected for the aspect …」。 behavior class の依存のいずれかを生成すると、同じクラスの behavior が実行されます。依存を遅延注入するか、matching rule を絞り込んでください:

    public function __construct(
    #[Autowire(lazy: true)] private readonly Wallet $wallet, // or #[AutowireServiceClosure(Wallet::class)], a service locator
    ) {}
  • 「Class … was not found by locator」。 include パス配下のクラスが、生成された基底クラスなど、Composer が見つけられないコードを継承しています。Composer に見つけさせるか、PARTIAL_REFLECTION を有効にするか、依存するクラスを exclude_paths で除外してください。

  • 例外ハンドラー。 他のすべてが失敗したときに読み込まれなければならないクラス(エラーハンドラー、カーネル)は、exclude_paths で除外してください。

© 2026 Alexander Lisachenko