跳转到内容
文档

快速上手

用 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 包的形式安装。

上手只需五步:

  1. 用 Composer 安装框架。
  2. 创建应用的内核。
  3. 在前端控制器中初始化内核。
  4. 编写一个 behavior class。
  5. 在内核中注册这个 behavior class。
终端窗口
composer require goaop/framework

Composer 会把框架安装到 vendor/goaop/framework。

本页的示例使用下面的目录结构,并假定 Composer 会自动加载 app/ 和 src/ 中的类,例如通过 composer.json 的 autoload 配置段。

app/ApplicationAspectKernel.php the kernel
public/index.php the front controller
src/ your application code, compiled by the framework
src/Aspect/MonitorAspect.php your first behavior class
var/cache/aop/ the cache of generated code
app/ApplicationAspectKernel.php
<?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。

public/index.php
<?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 here

init() 只调用一次,放在 Composer 自动加载器之后、应用加载自己的类之前。起步时这四个选项就够了:

选项 用途
debug true 开启开发模式。生产环境请用 false。
appDir 应用根目录。只有它下面的文件才会被编译。默认是包含 vendor/ 的那个目录。
cacheDir 生成代码的写入位置。此选项为必填。
includePaths 需要编译的目录。空数组表示 appDir 下的全部内容。

includePaths 的范围要尽量收窄。编译 vendor 代码很慢,而且很少有必要。未知的选项键会抛出 Go\Aop\Exception\InvalidConfigurationException,所以拼写错误会立即报错,而不是被悄悄忽略。完整的选项列表见 配置与命令行 页面。

src/Aspect/MonitorAspect.php
<?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 注解。

app/ApplicationAspectKernel.php
<?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 选中的类:

src/Example.php
<?php
class Example
{
public function greet(string $name): string
{
return "Hello, {$name}";
}
}

然后在前端控制器中、init() 之后使用它:

public/index.php
<?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 的完整语法。

bin/aspect 控制台需要 symfony/console:

终端窗口
composer require symfony/console
vendor/bin/aspect debug:aspect public/index.php

debug:aspect 列出已注册的 behavior class 及其 behavior。每个 bin/aspect 命令都接收初始化内核的那个文件的路径(这里是前端控制器),并执行该文件。debug:advisor --advisor=... 显示某个 advisor(一个 behavior 加上它的 matching rule)所匹配的被拦截调用。Behavior 没有运行时,就用这些命令排查。

你的类在被 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 请求中,解析器和转换器都不会被加载。

部署时,先构建一次缓存,再告诉内核信任它:

  1. 清空缓存目录。

  2. 预热缓存:

    终端窗口
    vendor/bin/aspect cache:warmup:aop public/index.php

    只要有文件无法编译,这个命令就会失败,于是部署脚本会停下来,而不是发布一份不完整的缓存。大型项目并行编译会更快,例如使用 --workers=8。

  3. 以 '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 版本升级?请先阅读 限制与升级 页面,其中列出了每一项变更。

框架的代码仓库本身就是一个面向编程代理的插件市场。其中的 goaop 插件包含一个 Agent Skill,能教会代理编写 behavior class、behavior 和 matching rule,集成框架,部署缓存,并找出 behavior 为什么没有运行。在 Claude Code 中:

/plugin marketplace add goaop/framework
/plugin install goaop@goaop

© 2026 Alexander Lisachenko