跳转到内容
文档

配置与命令行

配置内核、选择特性开关、让 behavior class 从应用容器中获取依赖,并使用控制台。

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

框架需要了解的关于你应用的一切,都通过一次调用传入:内核上的 init()。本页列出内核接受的每个选项、各个特性开关、behavior class(行为类)如何从应用容器中获取依赖,以及用来构建和检查缓存的 vendor/bin/aspect 控制台。

你的内核继承 Go\Core\AspectKernel,并在 configureAop() 中注册 behavior class(在 API 里叫 aspect(切面),见 术语表):

app/ApplicationAspectKernel.php
use Aspect\MonitorAspect;
use Go\Core\AspectContainer;
use Go\Core\AspectKernel;
class ApplicationAspectKernel extends AspectKernel
{
protected function configureAop(AspectContainer $container): void
{
// Deferred (recommended): constructed on first use
$container->addLazyService(MonitorAspect::class, static fn() => new MonitorAspect());
// Eager alternative: $container->add(MonitorAspect::class, new MonitorAspect());
}
}

它只需初始化一次,通常是在前端控制器中,紧跟在 Composer 自动加载器之后:

public/index.php
include __DIR__ . '/../vendor/autoload.php';
ApplicationAspectKernel::getInstance()->init([
'debug' => false,
'appDir' => __DIR__ . '/..',
'cacheDir' => __DIR__ . '/../var/cache/aop',
'includePaths' => [__DIR__ . '/../src'],
]);

只接受下面这些选项。未知的键、未知的 containerClass 或未知的特性位都会抛出 Go\Aop\Exception\InvalidConfigurationException,因此拼写错误会在启动时立即报错,而不是被悄悄忽略。

选项 类型 默认值 用途
cacheDir string 无,必填 存放编译后的源码、代理、advisor 缓存和类映射的目录。
appDir string 包含 vendor/ 的那个目录 应用根目录。缓存路径与源文件相对于它的路径一一对应,并且只有它下面的文件才会被编译。
debug bool false 开发模式:内核文件和 behavior class 文件的修改会使缓存失效,每个类和每次 include 都通过框架负责编译的流过滤器加载。设为 false 时,编译后的类通过 Composer 的类映射从缓存中加载。生产环境请用 false。
includePaths string[] [](appDir 下的全部内容) 需要编译的目录。范围要尽量收窄:编译 vendor 代码很慢,而且很少有必要。
excludePaths string[] [] 永远不编译的目录。缓存目录、框架本身及其运行时依赖(goaop/dissect、goaop/parser-reflection、nikic/php-parser、psr/container、symfony/finder)始终被排除。
features int 0 Go\Aop\Features 开关的位掩码,见下一节。
cacheFileMode int 0770 减去 umask 缓存文件的权限。必须在 0600 到 0777 之间,并赋予所有者读写权限;目录会得到相应的搜索(执行)位。
containerClass class-string Go\Core\Container 内核容器的实现。必须实现 Go\Core\AspectContainer(一个 PSR-11 ContainerInterface)。
parsedFilesLimit int 100 编译期间 goaop/parser-reflection 在内存中保留的已解析源文件(语法树,每个约 0.2 MB)数量。必须是正整数:越大,重复解析越少;越小,占用内存越少。它会取代在 init() 之前用 ReflectionEngine::setMaximumCachedFiles() 设置的上限,同时也是 cache:warmup:aop --cached-files 的默认值。

特性开关是 final 类 Go\Aop\Features 中的常量,用 | 组合使用:

public/index.php
use Go\Aop\Features;
ApplicationAspectKernel::getInstance()->init([
'debug' => false,
'appDir' => __DIR__ . '/..',
'cacheDir' => __DIR__ . '/../var/cache/aop',
'includePaths' => [__DIR__ . '/../src'],
'features' => Features::INTERCEPT_INCLUDES | Features::PREBUILT_CACHE,
]);

Features::ALL 组合了所有开关。AspectKernel::hasFeature() 告诉你某个开关是否已设置,遇到未知开关时会抛出异常。

开关 适用场景
INTERCEPT_INCLUDES 你的应用用 include/require 而不是 Composer 加载代码。
PREBUILT_CACHE 你在部署时构建缓存,并希望请求完全信任它。这是生产环境的设置。
PARTIAL_REFLECTION 你想编译的某个类所继承或实现的东西,框架无法定位。

把编译后文件中的 include 和 require 交给编译器处理。适用于不通过 Composer 加载的遗留代码。

