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

Yii3

goaop/goaop-yii3-bridge 1.0 による Yii3 との連携:yiisoft/config による組み込み、タグ付けした behavior class、./yii aop:warmup。

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

ブリッジ goaop/goaop-yii3-bridge 1.0 は、yiisoft/config に組み込まれます。behavior class(振る舞いクラス)は Yii コンテナの普通のサービスで、エンジンは、それぞれの behavior(振る舞い)のいずれかが初めて実行されるときになって初めて、そのクラスを解決します。

  • PHP 8.4 以降
  • Yii3 のパッケージ:yiisoft/config、yiisoft/di、yiisoft/aliases(アプリケーションテンプレートと同じ構成)
  • goaop/framework ^4.0(behavior は属性で宣言)
ターミナルウィンドウ
composer require goaop/goaop-yii3-bridge

ブリッジの設定は、yiisoft/config プラグインが取り込みます。プラグインを無効にした状態でインストールした場合は、composer yii-config-rebuild を実行してください。

エントリースクリプトからカーネルを起動する

Section titled “エントリースクリプトからカーネルを起動する”
public/index.php
use App\Environment;
use Go\Yii3\GoAopBridge\AopBootstrap;
use Yiisoft\Yii\Runner\Http\HttpApplicationRunner;
// ...
$runner = new HttpApplicationRunner(
rootPath: dirname(__DIR__),
debug: Environment::appDebug(),
checkEvents: Environment::appDebug(),
environment: Environment::appEnv(),
);
AopBootstrap::init($runner->getConfig(), rootPath: dirname(__DIR__));
$runner->run();

AopBootstrap::init() の行は、すべてのエントリースクリプトで、ランナーの生成と実行の間に追加してください:public/index.php、yii(ConsoleApplicationRunner と rootPath: __DIR__ を使う)、そして機能テストのブートストラップです。この行は、ブリッジのパラメーターとエイリアスをランナーの設定から読み取ります。ランナーがその設定を保持するので、パラメーターが二度構築されることはありません。

compile step(コンパイルステップ)が適用されるのは、カーネルの起動後に読み込まれたクラスだけで、Yii のランナーはコンテナを構築する間にクラスをオートロードします。この行を省いても、ブリッジの bootstrap 設定グループがカーネルを起動しますが、それでは遅すぎます:コンテナの構築中に読み込まれたクラスはコンパイルされません。デバッグモードでは、配列で定義されたすべてのクラスがこれに該当するため、開発環境と本番環境でアプリケーションの動作が変わってしまいます。

<?php
declare(strict_types=1);
namespace App\Aspect;
use Go\Aop\Aspect;
use Go\Aop\Intercept\MethodInvocation;
use Go\Lang\Attribute\Around;
use Go\Lang\Attribute\Before;
use Psr\Log\LoggerInterface;
final readonly class LoggingAspect implements Aspect
{
public function __construct(private LoggerInterface $logger) {}
#[Before('execution(public App\Service\**->*(*))')]
public function logCall(MethodInvocation $invocation): void
{
$this->logger->debug('Calling {method}', ['method' => $invocation->getMethod()->getName()]);
}
#[Around('execution(public App\Service\PaymentService->charge(*))')]
public function measureCharge(MethodInvocation $invocation): mixed
{
$start = hrtime(true);
try {
return $invocation->proceed();
} finally {
$this->logger->info('charge() took {ms}ms', ['ms' => (hrtime(true) - $start) / 1e6]);
}
}
}

behavior class は、aspects パラメーターに列挙します:

config/common/params.php
'goaop/goaop-yii3-bridge' => [
'aspects' => [
App\Aspect\LoggingAspect::class,
App\Aspect\AuditAspect::class,
],
],

オートワイヤリングできないコンストラクター引数は、他のサービスと同じく、コンテナの定義から渡します:

use App\Aspect\AuditAspect;
use Yiisoft\Definitions\Reference;
return [
AuditAspect::class => [
'__construct()' => [
'logger' => Reference::to('auditLogger'),
'level' => $params['app']['auditLevel'],
],
],
];

