跳转到内容
文档 · 集成

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-bridge

yiisoft/config 插件会读取桥接包的配置。如果你是在禁用该插件的情况下安装的,请运行 composer yii-config-rebuild。

public/index.php
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 配置组仍然会启动内核,但为时已晚:构建容器期间加载的类不会被编译。在调试模式下,这包括每个使用数组定义的类,于是应用在开发环境和生产环境中的表现会不一样。

<?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:

config/common/params.php
'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 的解析过程:

  1. 内核启动时不会自动加载任何东西:只对类名做语法校验。
  2. 当编译器需要某个类的 behavior 时,它通过反射从类中读取。此时 behavior class 对象是一个原生惰性代理,尚未被构造。
  3. 在它的某个 behavior 第一次被调用时,代理通过 $container->get(AspectClass::class) 完成初始化,得到的是 Yii 容器中的共享实例。

依赖数据库连接或 HTTP 客户端的 behavior class,在从未触及带有 behavior 的方法的请求中,不会创建这些连接或客户端。在调试模式下,桥接包会检查每个列出的类是否存在并实现了 Go\Aop\Aspect。

扩展包可以通过自己的 config/params.php 贡献 behavior class。params 组会递归合并,列表会被追加,重复的只注册一次:

config/params.php
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 在另一个目录中构建缓存,内核则继续使用它自己的目录。缓存文件与位置无关,因此你可以把目录直接移动到位。

Dockerfile
ENV GOAOP_CACHE_DIR=/app/aop
RUN ./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