快速上手
用 Composer 安装框架,创建内核,编写你的第一个 behavior,并看着它在你的代码周围运行。
本页译自英文,以英文页面为准。 阅读原文
日志、缓存、安全检查、事务这类 behavior(行为),你只需编写一次,框架就会把它作为动态 middleware(中间件)挂接到你选中的每一个方法上。在代码里,behavior 放在 behavior class(行为类)中(在 API 里叫 aspect(切面)):每个 behavior 都是一个方法,方法上的注解说明它何时运行,并携带一条 matching rule(匹配规则),说明它在哪里运行。你的业务类只保留业务逻辑。术语表 列出了 API 名称与本文档用语之间的对应关系。
- PHP 8.4 或更高版本。 支持所有现代 PHP 版本。
- 无需 PECL 或 PIE 扩展。 它是纯 PHP 实现:不需要
php-aop、runkit或uopz,也不使用eval()。它依赖tokenizer扩展。 - Composer。 框架及其依赖都以普通 Composer 包的形式安装。
上手只需五步:
- 用 Composer 安装框架。
- 创建应用的内核。
- 在前端控制器中初始化内核。
- 编写一个 behavior class。
- 在内核中注册这个 behavior class。
用 Composer 安装
Section titled “用 Composer 安装”composer require goaop/frameworkComposer 会把框架安装到 vendor/goaop/framework。
本页的示例使用下面的目录结构,并假定 Composer 会自动加载 app/ 和 src/ 中的类,例如通过 composer.json 的 autoload 配置段。
app/ApplicationAspectKernel.php the kernelpublic/index.php the front controllersrc/ your application code, compiled by the frameworksrc/Aspect/MonitorAspect.php your first behavior classvar/cache/aop/ the cache of generated code<?php
use Go\Core\AspectContainer;use Go\Core\AspectKernel;
/** * The application kernel */class ApplicationAspectKernel extends AspectKernel{ /** * Register the behavior classes in the container */ protected function configureAop(AspectContainer $container): void { }}内核在一个地方统一管理应用中的所有 behavior class。继承抽象类 Go\Core\AspectKernel 并实现 configureAop()。这个方法暂时留空,下文会在其中注册你的第一个 behavior class。
在前端控制器中初始化内核
Section titled “在前端控制器中初始化内核”<?php
include __DIR__ . '/../vendor/autoload.php'; // use composer
// Initialize the kernel$applicationAspectKernel = ApplicationAspectKernel::getInstance();$applicationAspectKernel->init([ 'debug' => true, // use 'false' for production mode 'appDir' => __DIR__ . '/..', // Application root directory 'cacheDir' => __DIR__ . '/../var/cache/aop', // Cache directory // Directories whose classes get behaviors; empty means all source files 'includePaths' => [ __DIR__ . '/../src/' ]]);
// Your application starts hereinit() 只调用一次,放在 Composer 自动加载器之后、应用加载自己的类之前。起步时这四个选项就够了:
| 选项 | 用途 |
|---|---|
debug |
true 开启开发模式。生产环境请用 false。 |
appDir |
应用根目录。只有它下面的文件才会被编译。默认是包含 vendor/ 的那个目录。 |
cacheDir |
生成代码的写入位置。此选项为必填。 |
includePaths |
需要编译的目录。空数组表示 appDir 下的全部内容。 |
includePaths 的范围要尽量收窄。编译 vendor 代码很慢,而且很少有必要。未知的选项键会抛出 Go\Aop\Exception\InvalidConfigurationException,所以拼写错误会立即报错,而不是被悄悄忽略。完整的选项列表见 配置与命令行 页面。
编写你的第一个 behavior
Section titled “编写你的第一个 behavior”<?php
namespace Aspect;
use Go\Aop\Aspect;use Go\Aop\Intercept\MethodInvocation;use Go\Lang\Attribute\Before;
/** * A monitoring behavior class */class MonitorAspect implements Aspect{ /** * Method that will be called before real method */ #[Before("execution(public Example->*(*))")] public function beforeMethodExecution(MethodInvocation $invocation): void { echo 'Calling Before Interceptor for: ', $invocation, ' with arguments: ', json_encode($invocation->getArguments()), "<br>\n"; }}Behavior class 是一个实现了 Go\Aop\Aspect 的普通 PHP 类。每个 behavior 都是一个 public 方法,带有一个来自 Go\Lang\Attribute 的注解,说明它何时运行。
#[Before]behavior 在被拦截的调用之前运行。其他注解有#[After]、#[AfterThrowing]和#[Around]。- 注解中的字符串就是 matching rule。
execution(public Example->*(*))选中类Example中每个 public、非 static 方法的执行。 - Behavior 会收到一个
MethodInvocation,它代表被拦截的调用:getArguments()返回调用的参数,而把 invocation 转成字符串会得到方法名。
Behavior 方法必须是 public 的。框架直接在 behavior class 实例上调用它们,因此 protected 或 private 的 behavior 方法会在类加载时被拒绝。一个方法最多只能带一个 behavior 注解。
注册 behavior class
Section titled “注册 behavior class”<?php
use Aspect\MonitorAspect;use Go\Core\AspectContainer;use Go\Core\AspectKernel;
class ApplicationAspectKernel extends AspectKernel{ /** * Register the behavior classes in the container */ protected function configureAop(AspectContainer $container): void { // Deferred (recommended): constructed on first use $container->addLazyService(MonitorAspect::class, static fn() => new MonitorAspect()); }}Behavior class 是内核容器中的一个服务。addLazyService() 注册的是一个工厂。Compile step(编译步骤)只读取 behavior class,因此工厂要等到它的某个 behavior 第一次运行时才会执行,而不是更早。
如果你更想预先创建 behavior class,可以改为注册一个实例:
$container->add(MonitorAspect::class, new MonitorAspect());Behavior class 也可以从应用的 PSR-11 容器中获取依赖,只需用 setDelegate() 把这个容器挂接到内核容器上。具体做法见 配置与命令行 页面。
添加一个供 matching rule 选中的类:
<?php
class Example{ public function greet(string $name): string { return "Hello, {$name}"; }}然后在前端控制器中、init() 之后使用它:
<?php
include __DIR__ . '/../vendor/autoload.php';
ApplicationAspectKernel::getInstance()->init([/* … as above … */]);
$example = new Example();echo $example->greet('World');在浏览器中打开页面,或运行 php public/index.php。在 Hello, World 之前,你会看到 behavior 输出的那一行,其中有方法名和它的参数 ["World"]。Example 没有引用 behavior class。Behavior 是在自动加载器加载并编译这个类时挂接上去的。
你从不需要自己调用 behavior。要改变它作用于哪些方法,修改的是 matching rule,而不是这些类。行为与匹配规则 页面说明了每种 behavior 何时运行,以及 matching rule 的完整语法。
查看已注册的内容
Section titled “查看已注册的内容”bin/aspect 控制台需要 symfony/console:
composer require symfony/consolevendor/bin/aspect debug:aspect public/index.phpdebug:aspect 列出已注册的 behavior class 及其 behavior。每个 bin/aspect 命令都接收初始化内核的那个文件的路径(这里是前端控制器),并执行该文件。debug:advisor --advisor=... 显示某个 advisor(一个 behavior 加上它的 matching rule)所匹配的被拦截调用。Behavior 没有运行时,就用这些命令排查。
Compile step 的工作原理
Section titled “Compile step 的工作原理”你的类在被 PHP 加载时编译。运行时没有任何东西包装你的对象,也不会用 eval() 生成代码。每个编译后的类都是缓存目录中的一个普通 PHP 文件,PHP 执行的正是这个文件。
对于编译后的类,原始类体会移到一个 trait 中。一个与原类同名的生成类会使用这个 trait,因此类名、父类和 self:: 都保持不变。每个被拦截的方法都会得到一个带有其 behavior 的 call context(调用上下文):
static $__joinPoint = InterceptorInjector::forMethod( self::class, 'doSomething', [ Interceptor::before(The::aspect(MonitorAspect::class)->beforeMethodExecution(...)), ], $this->doSomethingOriginalAlias(...),);The::aspect() 从内核容器中取出 behavior class 实例。->beforeMethodExecution(...) 就是你编写的 behavior 方法,以一等可调用(first-class callable)语法引用。你可以在 IDE 里按住 Ctrl 点击跳转到它,在其中设置断点,并单步调试生成的代码。最后一个参数指向原始的方法体。
行号保持不变,所以原始代码中的 Xdebug 断点依然有效。类、方法、参数、常量和属性上的注解都会复制到生成的代码中,因此通过反射读取它们的方式与之前完全一样。没有被任何 matching rule 选中的方法,运行时不带任何拦截代码。
cacheDir 中存放编译后的源码、代理、advisor 缓存和类映射。缓存路径与源文件相对于 appDir 的路径一一对应。这些文件都是普通 PHP,你可以打开、diff,也可以用安全工具扫描它们。
不要把缓存目录提交到版本库。在开发环境中,框架会在类加载时填充它;在生产环境中,你在部署时构建它。
设置 'debug' => true 时,每个类和每次 include 都通过框架的流过滤器加载,并由它完成编译。修改内核文件或 behavior class 文件会使缓存失效,被修改的文件会在下一次请求时重新编译。没有构建步骤:改完类或 behavior,刷新页面即可。
在 hot 请求下,开发模式明显比生产模式慢。不要在生产环境中使用它。
设置 'debug' => false 时,编译后的类通过 Composer 的类映射从缓存中加载。在 warm 请求中,解析器和转换器都不会被加载。
部署时,先构建一次缓存,再告诉内核信任它:
-
清空缓存目录。
-
预热缓存:
终端窗口 vendor/bin/aspect cache:warmup:aop public/index.php只要有文件无法编译,这个命令就会失败,于是部署脚本会停下来,而不是发布一份不完整的缓存。大型项目并行编译会更快,例如使用
--workers=8。 -
以
'debug' => false运行,并启用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,]);
启用 PREBUILT_CACHE 后,请求从不编译,也从不写入缓存目录,因此在只读文件系统上同样可用。缓存必须完整:如果 include 路径下有某个类在缓存中没有记录,请求就会以 WeavingException 失败。代码或 behavior class 有任何变化时,都要重新构建缓存。
生产环境与性能 页面介绍了 OPcache、预加载、Docker 和 Kubernetes。
如果你的应用基于 Symfony、Laravel 或 Yii3,请安装对应的桥接包(bridge),而不是自己编写前端控制器中的代码。桥接包会在应用生命周期的早期启动框架,并让你把 behavior class 注册为框架容器中的服务。参见 集成 页面,或以下仓库:goaop/goaop-symfony-bundle、goaop/goaop-laravel-bridge 和 goaop/goaop-yii3-bridge。
从 3.x 升级
Section titled “从 3.x 升级”要把应用从 3.x 版本升级?请先阅读 限制与升级 页面,其中列出了每一项变更。
AI 编程代理
Section titled “AI 编程代理”框架的代码仓库本身就是一个面向编程代理的插件市场。其中的 goaop 插件包含一个 Agent Skill,能教会代理编写 behavior class、behavior 和 matching rule,集成框架,部署缓存,并找出 behavior 为什么没有运行。在 Claude Code 中:
/plugin marketplace add goaop/framework/plugin install goaop@goaop© 2026 Alexander Lisachenko