完全信任部署时构建的缓存。内核会跳过对缓存目录及其可写性的探测、源文件 filemtime 比较、受跟踪资源检查,以及 advisor 缓存的新鲜度检查。请求从不编译,也从不写入缓存目录,因此可以在只读文件系统上运行。

反过来说,缓存必须完整。编译器从不接手的文件(位于 include 路径之外、被排除、不是 .php,例如被 include 的模板)会原样加载。除此之外,include 路径下的所有内容都必须在缓存中有记录。

cache:warmup:aop 本身并不信任它所构建的缓存。在已有目录上运行时,它会重新编译每个源文件发生变化(大小或修改时间)的文件。它的 loader 文件可能会在构建开始前加载缓存尚不知道的类:这些类在那里以未编译的形式加载,再由构建过程编译。

编译那些父类、接口或 trait 无法定位的类:它们由运行时生成的代码、class_alias() 或 Composer 自动加载器之外的文件声明。这样的类会连同它自己的方法和属性,以及可用祖先类的方法和属性一起被匹配和编译。从缺失的祖先继承来的成员不会被拦截。

不启用这个开关,这样的类会编译失败。遇到这种失败时再打开它。

函数规则与初始化规则无需开关

Section titled “函数规则与初始化规则无需开关”

框架会根据已注册的 behavior class(包括惰性注册的)启用这些 matching rule(匹配规则)所需的机制。你不需要在 features 中设置任何东西:

  • execution(Namespace\function(*)) 规则会在匹配的命名空间中加入函数代理。
  • initialization(...) 规则会开启对编译后文件中 new Foo(...) 表达式的改写。只要注册了这样的规则,每个被改写的 new 都会经过拦截器,所以请把这类规则限制在确实需要的代码上。

Matching rule 的语法见 行为与匹配规则。

内核容器是一个 PSR-11 容器(Go\Core\AspectContainer 继承了 Psr\Container\ContainerInterface)。它可以委托给你应用的容器:Symfony、Laravel、PHP-DI 或任何其他 PSR-11 容器。对于未在内核容器中注册的 id,get()、getService() 和 has() 会转而查询委托容器。

内核在应用构建容器之前就已初始化。所以你照常注册 behavior class,让它们惰性地解析依赖:

app/ApplicationAspectKernel.php
protected function configureAop(AspectContainer $container): void
{
// Runs when one of its behaviors first runs, after the application container is attached
$container->addLazyService(
MonitorAspect::class,
static fn(AspectContainer $container) => new MonitorAspect($container->getService(LoggerInterface::class)),
);
// or take the whole behavior class from the application container, by the id it has there
// $container->addLazyService(MonitorAspect::class, static fn(AspectContainer $c) => $c->get('app.monitor_aspect'));
}

一旦应用容器创建完毕(例如在框架的内核启动之后),就把它挂接上:

ApplicationAspectKernel::getInstance()->getContainer()->setDelegate($psrContainer);

Compile step(编译步骤)和缓存预热只需要 behavior class 本身。它们在 setDelegate() 之前运行(即使在 vendor/bin/aspect 中也是如此),并且从不创建它的实例。工厂在它的某个 behavior(行为)第一次运行时执行;如果此时某个依赖仍然缺失,就会抛出 ServiceNotFoundException。

Symfony、Laravel 和 Yii 3 的桥接包见 集成。

  • 工厂永远不要向内核容器请求它自己的 id。 这个 id 解析出来的正是当前正在构建的 behavior class。请按应用容器中的 id 从那里获取实例,或者用它的依赖自行构建。
  • Behavior class 永远不会从委托容器中被发现。 PSR-11 容器无法被内省:没有标准方法可以按接口或标签查找服务。每个 behavior class 都要在 configureAop() 中注册。针对特定框架的桥接包可以从自己的容器中按标签或接口收集服务,再用 addLazyService() 注册它们。
  • Compile step 从不创建 behavior class 实例。 它读取 behavior class,生成的代码按类名和方法名引用每个 behavior。每个 behavior class,包括没有实例属性的(PHP 无法让它们变成惰性的),都会在它的某个 behavior 第一次运行时、应用容器已挂接之后,由它的工厂创建。
  • 创建 behavior class 时不能触发它自己的任何一个 behavior。 如果 behavior class 依赖某个服务,而它的某个 behavior 恰好拦截了该服务的构造过程(服务的构造函数,或构造函数调用的某个方法),那么这个 behavior 就会在一个尚不存在的实例上运行。拦截器会用 AspectCircularReferenceException 报告这种情况,指出 behavior class、被拦截的调用,以及从创建到该 behavior 的调用链。请惰性地注入这个依赖(惰性服务、闭包或服务定位器),或者收窄 matching rule,让 behavior class 不去拦截自己依赖的创建过程。

