跳转到内容
文档

限制与升级到 4.0

4.0 版本无法拦截哪些内容、如何绕开这些限制,以及从 3.x 迁移的完整指南。

本页译自英文,以英文页面为准。 阅读原文

本页分为两部分。第一部分列出 4.0 版本不拦截的内容、原因,以及替代做法。第二部分是从 3.x 迁移到 4.0 的完整指南,按你应当执行的顺序排列。

这些限制如实列出。大多数来自 PHP 本身,而且每一项的失败方式都是可预期的:要么编译器在编译时抛出 WeavingException,要么该成员被跳过。

声明为 function &name() 的方法或函数无法被拦截。Call context(调用上下文)和 behavior(行为)返回的是值,调用方拿到的会是副本而不是引用。编译这样的方法会以 WeavingException 失败。

用 !matchReturningByReference() 把这类方法从宽泛的 matching rule(匹配规则)中排除:

#[Around('execution(public App\Service\*->*(*)) && !matchReturningByReference()')]

在 3.x 中,call context 会返回一个副本并给出 notice。在 4.0 中这是一个错误,所以你在编译时就能发现这些方法。

如果一个类从 trait 导入的方法带有 #[\Override],这个方法在该类中无法被拦截。PHP 会把这个注解复制到代理所调用的私有别名上,而这个别名并没有覆盖任何方法。编译这样的方法会以 WeavingException 失败。

你有四种选择:

  • 用 && !matchInherited() 把 trait 方法从规则中排除。
  • 只排除这一个方法,例如 && !execution(public Foo->hello(*))。
  • 从 trait 中移除 #[\Override]。
  • 直接以 trait 本身为目标,例如 execution(public HelloTrait->hello(*))。这样被编译的是 trait,可以与 #[\Override] 共存,而且 behavior 会作用于每个使用该 trait 的类。

类从父类继承来的 trait 方法不受影响。

对于包含 yield 的方法,behavior 在方法被调用时运行,proceed() 返回 Generator 对象。Behavior 看不到 yield 出来的值:这些值要等到调用方迭代时才产生。

getArguments() 按位置列出参数。按引用传递的可变参数(&...$values)会以值的方式传给原始方法。

代理会保留这个注解。框架中以数组形式携带参数的栈帧会隐藏这些参数:call context 的 __invoke()、生成的 __initialization(),以及被改写的 new。

位于 call context 与原始方法之间的两个内部函数无法隐藏它们:

  • ReflectionMethod::invokeArgs(),用于实例方法和构造函数
  • forward_static_call_array(),用于静态方法

它们在 Throwable::getTrace() 中的栈帧仍然持有参数数组,栈跟踪的文本形式会把它打印为 Array。收集栈帧参数的错误追踪工具能看到它。在 zend.exception_ignore_args=On(生产环境的默认值)下,任何栈帧都不带参数。

被拦截函数的代理以 declare(strict_types=1) 生成,每个命名空间一个文件。参数在进入代理之前,就已按调用方文件的模式完成类型转换。

access(...) 规则通过生成的代理上原生的 PHP 8.4 属性钩子,拦截实例属性的读写:生成的钩子把读写操作交给 ClassFieldAccess call context 处理。这能带来什么,见 属性拦截。以下属性会被有意跳过:

属性 原因
static 属性 PHP 没有为静态属性提供属性钩子。这是引擎层面的限制。
readonly 属性,包括 public private(set) readonly PHP 不允许在 readonly 属性上使用钩子。
已经有 get 或 set 钩子的属性 框架无法把自己的钩子与你定义的钩子组合在一起。
从父类继承的 final 属性 不支持。
继承的 private 属性 不支持。

支持的目标包括被编译的类自身声明的属性(含构造函数提升的属性),以及从父类继承的 public 和 protected 属性。

被跳过的属性不会引发错误。如果你的规则匹配到了它,这个属性会被静默地排除在拦截之外:AdviceMatcher 在生成任何代理代码之前就跳过静态、readonly 和带钩子的属性。作为安全兜底,属性生成器也会以 WeavingException 拒绝这类属性。

