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

制限事項と 4.0 へのアップグレード

バージョン 4.0 がインターセプトできないものとその回避方法、そして 3.x からの完全な移行ガイド。

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

このページは 2 部構成です。前半では、バージョン 4.0 がインターセプトしないもの、その理由、代わりにどうすればよいかを挙げます。後半は 3.x から 4.0 への完全な移行ガイドで、適用すべき順に並べています。

制限はありのままに記載しています。ほとんどは PHP 自体に由来するもので、どれも予測可能な形で失敗します:コンパイル時にコンパイラーが WeavingException を投げるか、そのメンバーがスキップされるかのどちらかです。

インターセプトできないメソッドと関数

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 は、そのトレイトを使うすべてのクラスに適用されます。

クラスが親クラスから継承したトレイトメソッドは、影響を受けません。

yield を含むメソッドでは、behavior はメソッドが呼ばれた時点で動き、proceed() は Generator オブジェクトを返します。behavior から yield された値は見えません:それらの値は後になって、呼び出し側が反復するときに生成されるからです。

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 では、どのフレームも引数を持ちません。

インターセプトされる関数のプロキシは、名前空間ごとに 1 ファイルで、declare(strict_types=1) 付きで生成されます。引数は、プロキシに入る前に、呼び出し元ファイルのモードに従って型変換されます。

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 のプロパティフックの上に構築し、コンテナの遅延(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 の機能 サポート 備考
新しいプロパティへのプロパティフック フレームワークが生成 access(...) のインターセプトに使用
既存のフックを持つプロパティ スキップ ユーザー定義のフックとは組み合わせられない
readonly プロパティ スキップ readonly プロパティにはフックが許可されない
非対称可視性(readonly 以外) 保持 可視性の修飾子をプロキシにコピー
#[\Deprecated] 属性 引き継ぎ プロキシのメソッドとクラスにコピー
lazy オブジェクト(newLazyProxy) インターセプト不可 遅延初期化に対応する call context がない

PHP 8.5 に関する注意は、PHP 8.5.10 と PHP 8.6.0beta2 でフレームワークを監査した結果に基づいています。

  • パイプ演算子 |>。 コンパイルされたメソッド本体の中で動作します。メソッド本体はそのまま <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 の機能 サポート 備考
メソッド本体でのパイプ演算子 |> 動作する 本体はそのまま生成されたトレイトに移される
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 なしで動きます。カーネルは、フロントコントローラーのできるだけ早い段階で初期化してください。フレームワークのブリッジは最初に起動する必要があります。各ブリッジがこれをどう扱うかは、インテグレーションを参照してください。

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 の処理をすべて経由します。メソッドのルールで足りる場面では、そちらを選んでください。

'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 にあります。

  1. PHP 8.4 以降で動かし、依存パッケージを更新します(下の「要件と依存パッケージ」を参照)。

  2. behavior class のすべての behavior メソッドを public にします(下の「behavior class」を参照)。

  3. behavior class は、registerAspect() の代わりに add() または addLazyService() で登録します。

  4. matching rule の ? ワイルドカードを * に置き換え、dynamic(...) ルールを書き直します。

  5. キャッシュディレクトリを削除してから、もう一度ウォームアップします。引数は、カーネルを初期化するファイルです:

    ターミナルウィンドウ
    vendor/bin/aspect cache:warmup:aop public/index.php
  6. Doctrine ブリッジを使っている場合は、エンティティの検出を WovenEntityClassLocator に切り替えます。

  • 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 メソッドは public でなければならない

Section titled “behavior メソッドは public でなければならない”

生成されたプロキシは、behavior class のインスタンスにある behavior を、first-class callable として呼び出します。そのため、#[Before]、#[After]、#[Around]、#[AfterThrowing] が付いたメソッドは public でなければなりません。protected や private の behavior メソッドに対して、ローダーは AspectException を投げます。#[Pointcut] だけが付いたメソッドは、どの可視性でも構いません。

3.x
#[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 の属性と組み合わせられます。フレームワークに属さない属性は無視されます。

AspectContainer::registerAspect() は削除されました。behavior class は、普通のコンテナサービスです。

3.x での書き方:

app/ApplicationAspectKernel.php
// 3.x
protected function configureAop(AspectContainer $container)
{
$container->registerAspect(new MonitorAspect());
}

4.0 での書き方:

app/ApplicationAspectKernel.php
// 4.0
protected 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() を使うと、あるインターフェースを実装するサービスの遅延登録に反応できます。

AspectContainer は Psr\Container\ContainerInterface を継承しているため、PSR-11 コンテナを期待するあらゆるコードにコンテナを渡せます。

  • AspectContainer::getValue() は get() に名前が変わりました。
  • has() は PSR のインターフェースに由来し、シグネチャは同じです。
  • 独自の containerClass は、getValue() の代わりに get() を実装し、さらにアプリケーションのコンテナを接続する setDelegate() も実装します。設定と CLI を参照してください。
4.0
// 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() は変わっていません。

  • マーカーインターフェースの 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 から警告を出すか、例外を投げてください。

参照を返すメソッドは拒否される

Section titled “参照を返すメソッドは拒否される”

function &name() と宣言されたメソッドや関数のコンパイルは、WeavingException で失敗します。call context が、参照ではなくコピーを返してしまうためです。3.x では、notice を出したうえでコピーを返していました。そのようなメソッドにマッチするルールには、&& !matchReturningByReference() を加えてください。

名前と型のパターンで、? は 1 文字のワイルドカードではなくなりました。null 許容型と衝突していたためです。戻り値型のパターンでは、先頭の ? は null 許容を表します:?Foo は Foo|null と同じです。? ワイルドカードは * に置き換えてください。

dynamic(...) ルールは削除されました。あわせて、MagicMethodDynamicPointcut、DynamicInvocationMatcherInterceptor、Pointcut::KIND_DYNAMIC、そして Pointcut::matches() の $instanceOrScope と $arguments パラメーターも削除されています。マジックメソッドそのものをインターセプトし、呼び出された名前を引数から読み取ってください。

3.x での書き方:

3.x
#[Around('dynamic(public Foo->save*(*))')]

4.0 での書き方:

4.0
#[Around('execution(public Foo->__call(*))')]
public function aroundMagicCall(MethodInvocation $invocation): mixed
{
[$methodName, $arguments] = $invocation->getArguments();
// ...
return $invocation->proceed();
}
  • 修飾子の優先順位。 スペース区切りの修飾子はすべて揃っている必要があり、| のほうが強く結合します。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() は新しいインスタンスを返します。

元のクラス本体は、トレイト <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 は削除されました。カーネルのオプションで渡していた場合は、このフラグを削除してください。

次の 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() を使ってください。
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 になりました:

  • Go\Core\Container、Go\Core\AttributeAspectLoaderExtension
  • Go\Aop\Framework\StaticInitializationJoinpoint
  • Go\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 してください。

ブリッジは、もうエンティティのメタデータを書き換えません。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