要替换内核容器,把你的类作为 containerClass 传入。它必须实现 Go\Core\AspectContainer,也就是 PSR-11 的 get() 和 has(),外加 setDelegate()。未知的 id 会抛出 ServiceNotFoundException,它实现了 Psr\Container\NotFoundExceptionInterface。

debug 选项在两种模式之间切换。你的 behavior class 和 matching rule 在两种模式下完全相同。

'debug' => true 'debug' => false
类加载 每个类和每次 include 都经过负责编译的流过滤器。 编译后的类通过 Composer 的类映射从缓存中获取。
源文件、behavior class 或内核文件有改动 在下一次请求时重新编译。 缓存原样提供。
重建缓存 不需要。 每次部署时,用 cache:warmup:aop。
适用于 本地开发。 生产环境。再加上 Features::PREBUILT_CACHE。

开发时没有构建步骤:改完类或 behavior,刷新页面,框架就会重新编译改动的部分。断点在原始代码中照常生效。

在生产环境中,框架把缓存的类映射交给 Composer,warm 请求中不会加载解析器和转换器。再加上 PREBUILT_CACHE,请求还会跳过所有源文件检查和缓存新鲜度检查。进一步调优的方法(OPcache、预加载、容器)见 生产环境与性能。

cacheDir 是唯一的必填选项。这个目录中存放:

  • 编译后的源码:每个原始类体以 <Class>OriginalTrait trait 的形式,存放在与其源文件相同的相对路径下;
  • 代理,与编译后的源码放在一起,使用原始类名;
  • Behavior class 的 advisor 缓存,以普通 PHP 文件的形式与编译后的源码放在一起;
  • 元数据,其中包括 _include.cache,即交给 Composer 的类映射;
  • _preload.php,在你用 cache:warmup:aop --preload 构建缓存时生成。

需要了解的几点:

  • 它与 appDir 一一对应。 缓存路径相对于应用根目录,元数据中的路径也以相对于 __DIR__ 的形式存储,因此应用目录移动后缓存依然有效。
  • 它永远不会被编译。 无论你在 excludePaths 中写了什么,缓存目录始终被排除。
  • 权限取自 cacheFileMode。 默认值是 0770 减去 umask。请以处理请求的那个用户的身份(或为该用户)构建缓存。
  • 从 3.x 升级时删除它。 3.x 的缓存文件一个都不会被复用,而且在启用 PREBUILT_CACHE 时,由其他框架版本构建的缓存会被拒绝。
终端窗口
vendor/bin/aspect cache:warmup:aop public/index.php

vendor/bin/aspect 需要 symfony/console(^7.4 || ^8.0)。如果你的应用还没有它,用 Composer 安装。

每个命令都接收初始化内核的那个文件的路径,通常是前端控制器或某个引导文件。该文件会被执行,因此命令看到的内核与你的应用使用完全相同的选项。如果应用已经初始化了自己的内核(例如框架集成提供的控制台,其中这些命令被注册为服务),就省略这个参数:命令会使用当前进程的内核。

每个命令都返回 Command::SUCCESS 或 Command::FAILURE。在脚本中请检查退出码。

命令 用途
cache:warmup:aop 把 include 路径下的每个文件编译进缓存。
cache:warmup:opcache 用框架的缓存以及一个请求会加载的内容预先填充 opcache.file_cache。
debug:aspect 列出已注册的 behavior class 及其 behavior。
debug:advisor 列出所有 advisor(每个 behavior 及其 matching rule),或某个 advisor 所匹配的被拦截调用。
debug:weaving 预热缓存两次,并报告两次生成结果不同的代理。
终端窗口
rm -rf var/cache/aop
vendor/bin/aspect cache:warmup:aop public/index.php --workers=8

这个命令编译 includePaths 下(减去 excludePaths)的每个文件,并写入编译后的文件、代理、advisor 缓存和元数据。它会显示一个进度条。每个无法编译的文件都会报告到 stderr,并以非零退出码退出,因此部署脚本或 docker build 会就此停下,而不是发布一份不完整的缓存。