behavior class が解決される流れ:

  1. カーネルの起動時には何もオートロードされません:クラス名は構文上の検証を受けるだけです。
  2. コンパイラーは、あるクラスの behavior が必要になると、リフレクションでクラスからそれを読み取ります。behavior class のオブジェクトはネイティブの lazy プロキシで、この時点ではまだ生成されていません。
  3. behavior のいずれかが初めて呼ばれたときに、プロキシは Yii コンテナの共有インスタンスである $container->get(AspectClass::class) で初期化されます。

データベース接続や HTTP クライアントに依存する behavior class でも、behavior を持つメソッドに到達しないリクエストでは、それらを生成しません。デバッグモードでは、列挙されたすべてのクラスが存在し、Go\Aop\Aspect を実装していることを、ブリッジが確認します。

パッケージは、自身の config/params.php から behavior class を提供できます。params グループは再帰的にマージされ、リストは追記され、重複は 1 回だけ登録されます:

config/params.php
return [
'goaop/goaop-yii3-bridge' => [
'aspects' => [
Vendor\Package\Aspect\CacheAspect::class,
],
],
];

behavior class へのタグ付け(オプトイン)

Section titled “behavior class へのタグ付け(オプトイン)”

'aspectTag' => 'goaop.aspect' を設定します。そのうえで、共通の di 設定グループの定義にタグを付けるか('tags' => ['goaop.aspect'])、共通の di-tags タグマップに列挙します(['goaop.aspect' => [LoggingAspect::class]])。タグ付けしたサービスは、クラス名で登録されている必要があります。

この検索は、コストがかかるためデフォルトでは無効です。ブリッジはカーネルの起動前に設定ファイルからタグの宣言を読み取るので、それらのファイルが参照するクラス(たとえばクラス定数や enum のケースを通じて)は、その時点で読み込まれ、もうコンパイルできなくなります。読み取られるのは共通のグループだけです。di-web/di-console の定義のタグ、di-tags-web/di-tags-console のマップ、サービスプロバイダーは参照されません。

デフォルト値は、ブリッジの params グループにあります。config/common/params.php で上書きするか、環境ごとに config/environments/<env>/params.php で上書きしてください。

パラメーター デフォルト 用途
debug null ソースや behavior class が変わったら再コンパイルします。null の場合は GOAOP_DEBUG、次に APP_DEBUG に従います。本番ではオフにしてください。
appDir '@root' アプリケーションのルート。この配下のファイルだけがコンパイルされます。
cacheDir null コンパイルされたソース、プロキシ、advisor(アドバイザー)のキャッシュの置き場所。null の場合は GOAOP_CACHE_DIR(エイリアスも可)、次に '@runtime/aop' に従います。
cacheFileMode null キャッシュファイルのパーミッション:整数(0770)または 8 進数の数字('770')。null は 0770 から umask を引いた値を意味します。
features 0 Go\Aop\Features フラグのビットマスク:PREBUILT_CACHE、PARTIAL_REFLECTION、INTERCEPT_INCLUDES。
includePaths ['@src'] コンパイルするのはこれらのディレクトリだけです。狭く保ってください。
excludePaths [] 決してコンパイルしないディレクトリ。キャッシュディレクトリとフレームワーク自体は、常に除外されます。
parsedFilesLimit null コンパイル中にメモリに保持するパース済みファイルの数。aop:warmup --cached-files のデフォルトでもあります。null はカーネルのデフォルト(100)を意味します。
aspects [] behavior class。Yii コンテナから遅延解決されます。
aspectTag null behavior class を登録するための、オプトインのコンテナタグ。例:'goaop.aspect'。

不正なパラメーターがあると、そのパラメーター名を示すメッセージとともに即座に失敗します。カーネルはコンテナ内で Go\Core\AspectKernel(および Go\Yii3\GoAopBridge\Kernel\AspectYii3Kernel)として、カーネルのコンテナは Go\Core\AspectContainer として利用できます。bootstrap コールバックが実行された後は、カーネルのコンテナは未知の ID を Yii コンテナに委譲します。

