限制与升级到 4.0
4.0 版本无法拦截哪些内容、如何绕开这些限制,以及从 3.x 迁移的完整指南。
本页译自英文,以英文页面为准。 阅读原文
本页分为两部分。第一部分列出 4.0 版本不拦截的内容、原因,以及替代做法。第二部分是从 3.x 迁移到 4.0 的完整指南,按你应当执行的顺序排列。
这些限制如实列出。大多数来自 PHP 本身,而且每一项的失败方式都是可预期的:要么编译器在编译时抛出 WeavingException,要么该成员被跳过。
无法拦截的方法和函数
Section titled “无法拦截的方法和函数”按引用返回的方法
Section titled “按引用返回的方法”声明为 function &name() 的方法或函数无法被拦截。Call context(调用上下文)和 behavior(行为)返回的是值,调用方拿到的会是副本而不是引用。编译这样的方法会以 WeavingException 失败。
用 !matchReturningByReference() 把这类方法从宽泛的 matching rule(匹配规则)中排除:
#[Around('execution(public App\Service\*->*(*)) && !matchReturningByReference()')]在 3.x 中,call context 会返回一个副本并给出 notice。在 4.0 中这是一个错误,所以你在编译时就能发现这些方法。
带有 #[\Override] 的 trait 方法
Section titled “带有 #[\Override] 的 trait 方法”如果一个类从 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 出来的值:这些值要等到调用方迭代时才产生。
按引用传递的可变参数
Section titled “按引用传递的可变参数”getArguments() 按位置列出参数。按引用传递的可变参数(&...$values)会以值的方式传给原始方法。
栈跟踪中的 #[\SensitiveParameter]
Section titled “栈跟踪中的 #[\SensitiveParameter]”代理会保留这个注解。框架中以数组形式携带参数的栈帧会隐藏这些参数:call context 的 __invoke()、生成的 __initialization(),以及被改写的 new。
位于 call context 与原始方法之间的两个内部函数无法隐藏它们:
ReflectionMethod::invokeArgs(),用于实例方法和构造函数forward_static_call_array(),用于静态方法
它们在 Throwable::getTrace() 中的栈帧仍然持有参数数组,栈跟踪的文本形式会把它打印为 Array。收集栈帧参数的错误追踪工具能看到它。在 zend.exception_ignore_args=On(生产环境的默认值)下,任何栈帧都不带参数。
函数代理的 strict_types
Section titled “函数代理的 strict_types”被拦截函数的代理以 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 说明
Section titled “PHP 8.4 说明”框架的属性拦截建立在 PHP 8.4 属性钩子之上,它的容器则用 PHP 8.4 惰性对象实现延迟服务。这两部分各有限制。
惰性对象的初始化无法被拦截
Section titled “惰性对象的初始化无法被拦截”PHP 8.4 引入了 ReflectionClass::newLazyProxy() 和 ReflectionClass::newLazyGhost(),用于惰性对象初始化。框架的 Container 对它自己的延迟服务,以及按类名注册的 behavior class(行为类),使用原生惰性代理。获取这样的服务时,得到的是一个带类型、instanceof 判断正确的 newLazyProxy() 实例。注册的工厂只在第一次真正与该对象交互时才运行。
PHP 无法惰性化的类会退回到立即构造:内部类及其非 stdClass 子类、抽象类和枚举。
惰性代理实例化其背后对象的那一刻没有对应的 call context,因此惰性对象的初始化本身无法被拦截。
PHP 8.4 小结
Section titled “PHP 8.4 小结”| PHP 8.4 特性 | 支持情况 | 说明 |
|---|---|---|
| 新属性上的属性钩子 | 由框架生成 | 用于 access(...) 拦截 |
| 已有钩子的属性 | 跳过 | 框架无法与用户定义的钩子组合 |
| readonly 属性 | 跳过 | readonly 属性上不允许使用钩子 |
| 非对称可见性(非 readonly) | 保留 | 可见性修饰符会复制到代理上 |
#[\Deprecated] 注解 |
传递 | 复制到代理方法和类上 |
惰性对象(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类体 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 不会被拦截
Section titled “初始化器中的 new 不会被拦截”常量表达式中的 new 表达式由引擎求值。这包括参数或构造函数提升参数的默认值、静态变量初始化器,以及注解的参数。编译器保持这些表达式不变,所以代码可以正常运行,但 initialization(...) behavior 不会为它们创建的对象运行。只有可执行代码中的 new 表达式会被拦截。
静态属性永远无法被拦截
Section titled “静态属性永远无法被拦截”静态属性,包括 PHP 8.5 中带有非对称可见性的 static 属性,都无法用 access(...) 规则拦截。PHP 没有为静态属性提供属性钩子,所以框架没有拦截它们的机制,AdviceMatcher 会把它们排除在属性拦截之外。这是 PHP 引擎的限制,不是 bug。
PHP 8.5 小结
Section titled “PHP 8.5 小结”| PHP 8.5 特性 | 支持情况 | 说明 |
|---|---|---|
方法体中的管道运算符 |> |
可用 | 方法体原封不动地移入生成的 trait |
clone with |
可用 | |
#[\NoDiscard] |
传递 | 复制到代理上;call context 返回该值 |
类常量上的注解(包括 #[\Deprecated]) |
保留 | 常量留在生成的 trait 中 |
| 以闭包和一等可调用对象作为参数默认值 | 可用 | |
| 静态非对称可见性(不拦截) | 保留 | 静态属性永远无法用 access() 拦截 |
self/parent 的反射解析 |
已处理 | 生成代理时使用原始 AST 类型节点 |
初始化器中的 new |
不拦截 | 由引擎求值;initialization(...) behavior 不会为它运行 |
用 access() 拦截静态属性 |
永远不支持 | 静态属性没有属性钩子(PHP 引擎限制) |
编译范围与 matching rule 的限制
Section titled “编译范围与 matching rule 的限制”内核启动前加载的类
Section titled “内核启动前加载的类”只有在内核初始化之后加载的类才会被编译。在此之前加载的类运行时不带它的 behavior。请在前端控制器中尽可能早地初始化内核。框架的桥接包必须最先启动;各个桥接包如何处理这一点,见 集成。
无法匹配参数
Section titled “无法匹配参数”Matching rule 中的参数列表总是 (*)。规则按类、名称、修饰符、返回类型和注解选择方法,从不按参数值或参数类型选择。要针对特定参数做处理,就匹配该方法,然后在 behavior 中检查 $invocation->getArguments()。完整语法见 行为与匹配规则。
需要了解的运行时开销
Section titled “需要了解的运行时开销”这些数据来自框架自己在 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。方法规则能满足需求时,优先使用方法规则。
调试模式用于开发
Section titled “调试模式用于开发”在 'debug' => true 下,生成的类通过流过滤器提供,因此 Xdebug 断点和魔术常量指向你的原始文件,修改过的文件也会自动重新编译。在基准测试中,调试模式下 hot 请求的耗时是生产模式的两倍多。生产环境请使用 'debug' => false;见 生产环境与性能。
从 3.x 升级到 4.0
Section titled “从 3.x 升级到 4.0”4.0 版本用基于 trait 的编译器取代了基于继承的编译器,把 behavior 生成为一等可调用对象,并为 PHP 8.4 重新设计了缓存。大多数应用只需要下面的检查清单。清单之后的各节逐一说明每项破坏性变更。其中的 API 名称沿用经典术语;术语表 列出了它们与本文用词的对应关系。完整的变更列表见 CHANGELOG。
快速检查清单
Section titled “快速检查清单”-
在 PHP 8.4 或更高版本上运行,并更新依赖(见下文「要求与依赖」)。
-
把 behavior class 中的每个 behavior 方法都改为
public(见下文「Behavior class」)。 -
用
add()或addLazyService()注册 behavior class,取代registerAspect()。 -
把 matching rule 中的
?通配符替换为*,并改写dynamic(...)规则。 -
删除缓存目录,然后重新预热。参数是初始化内核的文件:
终端窗口 vendor/bin/aspect cache:warmup:aop public/index.php -
如果你使用 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>OriginalTraittrait 形式存在的原始类体)就放在它旁边。 - 类映射。
_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 class
Section titled “Behavior class”Behavior 方法必须是 public
Section titled “Behavior 方法必须是 public”生成的代理把 behavior 作为 behavior class 实例上的一等可调用对象来调用。因此,带有 #[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 注解
Section titled “每个方法只能有一个 behavior 注解”Behavior class 的方法最多只能带有 #[Before]、#[After]、#[Around] 和 #[AfterThrowing] 中的一个。出现第二个会抛出 AspectException。把这样的方法拆分为每个 behavior 一个方法。#[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() 存储一个工厂,并在第一次获取服务时构建它。如果代码期望某个惰性代理实例在启动时就已存在,就必须调用 getService()。返回错误类型对象的工厂,现在会在第一次使用时失败,而不是在注册时失败。
AspectContainer::addResource() 已成为接口的一部分。onRegistration() 让你可以对实现某个接口的服务的延迟注册作出响应。
PSR-11 容器
Section titled “PSR-11 容器”AspectContainer 继承自 Psr\Container\ContainerInterface,因此你可以把这个容器传给任何需要 PSR-11 容器的代码。
AspectContainer::getValue()更名为get()。has()来自 PSR 接口,签名不变。- 自定义的
containerClass要实现get()而不是getValue(),另外还要实现setDelegate(),用来挂接你的应用容器。见 配置与命令行。
// 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,其 case 为Before、After、AfterThrowing、Around和Introduction。- 调用对象的构造函数(
DynamicTraitAliasMethodInvocation、StaticTraitAliasMethodInvocation、ReflectionFunctionInvocation)要求传入不可为空的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 “? 通配符已移除”名称和类型模式中的 ? 不再是单字符通配符,因为它与可空类型冲突。在返回类型模式中,开头的 ? 是可空标记:?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本身,以及使用 traitFoo的类。加上&& !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()返回一个新实例。
编译器与生成的代码
Section titled “编译器与生成的代码”原始类体会被转换为一个 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已被移除。如果你在内核选项中传入了这个标志,请删除它。
移除的未使用 API
Section titled “移除的未使用 API”以下公共类、方法和常量在框架内部没有任何用途,已被移除:
#[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()。
改名的枚举与常量
Section titled “改名的枚举与常量”| 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) {内核与转换器
Section titled “内核与转换器”- 返回转换器实例的
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 类与内部类
Section titled “final 类与内部类”从未打算被继承的类现在都是 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,所以一个 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 或新的类型。
Doctrine 桥接
Section titled “Doctrine 桥接”桥接不再改写实体元数据。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