选项 默认值 用途
--workers=N 1(在命令进程中编译) 在 N 个并行的 worker 进程中编译。设为 CPU 数量即可。
--cached-files=N 内核选项 parsedFilesLimit,100 每个进程在内存中保留的已解析文件数量。
--fail-fast 关闭 在第一个无法编译的文件处停止。
--cache-dir=DIR 内核的 cacheDir 在另一个目录中从零开始构建缓存,而内核和 worker 继续使用它们自己的目录。
--preload[=FILE] 关闭 同时写出缓存的 opcache.preload 脚本:缓存目录中的 _preload.php,或 FILE。
-v 关闭 打印每个文件,而不只是进度条。

关于这些选项:

  • --cache-dir 让部署流程可以在正在运行的缓存旁边准备下一个版本的缓存,然后原子地切换过去,例如通过替换符号链接。用这种方式构建的缓存是完整的、与位置无关的,即使是由一个自身缓存已经预热的生产内核来构建也是如此:编译器始终读取原始源码,从不读取 Composer 提供的编译后文件。
  • --preload 不带值时必须放在 loader 参数之后,否则它会把 loader 当作自己的值。这个脚本在 PHP 启动时链接缓存所知道的每个编译后的类和每个未转换的类;在静态初始化上带有 behavior 的类则留给自动加载器处理。脚本中没有任何绝对路径,并且只列出这份缓存中的类,所以要随缓存一起重建。如何配置预加载见 生产环境与性能。
  • 在已有目录上运行时,命令会重新编译每个源文件发生变化(大小或修改时间)的文件,并保留其他文件,即使启用了 PREBUILT_CACHE 也是如此。如果你希望缓存恰好只包含当前版本,请从空目录开始。
终端窗口
vendor/bin/aspect cache:warmup:opcache public/index.php --file-cache=/var/cache/opcache --entry=public/index.php

把生产请求会加载的内容编译进 opcache.file_cache:框架的缓存、Composer 的类映射和自动加载的文件、未转换的源文件、loader 以及入口文件。之后新的 PHP-FPM 主进程或 CLI 进程会从磁盘读取已编译的脚本,而不必重新编译它们。

选项 用途
--file-cache=DIR opcache.file_cache 目录,必须与配置中的一致。
--entry=FILE 要编译的入口文件。多个文件时重复使用该选项。

只有以 -d opcache.enable_cli=1 -d opcache.file_cache_only=1 -d opcache.file_cache=DIR 启动的进程才会把已编译的脚本写入磁盘。如果命令运行时没有这些参数,它会打印出应该运行的确切命令。

文件缓存与 PHP 构建以及文件的绝对路径绑定。请在最终镜像中、在 cache:warmup:aop 之后,用处理请求的那个 PHP 二进制文件运行这个命令。框架的缓存、加载器和入口文件必须能够编译,否则命令会失败;Composer 类映射中无法编译的文件会被列出并跳过。

终端窗口
vendor/bin/aspect debug:aspect public/index.php

列出已注册的 behavior class 及其 behavior。它还接受 --aspect=... 选项。

终端窗口
vendor/bin/aspect debug:advisor public/index.php

列出所有 advisor。加上 --advisor=... 时,它会显示该 advisor 所匹配的被拦截调用,从而告诉你 matching rule 是否选中了你预期的方法。

终端窗口
vendor/bin/aspect debug:weaving public/index.php

预热缓存两次,并报告两次运行之间生成结果不同的代理。出现差异说明某个 behavior class 的行为不是确定性的。

终端窗口
rm -rf var/cache/aop
vendor/bin/aspect cache:warmup:aop public/index.php --workers=8
  1. 清空缓存目录。
  2. 用 cache:warmup:aop 预热缓存。只要有文件无法编译,这个命令就会失败,于是部署会停下来,而不是发布一份不完整的缓存。大型项目用 --workers 并行编译会更快。
  3. 以 'debug' => false 运行,并启用 Features::PREBUILT_CACHE。
public/index.php
use Go\Aop\Features;
ApplicationAspectKernel::getInstance()->init([
'debug' => false,
'appDir' => __DIR__ . '/..',
'cacheDir' => __DIR__ . '/../var/cache/aop',
'includePaths' => [__DIR__ . '/../src'],
'features' => Features::PREBUILT_CACHE,
]);

只要代码、behavior class、内核选项或 composer.lock 有变化,就要重建缓存。实际上,这意味着每次部署都要重建。开发模式不需要重建。

OPcache 调优、预加载、Composer 自动加载器参数,以及把缓存构建进 Docker 镜像,见 生产环境与性能。从 3.x 升级(包括缓存格式的变化)见 限制与升级。

© 2026 Alexander Lisachenko