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 class 的 behavior(行为)第一次运行时才解析它。
- PHP 8.4 或更高版本
- Yii3 包:yiisoft/config、yiisoft/di、yiisoft/aliases(与应用模板中一致)
goaop/framework^4.0(用注解声明 behavior)
composer require goaop/goaop-yii3-bridgeyiisoft/config 插件会读取桥接包的配置。如果你是在禁用该插件的情况下安装的,请运行 composer yii-config-rebuild。
在入口脚本中启动内核
Section titled “在入口脚本中启动内核”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();在每个入口脚本中,在创建 runner 和运行它之间加上 AopBootstrap::init() 这一行:public/index.php、yii(使用它的 ConsoleApplicationRunner 和 rootPath: __DIR__),以及功能测试的引导文件。它从 runner 的配置中读取桥接包参数和别名。runner 会保留这份配置,因此参数不会被构建两次。
Compile step(编译步骤)只作用于内核启动之后加载的类,而 Yii runner 在构建容器时就会自动加载类。如果省略这一行,桥接包的 bootstrap 配置组仍然会启动内核,但为时已晚:构建容器期间加载的类不会被编译。在调试模式下,这包括每个使用数组定义的类,于是应用在开发环境和生产环境中的表现会不一样。
定义和注册 behavior class
Section titled “定义和注册 behavior class”<?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]); } }}在 aspects 参数中列出 behavior class:
'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 的解析过程:
- 内核启动时不会自动加载任何东西:只对类名做语法校验。
- 当编译器需要某个类的 behavior 时,它通过反射从类中读取。此时 behavior class 对象是一个原生惰性代理,尚未被构造。
- 在它的某个 behavior 第一次被调用时,代理通过
$container->get(AspectClass::class)完成初始化,得到的是 Yii 容器中的共享实例。
依赖数据库连接或 HTTP 客户端的 behavior class,在从未触及带有 behavior 的方法的请求中,不会创建这些连接或客户端。在调试模式下,桥接包会检查每个列出的类是否存在并实现了 Go\Aop\Aspect。
扩展包可以通过自己的 config/params.php 贡献 behavior class。params 组会递归合并,列表会被追加,重复的只注册一次:
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]])。打了标签的服务必须以其类名注册。
由于有额外开销,这种查找默认是关闭的。桥接包会在内核启动之前从配置文件中读取标签声明,因此这些文件引用的每个类(例如通过类常量或枚举 case 引用)都会在那时被加载,之后就无法再被编译。只有公共配置组会被读取。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)或八进制数字('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 paths)下的每个类编译进缓存。可用 --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(用 --aspect=... 只看一个)。 |
./yii aop:debug:advisor |
列出 advisor,或者某个 advisor 匹配到的内容(--advisor=...)。 |
./yii aop:debug:weaving |
编译两次并报告不一致的代理,从而揭示 behavior class 与被编译类之间的循环依赖。 |
这些是框架自己的命令,注册在 aop 命名空间下。它们运行在入口那一行初始化的内核上,所以省略它们可选的 loader 参数。--workers=N 的 worker 会再次运行 ./yii,因此需要入口那一行。如果是 bootstrap 兜底机制启动了内核,命令会在自己的进程中编译,并给出提示。
./yii aop:warmup --workers=4在生产环境中,关闭 debug,并在部署时构建缓存。--cache-dir=DIR 在另一个目录中构建缓存,内核则继续使用它自己的目录。缓存文件与位置无关,因此你可以把目录直接移动到位。
ENV GOAOP_CACHE_DIR=/app/aopRUN ./yii aop:warmup --workers=4 --preload在只读文件系统上,把 Features::PREBUILT_CACHE 加到 features 中。这样引擎会完全信任缓存,从不写入它,所以每次部署都要重建缓存。包含路径下缓存中没有记录的类会以 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 代码不会。 - 在
AopBootstrap::init()之前加载的类(例如App\Environment)无法被编译。入口那一行读取配置时,配置所加载的类也同样无法被编译。 - Behavior class 本身不需要编译:排除它们所在的目录,例如
'excludePaths' => ['@src/Aspect']。 - 如果创建 behavior class 时运行了它自己的某个 behavior,这个 behavior 会以
Go\Aop\Exception\AspectCircularReferenceException失败。惰性注入那个依赖(用闭包或Psr\Container\ContainerInterface),或者收窄 matching rule。 - 内核是进程全局的。常驻 worker(RoadRunner、Swoole、FrankenPHP)每个 worker 只初始化一次内核。像对待其他共享服务一样,重置那些持有每请求状态的 behavior class。
© 2026 Alexander Lisachenko
