配置与命令行
配置内核、选择特性开关、让 behavior class 从应用容器中获取依赖,并使用控制台。
本页译自英文,以英文页面为准。 阅读原文
框架需要了解的关于你应用的一切,都通过一次调用传入:内核上的 init()。本页列出内核接受的每个选项、各个特性开关、behavior class(行为类)如何从应用容器中获取依赖,以及用来构建和检查缓存的 vendor/bin/aspect 控制台。
你的内核继承 Go\Core\AspectKernel,并在 configureAop() 中注册 behavior class(在 API 里叫 aspect(切面),见 术语表):
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 自动加载器之后:
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 中的常量,用 | 组合使用:
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 |
你想编译的某个类所继承或实现的东西,框架无法定位。 |
INTERCEPT_INCLUDES
Section titled “INTERCEPT_INCLUDES”把编译后文件中的 include 和 require 交给编译器处理。适用于不通过 Composer 加载的遗留代码。
PREBUILT_CACHE
Section titled “PREBUILT_CACHE”完全信任部署时构建的缓存。内核会跳过对缓存目录及其可写性的探测、源文件 filemtime 比较、受跟踪资源检查,以及 advisor 缓存的新鲜度检查。请求从不编译,也从不写入缓存目录,因此可以在只读文件系统上运行。
反过来说,缓存必须完整。编译器从不接手的文件(位于 include 路径之外、被排除、不是 .php,例如被 include 的模板)会原样加载。除此之外,include 路径下的所有内容都必须在缓存中有记录。
cache:warmup:aop 本身并不信任它所构建的缓存。在已有目录上运行时,它会重新编译每个源文件发生变化(大小或修改时间)的文件。它的 loader 文件可能会在构建开始前加载缓存尚不知道的类:这些类在那里以未编译的形式加载,再由构建过程编译。
PARTIAL_REFLECTION
Section titled “PARTIAL_REFLECTION”编译那些父类、接口或 trait 无法定位的类:它们由运行时生成的代码、class_alias() 或 Composer 自动加载器之外的文件声明。这样的类会连同它自己的方法和属性,以及可用祖先类的方法和属性一起被匹配和编译。从缺失的祖先继承来的成员不会被拦截。
不启用这个开关,这样的类会编译失败。遇到这种失败时再打开它。
函数规则与初始化规则无需开关
Section titled “函数规则与初始化规则无需开关”框架会根据已注册的 behavior class(包括惰性注册的)启用这些 matching rule(匹配规则)所需的机制。你不需要在 features 中设置任何东西:
execution(Namespace\function(*))规则会在匹配的命名空间中加入函数代理。initialization(...)规则会开启对编译后文件中new Foo(...)表达式的改写。只要注册了这样的规则,每个被改写的new都会经过拦截器,所以请把这类规则限制在确实需要的代码上。
Matching rule 的语法见 行为与匹配规则。
从应用容器获取 behavior class
Section titled “从应用容器获取 behavior class”内核容器是一个 PSR-11 容器(Go\Core\AspectContainer 继承了 Psr\Container\ContainerInterface)。它可以委托给你应用的容器:Symfony、Laravel、PHP-DI 或任何其他 PSR-11 容器。对于未在内核容器中注册的 id,get()、getService() 和 has() 会转而查询委托容器。
内核在应用构建容器之前就已初始化。所以你照常注册 behavior class,让它们惰性地解析依赖:
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 的桥接包见 集成。
Behavior class 工厂的规则
Section titled “Behavior class 工厂的规则”- 工厂永远不要向内核容器请求它自己的 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 不去拦截自己依赖的创建过程。
自定义容器类
Section titled “自定义容器类”要替换内核容器,把你的类作为 containerClass 传入。它必须实现 Go\Core\AspectContainer,也就是 PSR-11 的 get() 和 has(),外加 setDelegate()。未知的 id 会抛出 ServiceNotFoundException,它实现了 Psr\Container\NotFoundExceptionInterface。
开发模式与生产模式
Section titled “开发模式与生产模式”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>OriginalTraittrait 的形式,存放在与其源文件相同的相对路径下; - 代理,与编译后的源码放在一起,使用原始类名;
- 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.phpvendor/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 |
预热缓存两次,并报告两次生成结果不同的代理。 |
cache:warmup:aop
Section titled “cache:warmup:aop”rm -rf var/cache/aopvendor/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也是如此。如果你希望缓存恰好只包含当前版本,请从空目录开始。
cache:warmup:opcache
Section titled “cache:warmup:opcache”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 类映射中无法编译的文件会被列出并跳过。
debug:aspect
Section titled “debug:aspect”vendor/bin/aspect debug:aspect public/index.php列出已注册的 behavior class 及其 behavior。它还接受 --aspect=... 选项。
debug:advisor
Section titled “debug:advisor”vendor/bin/aspect debug:advisor public/index.php列出所有 advisor。加上 --advisor=... 时,它会显示该 advisor 所匹配的被拦截调用,从而告诉你 matching rule 是否选中了你预期的方法。
debug:weaving
Section titled “debug:weaving”vendor/bin/aspect debug:weaving public/index.php预热缓存两次,并报告两次运行之间生成结果不同的代理。出现差异说明某个 behavior class 的行为不是确定性的。
rm -rf var/cache/aopvendor/bin/aspect cache:warmup:aop public/index.php --workers=8- 清空缓存目录。
- 用
cache:warmup:aop预热缓存。只要有文件无法编译,这个命令就会失败,于是部署会停下来,而不是发布一份不完整的缓存。大型项目用--workers并行编译会更快。 - 以
'debug' => false运行,并启用Features::PREBUILT_CACHE。
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
