制限事項と 4.0 へのアップグレード
バージョン 4.0 がインターセプトできないものとその回避方法、そして 3.x からの完全な移行ガイド。
このページは英語版からの翻訳です。基準となるのは英語版のページです。 原文を読む
このページは 2 部構成です。前半では、バージョン 4.0 がインターセプトしないもの、その理由、代わりにどうすればよいかを挙げます。後半は 3.x から 4.0 への完全な移行ガイドで、適用すべき順に並べています。
制限はありのままに記載しています。ほとんどは PHP 自体に由来するもので、どれも予測可能な形で失敗します:コンパイル時にコンパイラーが WeavingException を投げるか、そのメンバーがスキップされるかのどちらかです。
インターセプトできないメソッドと関数
Section titled “インターセプトできないメソッドと関数”参照を返すメソッド
Section titled “参照を返すメソッド”function &name() と宣言されたメソッドや関数は、インターセプトできません。call context(呼び出しコンテキスト)と behavior(振る舞い)は値を返すため、呼び出し側は参照ではなくコピーを受け取ることになってしまうからです。このようなメソッドをコンパイルすると、WeavingException で失敗します。
範囲の広い matching rule(マッチングルール)からこうしたメソッドを除外するには、!matchReturningByReference() を使います:
#[Around('execution(public App\Service\*->*(*)) && !matchReturningByReference()')]3.x では、call context は notice を出したうえでコピーを返していました。4.0 ではエラーになるため、こうしたメソッドはコンパイル時に見つかります。
#[\Override] 付きのトレイトメソッド
Section titled “#[\Override] 付きのトレイトメソッド”クラスがトレイトから取り込み、かつ #[\Override] が付いたメソッドは、そのクラスではインターセプトできません。PHP はこの属性を、プロキシが呼び出す private なエイリアスにもコピーしますが、そのエイリアスは何もオーバーライドしていないからです。このようなメソッドをコンパイルすると、WeavingException で失敗します。
選択肢は 4 つあります:
&& !matchInherited()で、トレイトのメソッドをルールから除外する。- そのメソッドだけを除外する。たとえば
&& !execution(public Foo->hello(*))。 - トレイトから
#[\Override]を取り除く。 - トレイト自体を対象にする。たとえば
execution(public HelloTrait->hello(*))。この場合はトレイトがコンパイルされ、#[\Override]があっても動作します。behavior は、そのトレイトを使うすべてのクラスに適用されます。
クラスが親クラスから継承したトレイトメソッドは、影響を受けません。
ジェネレーター
Section titled “ジェネレーター”yield を含むメソッドでは、behavior はメソッドが呼ばれた時点で動き、proceed() は Generator オブジェクトを返します。behavior から yield された値は見えません:それらの値は後になって、呼び出し側が反復するときに生成されるからです。
参照渡しの可変長引数
Section titled “参照渡しの可変長引数”getArguments() は、引数を位置順に並べます。参照渡しの可変長引数(&...$values)は、元のメソッドには値渡しで渡されます。
スタックトレースでの #[\SensitiveParameter]
Section titled “スタックトレースでの #[\SensitiveParameter]”プロキシはこの属性を保持します。引数を配列として持つフレームワークのフレームでは、引数は隠されます:call context の __invoke()、生成された __initialization()、そして書き換えられた new です。
call context と元のメソッドの間にある 2 つの内部関数は、引数を隠せません:
ReflectionMethod::invokeArgs()(インスタンスメソッドとコンストラクター)forward_static_call_array()(static メソッド)
Throwable::getTrace() に含まれるこれらのフレームは引数の配列を保持したままで、トレースの文字列表現では Array と表示されます。フレームの引数を収集するエラートラッカーからは、これが見えます。本番のデフォルトである zend.exception_ignore_args=On では、どのフレームも引数を持ちません。
関数プロキシの strict_types
Section titled “関数プロキシの strict_types”インターセプトされる関数のプロキシは、名前空間ごとに 1 ファイルで、declare(strict_types=1) 付きで生成されます。引数は、プロキシに入る前に、呼び出し元ファイルのモードに従って型変換されます。
プロパティのインターセプト
Section titled “プロパティのインターセプト”access(...) ルールは、生成されたプロキシ上の PHP 8.4 ネイティブのプロパティフックを通じて、インスタンスプロパティの読み書きをインターセプトします:生成されたフックが、読み書きを ClassFieldAccess の call context に通します。これで何ができるかは、プロパティのインターセプトを参照してください。次のプロパティは意図的にスキップされます:
| プロパティ | 理由 |
|---|---|
static プロパティ |
PHP には static プロパティ用のプロパティフックがありません。エンジンの制約です。 |
public private(set) readonly を含む readonly プロパティ |
PHP は readonly プロパティへのフックを許可していません。 |
すでに get または set フックを持つプロパティ |
フレームワークは、自前のフックをユーザーが定義したフックと組み合わせられません。 |
親クラスから継承した final プロパティ |
サポートしていません。 |
継承した private プロパティ |
サポートしていません。 |
対象にできるのは、コンパイルされるクラス自身で宣言されたプロパティ(コンストラクターのプロモーションによるものを含む)と、親クラスから継承した public および protected プロパティです。
スキップされたプロパティは、エラーになりません。ルールがそのプロパティにマッチしても、黙ってインターセプトの対象から外されます:AdviceMatcher は、プロキシのコードを生成する前に、static、readonly、フック付きのプロパティをスキップします。さらに安全策として、プロパティのジェネレーターもそのようなプロパティを WeavingException で拒否します。
readonly でないプロパティの非対称可視性は保持されます。public protected(set) string $name は、プロキシクラスでも修飾子を保ちます。
PHP 8.4 に関する注意
Section titled “PHP 8.4 に関する注意”フレームワークは、プロパティのインターセプトを PHP 8.4 のプロパティフックの上に構築し、コンテナの遅延(lazy)サービスには PHP 8.4 の lazy オブジェクトを使っています。このうち 2 つの部分には制限があります。
lazy オブジェクトの初期化はインターセプトできない
Section titled “lazy オブジェクトの初期化はインターセプトできない”PHP 8.4 では、lazy オブジェクトの初期化のために ReflectionClass::newLazyProxy() と ReflectionClass::newLazyGhost() が導入されました。フレームワークの Container は、自身の遅延サービスと、クラス名で登録された behavior class(振る舞いクラス)に、ネイティブの lazy プロキシを使います。こうしたサービスを取得すると、型付きで instanceof も正しく通る newLazyProxy() のインスタンスが返されます。登録されたファクトリが実行されるのは、そのオブジェクトに初めて実際に触れたときだけです。
PHP が遅延化できないクラスは、即時生成にフォールバックします:内部クラスとその stdClass 以外のサブクラス、抽象クラス、enum です。
lazy プロキシが背後のインスタンスを実体化する瞬間に対応する call context はないため、lazy オブジェクトの初期化そのものはインターセプトできません。
PHP 8.4 のまとめ
Section titled “PHP 8.4 のまとめ”| PHP 8.4 の機能 | サポート | 備考 |
|---|---|---|
| 新しいプロパティへのプロパティフック | フレームワークが生成 | access(...) のインターセプトに使用 |
| 既存のフックを持つプロパティ | スキップ | ユーザー定義のフックとは組み合わせられない |
| readonly プロパティ | スキップ | readonly プロパティにはフックが許可されない |
| 非対称可視性(readonly 以外) | 保持 | 可視性の修飾子をプロキシにコピー |
#[\Deprecated] 属性 |
引き継ぎ | プロキシのメソッドとクラスにコピー |
lazy オブジェクト(newLazyProxy) |
インターセプト不可 | 遅延初期化に対応する call context がない |
PHP 8.5 に関する注意
Section titled “PHP 8.5 に関する注意”PHP 8.5 に関する注意は、PHP 8.5.10 と PHP 8.6.0beta2 でフレームワークを監査した結果に基づいています。
PHP 8.5 で動作するもの
Section titled “PHP 8.5 で動作するもの”- パイプ演算子
|>。 コンパイルされたメソッド本体の中で動作します。メソッド本体はそのまま<Class>OriginalTraitという本体用のトレイトに移されるため、その中の PHP 8.5 の式構文はすべて保たれます。 clone with。 コンパイルされたコード内の式は、期待どおりに動作します。#[\NoDiscard]。 この属性は生成されたプロキシメソッドにコピーされ、call context はインターセプトされたメソッドの値を返します。コンパイルされたメソッドでも、エンジンの「戻り値が使われていない」という警告は引き続き出ます。- クラス定数の属性(
#[\Deprecated]を含む)。クラス定数は、属性ごと生成されたトレイトに残ります。 - 引数のデフォルト値としてのクロージャーと first-class callable。 プロキシメソッドのシグネチャでも、コンパイル後にそのまま残ります。
- 静的な非対称可視性。 非対称可視性を持つ
staticプロパティ(public static private(set))は、コンパイルされたクラスでも動作します。access(...)ルールの対象になることはありません。 - リフレクションでの
selfとparentの解決。 PHP 8.5 では、ReflectionNamedType::getName()が戻り値型のselfとparentを具体的なクラス名に解決します。プロキシのジェネレーターは、可能な場合は AST の生の型ノードを読むため、生成されたプロキシでもselfとparentのキーワードは保たれます。
初期化式の中の new はインターセプトされない
Section titled “初期化式の中の new はインターセプトされない”定数式の中の new 式は、エンジンが評価します。対象は、引数やプロモートされたコンストラクター引数のデフォルト値、静的変数の初期化子、属性の引数です。コンパイラーはこれらの式をそのまま残すのでコードは動作しますが、それらが生成するオブジェクトに対して initialization(...) の behavior は動きません。インターセプトされるのは、実行可能なコードの中の new 式だけです。
static プロパティは決してインターセプトできない
Section titled “static プロパティは決してインターセプトできない”static プロパティは、PHP 8.5 の非対称可視性を持つ static プロパティも含めて、access(...) ルールではインターセプトできません。static プロパティには PHP のプロパティフックが存在しないため、フレームワークにはそれらをインターセプトする仕組みがなく、AdviceMatcher はそれらをプロパティのインターセプトから除外します。これは PHP エンジンの制約であり、バグではありません。
PHP 8.5 のまとめ
Section titled “PHP 8.5 のまとめ”| PHP 8.5 の機能 | サポート | 備考 |
|---|---|---|
メソッド本体でのパイプ演算子 |> |
動作する | 本体はそのまま生成されたトレイトに移される |
clone with |
動作する | |
#[\NoDiscard] |
引き継ぎ | プロキシにコピー。call context が値を返す |
クラス定数の属性(#[\Deprecated] を含む) |
保持 | 定数は生成されたトレイトに残る |
| 引数のデフォルト値としてのクロージャーと first-class callable | 動作する | |
| 静的な非対称可視性(インターセプト対象外) | 保持 | static プロパティは access() では決してインターセプトできない |
リフレクションでの self/parent の解決 |
対応済み | プロキシの生成に AST の生の型ノードを使用 |
初期化式の中の new |
インターセプトされない | エンジンが評価する。initialization(...) の behavior は動かない |
access() による static プロパティのインターセプト |
不可 | static プロパティにはプロパティフックがない(PHP エンジンの制約) |
コンパイル範囲と matching rule の制限
Section titled “コンパイル範囲と matching rule の制限”カーネルの起動前に読み込まれたクラス
Section titled “カーネルの起動前に読み込まれたクラス”コンパイルされるのは、カーネルの初期化後に読み込まれたクラスだけです。それより前に読み込まれたクラスは、behavior なしで動きます。カーネルは、フロントコントローラーのできるだけ早い段階で初期化してください。フレームワークのブリッジは最初に起動する必要があります。各ブリッジがこれをどう扱うかは、インテグレーションを参照してください。
引数はマッチできない
Section titled “引数はマッチできない”matching rule の引数リストは、常に (*) です。ルールはクラス、名前、修飾子、戻り値型、属性でメソッドを選びますが、引数の値や引数の型で選ぶことはありません。特定の引数に応じて処理したい場合は、メソッドにマッチさせ、behavior の中で $invocation->getArguments() を調べてください。構文の全体は振る舞いとマッチングルールにあります。
知っておくべき実行時のコスト
Section titled “知っておくべき実行時のコスト”これらの数値は、docs/performance.md にあるフレームワーク自身のベンチマークから取ったものです:約 250 ファイル、コンパイルされるクラス 94 個、behavior class 6 個からなる小さなショップアプリケーションを、JIT を無効にした PHP 8.5.12 で動かしています。計測方法と再現方法は、このファイルで説明されています。
initialization() ルールはすべての new に影響する
Section titled “initialization() ルールはすべての new に影響する”initialization ルールが登録されている間は、生成ファイル内のすべての new がトランスフォーマーを通ります。初期化の behavior を持たない(かつ public なコンストラクターを持つ)クラスは、引き続きネイティブの new で生成されますが、素の new より約 130 ns 余分にかかります。初期化の behavior を持つクラスは、call context の処理をすべて経由します。メソッドのルールで足りる場面では、そちらを選んでください。
デバッグモードは開発用
Section titled “デバッグモードは開発用”'debug' => true では、生成されたクラスがストリームフィルター経由で提供されるため、Xdebug のブレークポイントとマジック定数は元のファイルを指し、変更されたファイルは自動で再コンパイルされます。ベンチマークでは、デバッグモードのホットなリクエストは、本番モードの 2 倍以上の時間がかかります。本番では 'debug' => false を使ってください。本番環境とパフォーマンスを参照してください。
3.x から 4.0 へのアップグレード
Section titled “3.x から 4.0 へのアップグレード”バージョン 4.0 は、継承ベースのコンパイラーをトレイトベースのものに置き換え、behavior を first-class callable として生成し、PHP 8.4 向けにキャッシュを作り直しています。ほとんどのアプリケーションでは、下のチェックリストだけで足ります。その後の各セクションでは、すべての破壊的変更を説明します。そこに出てくる API 名は従来の用語のままです。このドキュメントで使っている言葉との対応は、用語表にあります。変更の全リストは CHANGELOG にあります。
クイックチェックリスト
Section titled “クイックチェックリスト”-
PHP 8.4 以降で動かし、依存パッケージを更新します(下の「要件と依存パッケージ」を参照)。
-
behavior class のすべての behavior メソッドを
publicにします(下の「behavior class」を参照)。 -
behavior class は、
registerAspect()の代わりにadd()またはaddLazyService()で登録します。 -
matching rule の
?ワイルドカードを*に置き換え、dynamic(...)ルールを書き直します。 -
キャッシュディレクトリを削除してから、もう一度ウォームアップします。引数は、カーネルを初期化するファイルです:
ターミナルウィンドウ vendor/bin/aspect cache:warmup:aop public/index.php -
Doctrine ブリッジを使っている場合は、エンティティの検出を
WovenEntityClassLocatorに切り替えます。
要件と依存パッケージ
Section titled “要件と依存パッケージ”ext-tokenizerを備えた PHP 8.4 以降。- 依存パッケージは Composer で更新します。必要なバージョンは
composer.jsonに記載されています。 psr/containerが新しい依存パッケージとして加わり、nikic/php-parserはgoaop/parser-reflection経由でインストールされます。laminas/laminas-codeは使われなくなりました。プロキシは、内部のGo\Proxy\Generatorパッケージで生成されます。フレームワークのジェネレーターを拡張していたコードや、フレームワークと一緒に入る laminas のジェネレータークラスに依存していたコードは、更新が必要です。bin/aspectにはsymfony/consoleが必要です。
キャッシュの形式はすべて変わり、3.x のキャッシュファイルは一切再利用されません。
- プロキシの配置。
_proxiesサブディレクトリはなくなりました。プロキシは、キャッシュディレクトリ配下の、ソースファイルと同じ相対パスに保存され、生成されたソース(<Class>OriginalTraitトレイトとしての元のクラス本体)はその隣に置かれます。 - クラスマップ。
_include.cacheは、コンパイルされたすべてのクラスをキャッシュ済みファイルに対応付け、起動時に Composer に渡されます。また、INTERCEPT_INCLUDESでインターセプトされる include のために、既知のすべてのソースファイルをキャッシュ済みファイル(変換されない場合はnull)に対応付けます。これがないキャッシュディレクトリは、古いものとして扱われます。 - behavior class のキャッシュ。 シリアライズされた
{cacheDir}/_aspect/sha1(FQCN)の blob は、生成されたソースの隣に置かれる素の PHP ファイルに置き換わりました:{appDir}/src/Aspect/LoggingAspect.phpは{cacheDir}/src/Aspect/LoggingAspect.cache.phpとしてキャッシュされます。インターセプターはシリアライズできなくなりました:AbstractInterceptor::__serialize()、__unserialize()、serializeAdvice()、unserializeAdvice()は削除されています。
メタデータファイルには、形式のバージョンが記録されています。Features::PREBUILT_CACHE では、別のバージョンのフレームワークでビルドされたキャッシュは、実行時に再ビルドされるのではなく、例外で拒否されます。
Features::PREBUILT_CACHE は、キャッシュを完全に信頼するようになりました。ディレクトリと書き込み可否の確認、filemtime の比較、追跡対象リソースのチェック、behavior class のキャッシュの鮮度チェックは、すべて省略されます。デプロイ時のキャッシュの再ビルドは、デプロイする側の責任です。
cacheFileMode オプションは検証されるようになりました。0600 から 0777 までの整数で、所有者に読み書きの権限を与えるものでなければなりません。ディレクトリには、モードの読み取りビットに対応した検索権限が付きます。
behavior class
Section titled “behavior class”behavior メソッドは public でなければならない
Section titled “behavior メソッドは public でなければならない”生成されたプロキシは、behavior class のインスタンスにある behavior を、first-class callable として呼び出します。そのため、#[Before]、#[After]、#[Around]、#[AfterThrowing] が付いたメソッドは public でなければなりません。protected や private の behavior メソッドに対して、ローダーは AspectException を投げます。#[Pointcut] だけが付いたメソッドは、どの可視性でも構いません。
#[Before('execution(public Example->*(*))')]protected function beforeMethod(MethodInvocation $invocation): void {}
// 4.0#[Before('execution(public Example->*(*))')]public function beforeMethod(MethodInvocation $invocation): void {}メソッドごとに behavior の属性は 1 つ
Section titled “メソッドごとに behavior の属性は 1 つ”behavior class のメソッドに付けられるのは、#[Before]、#[After]、#[Around]、#[AfterThrowing] のうち最大 1 つです。2 つ目を付けると、AspectException が投げられます。そのようなメソッドは、behavior ごとに 1 つのメソッドに分割してください。#[Pointcut] は引き続き、同じメソッド上で behavior の属性と組み合わせられます。フレームワークに属さない属性は無視されます。
behavior class の登録
Section titled “behavior class の登録”AspectContainer::registerAspect() は削除されました。behavior class は、普通のコンテナサービスです。
3.x での書き方:
// 3.xprotected function configureAop(AspectContainer $container){ $container->registerAspect(new MonitorAspect());}4.0 での書き方:
// 4.0protected function configureAop(AspectContainer $container): void{ // Deferred (recommended): constructed when one of its behaviors runs for the first time $container->addLazyService(MonitorAspect::class, static fn() => new MonitorAspect());
// Eager alternative // $container->add(MonitorAspect::class, new MonitorAspect());}addLazyService() はファクトリを保存し、初めて取得されたときにサービスを生成します。起動時に lazy プロキシのインスタンスが存在することを前提にしていたコードは、getService() を呼ぶ必要があります。誤った型のオブジェクトを返すファクトリは、登録時ではなく、初めて使われたときに失敗するようになりました。
AspectContainer::addResource() は、インターフェースの一部です。onRegistration() を使うと、あるインターフェースを実装するサービスの遅延登録に反応できます。
PSR-11 コンテナ
Section titled “PSR-11 コンテナ”AspectContainer は Psr\Container\ContainerInterface を継承しているため、PSR-11 コンテナを期待するあらゆるコードにコンテナを渡せます。
AspectContainer::getValue()はget()に名前が変わりました。has()は PSR のインターフェースに由来し、シグネチャは同じです。- 独自の
containerClassは、getValue()の代わりにget()を実装し、さらにアプリケーションのコンテナを接続するsetDelegate()も実装します。設定と CLI を参照してください。
// before$pointcut = $container->getValue('my.pointcut');
$pointcut = $container->get('my.pointcut');未知の ID を指定すると、ServiceNotFoundException が投げられます。これは Psr\Container\NotFoundExceptionInterface を実装しています。getService() は、エントリーが要求したクラスのインスタンスでない場合に Go\Aop\Exception\ContainerException を投げます。この例外は、Psr\Container\ContainerExceptionInterface を実装した InvalidConfigurationException です。
この名前の変更は、コンテナだけに適用されます。プロパティの call context にある FieldAccess::getValue() は変わっていません。
Advice とインターセプターの API
Section titled “Advice とインターセプターの API”- マーカーインターフェースの
AdviceBefore、AdviceAfter、AdviceAroundは削除されました。AdviceにはgetType(): AdviceTypeEnumが必要で、そのケースはBefore、After、AfterThrowing、Around、Introductionです。 - invocation のコンストラクター(
DynamicTraitAliasMethodInvocation、StaticTraitAliasMethodInvocation、ReflectionFunctionInvocation)には、null 非許容のClosure $closureToCallが必要です。 DeclareErrorは削除されました:属性、DeclareErrorInterceptor、PointcutBuilder::declareError()です。代わりに、#[Before]や#[Around]の behavior から警告を出すか、例外を投げてください。
matching rule
Section titled “matching rule”参照を返すメソッドは拒否される
Section titled “参照を返すメソッドは拒否される”function &name() と宣言されたメソッドや関数のコンパイルは、WeavingException で失敗します。call context が、参照ではなくコピーを返してしまうためです。3.x では、notice を出したうえでコピーを返していました。そのようなメソッドにマッチするルールには、&& !matchReturningByReference() を加えてください。
? ワイルドカードの廃止
Section titled “? ワイルドカードの廃止”名前と型のパターンで、? は 1 文字のワイルドカードではなくなりました。null 許容型と衝突していたためです。戻り値型のパターンでは、先頭の ? は null 許容を表します:?Foo は Foo|null と同じです。? ワイルドカードは * に置き換えてください。
dynamic(...) の廃止
Section titled “dynamic(...) の廃止”dynamic(...) ルールは削除されました。あわせて、MagicMethodDynamicPointcut、DynamicInvocationMatcherInterceptor、Pointcut::KIND_DYNAMIC、そして Pointcut::matches() の $instanceOrScope と $arguments パラメーターも削除されています。マジックメソッドそのものをインターセプトし、呼び出された名前を引数から読み取ってください。
3.x での書き方:
#[Around('dynamic(public Foo->save*(*))')]4.0 での書き方:
#[Around('execution(public Foo->__call(*))')]public function aroundMagicCall(MethodInvocation $invocation): mixed{ [$methodName, $arguments] = $invocation->getArguments(); // ... return $invocation->proceed();}変更された matching rule
Section titled “変更された matching rule”- 修飾子の優先順位。 スペース区切りの修飾子はすべて揃っている必要があり、
|のほうが強く結合します。final public|protectedは、final かつ(public または protected)という意味です。3.x では、final でないすべての public メソッドにもマッチしていました。 Foo+はFooを含む。 クラスまたはインターフェースのFoo自身と、トレイトFooを使うクラスにもマッチするようになりました。型そのものを除外するには、&& !within(Foo)を加えてください。- 属性のルールはサブクラスにもマッチする。
@execution(Attr)をはじめとする属性のルールは、Attrを継承した属性にもマッチします。 *は 0 文字にもマッチする。 名前と戻り値型のパターンで、*は名前の 1 つの部分に含まれる任意の文字列(0 文字を含む)を表します。3.x では少なくとも 1 文字が必要でした:Sensor*はクラスSensor自身をスキップし、set*はset()という名前のメソッドをスキップしていました。こうしたルールは、今後はそれらにもマッチします。必要なら、&& !execution(public Foo->set(*))や&& !within(Foo)で除外してください。|による選択肢は、名前の部分の中にとどまる。Ns\A|BはNs\AとNs\Bを選びます。3.x では、Ns\AまたはグローバルクラスのBという意味でした。異なる名前空間のクラスを並べていたパターン(Foo\A|Bar\B)は、2 つのルールとして書く必要があります:execution(public Foo\A->*(*)) || execution(public Bar\B->*(*))。ModifierPointcutは final でイミュータブル。 マスクはコンストラクターの引数になり、andMatch()、orMatch()、notMatch()は新しいインスタンスを返します。
コンパイラーと生成コード
Section titled “コンパイラーと生成コード”元のクラス本体は、トレイト <Class>OriginalTrait に変換されます。プロキシクラスは元の名前、親クラス、インターフェースを保ち、そのトレイトを private な <method>OriginalAlias エイリアス付きで use します。3.x では、プロキシは名前を変えた親クラス <Class>__AopProxied を継承していました。この継承の層に依存していたコードは、次の影響を受けます:
- プロキシには、名前を変えた親クラスはもうありません。
get_parent_class()、クラス内のparent::、instanceofのチェックは、元の親クラスを見ます。 AspectContainer::AOP_PROXIED_SUFFIXは削除されました。ORIGINAL_TRAIT_SUFFIX('OriginalTrait')またはORIGINAL_TRAIT_FILE_SUFFIX('OriginalTrait.php')を使ってください。AbstractMethodInvocation::TRAIT_ALIAS_PREFIXは、TRAIT_ALIAS_SUFFIX('OriginalAlias')に置き換わりました。InitializationAwareとStaticInitializationAwareのフックは、__initialization()と__staticInitialization()という名前です。- 生成コード内の
self::はプロキシクラスに解決されるため、SelfValueTransformerとSelfValueVisitorは削除されました。 Go\Aop\Featuresは、インターフェースではなく final クラスになりました。定数は変わりませんが、実装することはできなくなりました。Features::ALLはすべてのフラグを組み合わせたもので、AspectKernel::hasFeature()は未知のフラグに対して例外を投げます。Features::PARAMETER_WIDENINGは削除されました。カーネルのオプションで渡していた場合は、このフラグを削除してください。
使われていない API の削除
Section titled “使われていない API の削除”次の public なクラス、メソッド、定数は、フレームワーク内で使われていなかったため削除されました:
#[Aspect]属性(Go\Lang\Attribute\Aspect)。フレームワークはこれを一度も読んでいませんでした:behavior class は、Go\Aop\Aspectを実装していることで識別されます。behavior class からこの属性を削除してください。Pointcut::KIND_TRAIT。Pointcut::KIND_ALLは127ではなく119になりました。Go\Proxy\Part\InterceptedConstructorGeneratorとGo\Proxy\Part\FunctionParameterList。InterceptedMethodGenerator::getBody()とsetBody()、CachePathManager::setCacheDir()、そしてAopComposerLoader::wasInitialized()。同じフラグはAopComposerLoader::init()が返します。- コンテナのエントリー
'kernel.options'。AspectKernel::getOptions()を使ってください。
名前が変わった enum と定数
Section titled “名前が変わった enum と定数”| 3.x / 4.0 の開発途中の版 | 4.0 |
|---|---|
TransformerResultEnum::RESULT_TRANSFORMED |
TransformerResult::Transformed |
TransformerResultEnum::RESULT_ABSTAIN |
TransformerResult::Abstain |
TransformerResultEnum::RESULT_ABORTED |
TransformerResult::Aborted |
FieldAccessType::READ / WRITE |
FieldAccessType::Read / Write |
AspectContainer::AOP_PROXIED_SUFFIX |
AspectContainer::ORIGINAL_TRAIT_SUFFIX |
AspectContainer::getValue() |
AspectContainer::get()(PSR-11) |
Go\Proxy\Generator の enum(Visibility、PropertyModifier、ClassModifier)も、ケースに PascalCase を使います。独自のソーストランスフォーマーは TransformerResult のケースを返し、getAccessType() を比較する behavior は新しいケース名を使います:
if ($access->getAccessType() === FieldAccessType::WRITE) {if ($access->getAccessType() === FieldAccessType::Write) {カーネルとトランスフォーマー
Section titled “カーネルとトランスフォーマー”- トランスフォーマーのインスタンスを返していた
AspectKernel::registerTransformers()は、遅延コンテナサービスを登録するregisterTransformerServices(AspectContainer $container)に置き換わりました。組み込みのトランスフォーマーを置き換え、省き、並べ替え、拡張するには、これをオーバーライドします。1 つ追加するだけなら、configureAop()から$container->addLazyService(MyTransformer::class, ...)を呼んでください。 CachingTransformerは削除されました:キャッシュの判断はSourceTransformingLoaderが行います。SourceTransformingLoader::addTransformer()は削除され、transformCode()は全体としてのTransformerResultを返します。StreamMetaData::$sourceは読み取り専用です:読み取るたびに$tokenStreamから再構築されます。独自のトランスフォーマーは$tokenStream内のトークンを編集するか、setTokenStreamFromRawTokens()で置き換えます。ConstructorExecutionTransformer、FilterInjectorTransformer、MagicConstantTransformerは、もうSourceTransformerではありません。これらはNodeRewriterのルールで、構文木を 1 回走査するSyntaxTreeRewriterによって適用されます。この走査はフレームワークのサービスで、registerTransformerServices()をオーバーライドした場合でも、WeavingTransformerの前でチェーンの先頭に立ちます。- 独自の
SourceTransformerは、従来どおり登録します。個々のノードを書き換えるには、自分で構文木を走査するトランスフォーマーではなく、NodeRewriterサービスを登録してください。変換パイプラインの拡張については、設定と CLI を参照してください。
final クラスと internal クラス
Section titled “final クラスと internal クラス”拡張されることを想定していなかったクラスは、final になりました:
Go\Core\Container、Go\Core\AttributeAspectLoaderExtensionGo\Aop\Framework\StaticInitializationJoinpointGo\Instrument\ClassLoading\AopComposerLoader、SourceTransformingLoader、Go\Instrument\PathResolver- トランスフォーマーの
WeavingTransformer、FilterInjectorTransformer、MagicConstantTransformer、およびStreamMetaData - プロキシジェネレーターの
EnumProxyGenerator、TraitProxyGenerator、FunctionProxyGenerator - 属性の
#[Before]、#[After]、#[Around]、#[AfterThrowing]、#[Pointcut]、#[DeclareParents]
Go\Lang\Attribute\AbstractInterceptor は abstract です。フレームワークの内部機構の一部でしかないクラスは @internal とマークされ、後方互換性の保証の対象外です:AdviceMatcher、AspectLoader、CachedAspectLoader、CachePathManager、CacheWarmer、Enumerator、InterceptorInjector、The、NativeLazyProxy。
これらのクラスのサブクラスは、コンポジションに置き換えるか、configureAop() または registerTransformerServices() で登録する独自のコンテナやトランスフォーマーに置き換えてください。
フレームワークが投げる例外はすべて Go\Aop\Exception\ExceptionInterface を実装しているため、1 つの catch でフレームワークのあらゆる失敗を扱えます。いくつかの箇所では、投げる例外の型が変わりました:
| 状況 | 3.x | 4.0 |
|---|---|---|
| 不正なカーネルオプション、コンテナへの登録、コンソール入力 | RuntimeException、InvalidArgumentException、UnexpectedValueException |
InvalidConfigurationException(InvalidArgumentException の一種) |
| 不正な matching rule | UnexpectedValueException、InvalidArgumentException |
PointcutSyntaxException(AspectException の一種) |
| 未知のコンテナ ID | OutOfBoundsException |
ServiceNotFoundException(OutOfBoundsException であり、PSR-11 の NotFoundExceptionInterface でもある) |
getService() で型の合わないコンテナエントリー |
InvalidArgumentException |
ContainerException(InvalidConfigurationException であり、PSR-11 の ContainerExceptionInterface でもある) |
| コンパイル、プロキシの生成、キャッシュの書き込み | RuntimeException、LogicException、InvalidArgumentException |
WeavingException(RuntimeException の一種) |
| キャッシュできない behavior | Go\Core\Cache\NotCompilableException |
Go\Aop\Exception\NotCompilableException |
| 不正な behavior class、call context の実行時エラー | Go\Aop\AspectException |
Go\Aop\Exception\AspectException、Go\Aop\Exception\InvocationException |
上に挙げた SPL の型を catch していた箇所では、ExceptionInterface か新しい型を catch してください。
Doctrine ブリッジ
Section titled “Doctrine ブリッジ”ブリッジは、もうエンティティのメタデータを書き換えません。3.x の mapped superclass による回避策は継承ベースのエンジンにしか当てはまらず、Doctrine はコンパイルされたエンティティをそのまま正しくマッピングします。代わりに、次の 2 点を設定してください(Doctrine ORM 3.6+):
use Doctrine\ORM\Events;use Doctrine\ORM\Mapping\Driver\AttributeDriver;use Go\Bridge\Doctrine\MetadataLoadInterceptor;use Go\Bridge\Doctrine\WovenEntityClassLocator;
// Discover entities through the autoloader, which serves the generated classes$configuration->setMetadataDriverImpl( new AttributeDriver(WovenEntityClassLocator::createFromDirectories([__DIR__ . '/src/Entity'])),);// Intercepted properties become hooked properties, which Doctrine supports with native lazy objects$configuration->enableNativeLazyObjects(true);
// Optional: reports misconfiguration early; a plain listener, no longer an EventSubscriber$eventManager->addEventListener(Events::loadClassMetadata, new MetadataLoadInterceptor());コマンドは #[AsCommand] で名前を宣言し、bin/aspect によって遅延読み込みされます。どのコマンドも Command::SUCCESS か Command::FAILURE を返します。
- 3.x では、
debug:weavingはエラーの件数をそのまま返していました。スクリプトがその数値に依存していた場合は、代わりに終了コードを確認してください。 cache:warmup:aopは、コンパイルできないファイルがあると失敗します。そのため、ウォームアップのエラーを無視していたデプロイスクリプトは、今後はそこで止まります。最初のエラーで止めるには、--fail-fastを付けます:
vendor/bin/aspect cache:warmup:aop public/index.php --fail-fast© 2026 Alexander Lisachenko