非 readonly 属性上的非对称可见性会被保留。public protected(set) string $name 在代理类中保持原有的修饰符。

框架的属性拦截建立在 PHP 8.4 属性钩子之上,它的容器则用 PHP 8.4 惰性对象实现延迟服务。这两部分各有限制。

PHP 8.4 引入了 ReflectionClass::newLazyProxy() 和 ReflectionClass::newLazyGhost(),用于惰性对象初始化。框架的 Container 对它自己的延迟服务,以及按类名注册的 behavior class(行为类),使用原生惰性代理。获取这样的服务时,得到的是一个带类型、instanceof 判断正确的 newLazyProxy() 实例。注册的工厂只在第一次真正与该对象交互时才运行。

PHP 无法惰性化的类会退回到立即构造:内部类及其非 stdClass 子类、抽象类和枚举。

惰性代理实例化其背后对象的那一刻没有对应的 call context,因此惰性对象的初始化本身无法被拦截。

PHP 8.4 特性 支持情况 说明
新属性上的属性钩子 由框架生成 用于 access(...) 拦截
已有钩子的属性 跳过 框架无法与用户定义的钩子组合
readonly 属性 跳过 readonly 属性上不允许使用钩子
非对称可见性(非 readonly) 保留 可见性修饰符会复制到代理上
#[\Deprecated] 注解 传递 复制到代理方法和类上
惰性对象(newLazyProxy) 无法拦截 惰性初始化没有 call context

PHP 8.5 部分的说明基于在 PHP 8.5.10 和 PHP 8.6.0beta2 上对框架所做的审查。

  • 管道运算符 |>。 它可以在被编译的方法体中使用。方法体会原封不动地移入 <Class>OriginalTrait 类体 trait,因此其中任何 PHP 8.5 表达式语法都会保留。
  • clone with。 被编译代码中的这类表达式按预期工作。
  • #[\NoDiscard]。 这个注解会复制到生成的代理方法上,call context 返回被拦截方法的返回值。对被编译的方法,引擎的「返回值未使用」警告照常触发。
  • 类常量上的注解,包括 #[\Deprecated]。类常量连同它们的注解一起留在生成的 trait 中。
  • 以闭包和一等可调用对象(first-class callable)作为参数默认值。 它们在编译后的代理方法签名中得以保留。
  • 静态非对称可见性。 带有非对称可见性的 static 属性(public static private(set))在被编译的类上可以正常使用。access(...) 规则永远不会以它们为目标。
  • self 和 parent 的反射解析。 在 PHP 8.5 上,ReflectionNamedType::getName() 会把 self 和 parent 返回类型解析为具体的类名。代理生成器在可能时读取原始的 AST 类型节点,因此生成的代理中保留了 self 和 parent 关键字。

常量表达式中的 new 表达式由引擎求值。这包括参数或构造函数提升参数的默认值、静态变量初始化器,以及注解的参数。编译器保持这些表达式不变,所以代码可以正常运行,但 initialization(...) behavior 不会为它们创建的对象运行。只有可执行代码中的 new 表达式会被拦截。

静态属性,包括 PHP 8.5 中带有非对称可见性的 static 属性,都无法用 access(...) 规则拦截。PHP 没有为静态属性提供属性钩子,所以框架没有拦截它们的机制,AdviceMatcher 会把它们排除在属性拦截之外。这是 PHP 引擎的限制,不是 bug。