yiisoft/yii-console がインストールされていれば、ブリッジは ./yii に次のコマンドを追加します:

コマンド 用途
./yii aop:warmup include パス配下のすべてのクラスをキャッシュにコンパイルします。--fail-fast、--workers=N、--cache-dir=DIR、--preload[=FILE]、--cached-files=N。
./yii aop:opcache aop:warmup の後に、フレームワークのキャッシュ、アプリケーション、その設定で OPcache のファイルキャッシュを充填します。
./yii aop:debug:aspect behavior class を、その matching rule(マッチングルール)と advisor とともに一覧表示します(1 つだけなら --aspect=...)。
./yii aop:debug:advisor advisor を一覧表示するか、1 つの advisor が何にマッチするかを表示します(--advisor=...)。
./yii aop:debug:weaving 2 回コンパイルし、内容の異なるプロキシを報告します。これにより、behavior class とコンパイルされたクラスの間の循環依存が明らかになります。

これらはフレームワーク自身のコマンドで、aop 名前空間に登録されます。エントリーの行で初期化されたカーネルの上で動くので、省略可能な loader 引数は省いてください。--workers=N のワーカーは ./yii を改めて実行するので、エントリーの行が必要です。bootstrap のフォールバックがカーネルを起動した場合、コマンドは自身のプロセス内でコンパイルし、その旨を表示します。

ターミナルウィンドウ
./yii aop:warmup --workers=4

本番では debug をオフにし、デプロイ時にキャッシュをビルドします。--cache-dir=DIR は、カーネルが自身のディレクトリを使い続けている間に、別のディレクトリでキャッシュをビルドします。キャッシュファイルは配置場所に依存しないので、そのディレクトリを所定の場所へ移動できます。

Dockerfile
ENV GOAOP_CACHE_DIR=/app/aop
RUN ./yii aop:warmup --workers=4 --preload

読み取り専用のファイルシステムでは、features に Features::PREBUILT_CACHE を加えます。するとエンジンはキャッシュを完全に信頼し、キャッシュに書き込むことはなくなるので、デプロイのたびに再ビルドしてください。キャッシュが把握していない include パス配下のクラスは、Go\Aop\Exception\WeavingException で失敗します。aop:warmup のプロセス自体は例外なので、そうしたクラスもキャッシュにコンパイルできます。

OPcache を使う場合、./yii aop:warmup --preload は opcache.preload 用の _preload.php をキャッシュディレクトリに書き出し、./yii aop:opcache は最終イメージの中でファイルキャッシュを充填します:

ターミナルウィンドウ
mkdir -p /var/cache/opcache && php -d opcache.enable_cli=1 -d opcache.file_cache_only=1 \
-d opcache.file_cache=/var/cache/opcache \
./yii aop:opcache --file-cache=/var/cache/opcache
  • コンパイルされるのは、appDir と includePaths 配下のクラスだけです。vendor のコードはコンパイルされません。
  • App\Environment のように AopBootstrap::init() より前に読み込まれたクラスは、コンパイルできません。エントリーの行が設定を読み取る間に、その設定が読み込むクラスも同様です。
  • behavior class 自体はコンパイルする必要がありません:そのディレクトリを除外してください。例:'excludePaths' => ['@src/Aspect']。
  • behavior class の生成が、そのクラス自身の behavior のいずれかを実行してしまう場合、その behavior は Go\Aop\Exception\AspectCircularReferenceException で失敗します。その依存を遅延注入する(クロージャーまたは Psr\Container\ContainerInterface)か、matching rule を絞り込んでください。
  • カーネルはプロセス全体で共有されます。長時間稼働するワーカー(RoadRunner、Swoole、FrankenPHP)では、ワーカーごとに一度だけ初期化されます。リクエストごとの状態を持つ behavior class は、他の共有サービスと同じようにリセットしてください。

© 2026 Alexander Lisachenko