PHP 8.5 特性 支持情况 说明
方法体中的管道运算符 |> 可用 方法体原封不动地移入生成的 trait
clone with 可用
#[\NoDiscard] 传递 复制到代理上;call context 返回该值
类常量上的注解(包括 #[\Deprecated]) 保留 常量留在生成的 trait 中
以闭包和一等可调用对象作为参数默认值 可用
静态非对称可见性(不拦截) 保留 静态属性永远无法用 access() 拦截
self/parent 的反射解析 已处理 生成代理时使用原始 AST 类型节点
初始化器中的 new 不拦截 由引擎求值;initialization(...) behavior 不会为它运行
用 access() 拦截静态属性 永远不支持 静态属性没有属性钩子(PHP 引擎限制)

只有在内核初始化之后加载的类才会被编译。在此之前加载的类运行时不带它的 behavior。请在前端控制器中尽可能早地初始化内核。框架的桥接包必须最先启动;各个桥接包如何处理这一点,见 集成。

Matching rule 中的参数列表总是 (*)。规则按类、名称、修饰符、返回类型和注解选择方法,从不按参数值或参数类型选择。要针对特定参数做处理,就匹配该方法,然后在 behavior 中检查 $invocation->getArguments()。完整语法见 行为与匹配规则。

这些数据来自框架自己在 docs/performance.md 中的基准测试:一个小型商店应用,约 250 个文件、94 个被编译的类和 6 个 behavior class,运行在关闭 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 断点和魔术常量指向你的原始文件,修改过的文件也会自动重新编译。在基准测试中,调试模式下 hot 请求的耗时是生产模式的两倍多。生产环境请使用 'debug' => false;见 生产环境与性能。

4.0 版本用基于 trait 的编译器取代了基于继承的编译器,把 behavior 生成为一等可调用对象,并为 PHP 8.4 重新设计了缓存。大多数应用只需要下面的检查清单。清单之后的各节逐一说明每项破坏性变更。其中的 API 名称沿用经典术语;术语表 列出了它们与本文用词的对应关系。完整的变更列表见 CHANGELOG。

  1. 在 PHP 8.4 或更高版本上运行,并更新依赖(见下文「要求与依赖」)。

  2. 把 behavior class 中的每个 behavior 方法都改为 public(见下文「Behavior class」)。

  3. 用 add() 或 addLazyService() 注册 behavior class,取代 registerAspect()。

  4. 把 matching rule 中的 ? 通配符替换为 *,并改写 dynamic(...) 规则。

  5. 删除缓存目录,然后重新预热。参数是初始化内核的文件:

    终端窗口
    vendor/bin/aspect cache:warmup:aop public/index.php
  6. 如果你使用 Doctrine 桥接,把实体发现切换为 WovenEntityClassLocator。

  • PHP 8.4+,并带有 ext-tokenizer。
  • 用 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 trait 形式存在的原始类体)就放在它旁边。
  • 类映射。 _include.cache 把每个被编译的类映射到它的缓存文件,并在启动时交给 Composer。它还把每个已知的源文件映射到它的缓存文件(未转换时为 null),供 INTERCEPT_INCLUDES 拦截的 include 使用。没有这个文件的缓存目录会被视为过期。
  • Behavior class 缓存。 序列化的 {cacheDir}/_aspect/sha1(FQCN) 二进制块被替换为放在生成源码旁边的普通 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 作为 behavior class 实例上的一等可调用对象来调用。因此,带有 #[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 注解

Section titled “每个方法只能有一个 behavior 注解”

Behavior class 的方法最多只能带有 #[Before]、#[After]、#[Around] 和 #[AfterThrowing] 中的一个。出现第二个会抛出 AspectException。把这样的方法拆分为每个 behavior 一个方法。#[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() 存储一个工厂,并在第一次获取服务时构建它。如果代码期望某个惰性代理实例在启动时就已存在,就必须调用 getService()。返回错误类型对象的工厂,现在会在第一次使用时失败,而不是在注册时失败。

AspectContainer::addResource() 已成为接口的一部分。onRegistration() 让你可以对实现某个接口的服务的延迟注册作出响应。

AspectContainer 继承自 Psr\Container\ContainerInterface,因此你可以把这个容器传给任何需要 PSR-11 容器的代码。

  • AspectContainer::getValue() 更名为 get()。
  • has() 来自 PSR 接口,签名不变。
  • 自定义的 containerClass 要实现 get() 而不是 getValue(),另外还要实现 setDelegate(),用来挂接你的应用容器。见 配置与命令行。
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,其 case 为 Before、After、AfterThrowing、Around 和 Introduction。
  • 调用对象的构造函数(DynamicTraitAliasMethodInvocation、StaticTraitAliasMethodInvocation、ReflectionFunctionInvocation)要求传入不可为空的 Closure $closureToCall。
  • DeclareError 已被移除:包括该注解、DeclareErrorInterceptor 和 PointcutBuilder::declareError()。改为在 #[Before] 或 #[Around] behavior 中发出警告或抛出异常。

编译声明为 function &name() 的方法或函数会以 WeavingException 失败,因为 call context 返回的会是副本而不是引用。3.x 会返回一个副本并给出 notice。对匹配到这类方法的规则,加上 && !matchReturningByReference()。

名称和类型模式中的 ? 不再是单字符通配符,因为它与可空类型冲突。在返回类型模式中,开头的 ? 是可空标记:?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 本身,以及使用 trait Foo 的类。加上 && !within(Foo) 可以排除该类型本身。
  • 注解规则会匹配子类。 @execution(Attr) 以及其他注解规则,也会匹配继承自 Attr 的注解。
  • * 也能匹配空。 在名称和返回类型模式中,* 代表一个名称片段中的任意字符,包括零个字符。在 3.x 中它至少需要一个字符: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)必须写成两条规则:execution(public Foo\A->*(*)) || execution(public Bar\B->*(*))。
  • ModifierPointcut 是 final 且不可变的。 掩码作为构造函数参数传入,andMatch()、orMatch() 和 notMatch() 返回一个新实例。

原始类体会被转换为一个 trait,即 <Class>OriginalTrait。代理类保留原始的类名、父类和接口,并通过私有的 <method>OriginalAlias 别名使用这个 trait。在 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 已被移除。如果你在内核选项中传入了这个标志,请删除它。

以下公共类、方法和常量在框架内部没有任何用途,已被移除:

  • #[Aspect] 注解(Go\Lang\Attribute\Aspect)。框架从未读取过它:behavior class 是通过实现 Go\Aop\Aspect 来识别的。请从你的 behavior class 中移除这个注解。
  • Pointcut::KIND_TRAIT。Pointcut::KIND_ALL 的值是 119,而不是 127。
  • 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 的枚举(Visibility、PropertyModifier、ClassModifier)同样使用 PascalCase 的 case 名。自定义源码转换器返回 TransformerResult 的 case,比较 getAccessType() 的 behavior 则使用新的 case 名:

if ($access->getAccessType() === FieldAccessType::WRITE) {
if ($access->getAccessType() === FieldAccessType::Write) {
  • 返回转换器实例的 AspectKernel::registerTransformers(),被 registerTransformerServices(AspectContainer $container) 取代,后者注册的是延迟容器服务。覆盖它可以替换、省略、重新排序或扩展内置的转换器。如果只想追加一个,在 configureAop() 中调用 $container->addLazyService(MyTransformer::class, ...)。
  • CachingTransformer 已被移除:是否使用缓存由 SourceTransformingLoader 决定。SourceTransformingLoader::addTransformer() 已被移除,transformCode() 返回整体的 TransformerResult。
  • StreamMetaData::$source 是只读的:每次读取时都会根据 $tokenStream 重新构建。自定义转换器编辑 $tokenStream 中的 token,或者用 setTokenStreamFromRawTokens() 替换它们。
  • ConstructorExecutionTransformer、FilterInjectorTransformer 和 MagicConstantTransformer 不再是 SourceTransformer。它们是 NodeRewriter 规则,由一次 SyntaxTreeRewriter 语法树遍历统一应用。这次遍历是框架的一个服务:即使覆盖了 registerTransformerServices(),它也会在 WeavingTransformer 之前开启转换链。
  • 自定义的 SourceTransformer 照旧注册。要改写单个节点,请注册一个 NodeRewriter 服务,而不是一个自己遍历语法树的转换器。扩展转换管道的方法见 配置与命令行。

从未打算被继承的类现在都是 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,所以一个 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 类型,请改为捕获 ExceptionInterface 或新的类型。

桥接不再改写实体元数据。3.x 中基于 mapped superclass 的变通做法只适用于基于继承的引擎,而 Doctrine 能原样正确映射被编译的实体。改为配置以下两项(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