Primeiros passos
Instale o framework com o Composer, crie um kernel, escreva seu primeiro behavior e veja-o rodar em torno do seu código.
Traduzido do inglês. A página em inglês é a referência. Ler o original
Você escreve um behavior (comportamento), como logging, cache, uma verificação de segurança ou uma transação, uma única vez, e o framework o anexa como middleware dinâmico a cada método que você selecionar. No código, os behaviors ficam em uma behavior class (classe de comportamento), que na API se chama aspect (aspecto): cada behavior é um método cujo atributo diz quando ele roda e traz uma matching rule (regra de correspondência) que diz onde. Suas classes ficam só com a lógica de negócio. A tabela de termos relaciona os nomes da API às palavras usadas nesta documentação.
Requisitos
Seção intitulada “Requisitos”- PHP 8.4 ou mais recente. Funciona em todas as versões modernas do PHP.
- Nenhuma extensão PECL ou PIE. É PHP puro: sem
php-aop,runkitouuopz, e semeval(). Usa a extensãotokenizer. - Composer. O framework e suas dependências são instalados como pacotes Composer comuns.
Começar leva cinco passos:
- Instalar o framework com o Composer.
- Criar o kernel da aplicação.
- Inicializar o kernel no front controller (controlador frontal).
- Escrever uma behavior class.
- Registrar a behavior class no kernel.
Instalação com o Composer
Seção intitulada “Instalação com o Composer”composer require goaop/frameworkO Composer instala o framework em vendor/goaop/framework.
Os exemplos desta página usam a estrutura abaixo. Eles supõem que o Composer carrega automaticamente as classes de app/ e src/, por exemplo pela seção autoload do seu composer.json.
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 codeCrie o kernel
Seção intitulada “Crie o kernel”<?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 { }}O kernel gerencia todas as behavior classes da sua aplicação em um só lugar. Estenda a classe abstrata Go\Core\AspectKernel e implemente configureAop(). Por enquanto o método fica vazio; você registra nele sua primeira behavior class mais abaixo.
Inicialize o kernel no front controller
Seção intitulada “Inicialize o kernel no front controller”<?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 hereChame init() uma única vez, logo depois do autoloader do Composer e antes que a aplicação carregue suas próprias classes. Estas quatro opções bastam para começar:
| Opção | Finalidade |
|---|---|
debug |
true liga o modo de desenvolvimento. Use false em produção. |
appDir |
A raiz da aplicação. Só os arquivos abaixo dela são compilados. O padrão é o diretório que contém vendor/. |
cacheDir |
Onde o código gerado é gravado. Esta opção é obrigatória. |
includePaths |
Os diretórios a compilar. Um array vazio significa tudo abaixo de appDir. |
Mantenha includePaths restrito. Compilar código de vendor é lento e raramente necessário. Uma chave de opção desconhecida lança Go\Aop\Exception\InvalidConfigurationException, então um erro de digitação falha na hora em vez de ser ignorado. A lista completa de opções está na página Configuração e CLI.
Escreva seu primeiro behavior
Seção intitulada “Escreva seu primeiro 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"; }}Uma behavior class é uma classe PHP comum que implementa Go\Aop\Aspect. Cada behavior é um método público com um atributo de Go\Lang\Attribute que diz quando ele roda.
- Um behavior
#[Before]roda antes da chamada interceptada. Os outros atributos são#[After],#[AfterThrowing]e#[Around]. - A string no atributo é a matching rule.
execution(public Example->*(*))seleciona a execução de todo método público e não estático da classeExample. - O behavior recebe um
MethodInvocation. Ele dá acesso à chamada interceptada:getArguments()retorna seus argumentos, e a invocação, convertida em string, traz o nome do método.
Métodos de behavior precisam ser public. O framework os chama diretamente na instância da behavior class, então um método de behavior protected ou private é rejeitado quando a classe é carregada. Um método leva no máximo um atributo de behavior.
Registre a behavior class
Seção intitulada “Registre a 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()); }}Uma behavior class é um serviço do container do kernel. addLazyService() registra uma factory. A compile step (etapa de compilação) apenas lê a behavior class, então a factory roda quando um dos behaviors dela roda pela primeira vez, não antes.
Se preferir criar a behavior class de antemão, registre uma instância:
$container->add(MonitorAspect::class, new MonitorAspect());As behavior classes também podem receber suas dependências do container PSR-11 da sua aplicação, que você liga ao container do kernel com setDelegate(). A página Configuração e CLI mostra como.
Veja funcionando
Seção intitulada “Veja funcionando”Adicione uma classe para a matching rule selecionar:
<?php
class Example{ public function greet(string $name): string { return "Hello, {$name}"; }}Depois use-a no front controller, após init():
<?php
include __DIR__ . '/../vendor/autoload.php';
ApplicationAspectKernel::getInstance()->init([/* … as above … */]);
$example = new Example();echo $example->greet('World');Abra a página no navegador ou rode php public/index.php. Antes de Hello, World aparece a linha do behavior, com o nome do método e seus argumentos ["World"]. Example não tem nenhuma referência à behavior class. O behavior foi anexado à classe quando o autoloader a carregou e compilou.
Você nunca chama o behavior por conta própria. Para mudar os métodos em que ele roda, você muda a matching rule, não as classes. A página Behaviors e matching rules explica quando cada behavior roda e a sintaxe completa das matching rules.
Confira o que está registrado
Seção intitulada “Confira o que está registrado”O console bin/aspect precisa de symfony/console:
composer require symfony/consolevendor/bin/aspect debug:aspect public/index.phpdebug:aspect lista as behavior classes registradas e seus behaviors. Todo comando bin/aspect recebe o caminho do arquivo que inicializa o kernel, aqui o front controller, e executa esse arquivo. debug:advisor --advisor=... mostra as chamadas interceptadas que um advisor (um behavior com sua matching rule) seleciona. Use esses comandos quando um behavior não rodar.
Como funciona a compile step
Seção intitulada “Como funciona a compile step”Suas classes são compiladas quando o PHP as carrega. Nada envolve seus objetos em tempo de execução, e nenhum código é gerado com eval(). Cada classe compilada é um arquivo PHP comum no diretório de cache, e é esse arquivo que o PHP executa.
O código gerado
Seção intitulada “O código gerado”Numa classe compilada, o corpo original da classe vai para uma trait. Uma classe gerada com o nome original usa essa trait, então o nome da classe, suas classes pai e self:: continuam como eram. Cada método interceptado ganha um call context (contexto de chamada) com seus behaviors:
static $__joinPoint = InterceptorInjector::forMethod( self::class, 'doSomething', [ Interceptor::before(The::aspect(MonitorAspect::class)->beforeMethodExecution(...)), ], $this->doSomethingOriginalAlias(...),);The::aspect() busca a instância da behavior class no container do kernel. ->beforeMethodExecution(...) é o método de behavior que você escreveu, referenciado com a sintaxe de first-class callable. Você pode dar Ctrl-clique nele na IDE, colocar um breakpoint dentro dele e percorrer o código gerado passo a passo. O último argumento aponta para o corpo do método original.
Os números de linha são preservados, então os breakpoints do Xdebug no seu código original continuam funcionando. Os atributos da classe, de seus métodos, parâmetros, constantes e propriedades são copiados para o código gerado, então lê-los via reflection funciona como antes. Métodos que nenhuma matching rule seleciona rodam sem nenhum código de interceptação.
O diretório de cache
Seção intitulada “O diretório de cache”cacheDir guarda os fontes compilados, os proxies, os caches de advisors e o class map. Os caminhos no cache espelham os caminhos dos fontes relativos a appDir. Os arquivos são PHP comum, então você pode abri-los, compará-los com diff e passá-los pelas suas ferramentas de segurança.
Não faça commit do diretório de cache. Em desenvolvimento, o framework o preenche à medida que as classes são carregadas. Em produção, você o gera no deploy.
Modo de desenvolvimento
Seção intitulada “Modo de desenvolvimento”Com 'debug' => true, toda classe e todo include passam pelo stream filter do framework, que os compila. Mudanças no arquivo do kernel e nos arquivos de behavior classes invalidam o cache, e os arquivos alterados são compilados de novo na próxima requisição. Não há etapa de build: edite uma classe ou um behavior e recarregue a página.
O modo de desenvolvimento é visivelmente mais lento que o modo de produção em requisições quentes. Não o use em produção.
Modo de produção
Seção intitulada “Modo de produção”Com 'debug' => false, as classes compiladas são carregadas do cache pelo class map do Composer. O parser e os transformers não são carregados em requisições mornas.
Para o deploy, gere o cache uma vez e diga ao kernel para confiar nele:
-
Limpe o diretório de cache.
-
Faça o aquecimento do cache:
Janela do terminal vendor/bin/aspect cache:warmup:aop public/index.phpO comando falha quando um arquivo não pode ser compilado, então o script de deploy para em vez de publicar um cache incompleto. Projetos grandes compilam mais rápido em paralelo, por exemplo com
--workers=8. -
Rode com
'debug' => falsee a featurePREBUILT_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,]);
Com PREBUILT_CACHE, uma requisição nunca compila e nunca grava no diretório de cache, então também funciona em um sistema de arquivos somente leitura. O cache precisa estar completo: uma classe abaixo dos include paths da qual o cache não tem registro faz a requisição falhar com uma WeavingException. Gere o cache de novo sempre que o código ou as behavior classes mudarem.
A página Produção e desempenho trata de OPcache, preloading, Docker e Kubernetes.
Próximos passos
Seção intitulada “Próximos passos”Usando um framework
Seção intitulada “Usando um framework”Se sua aplicação roda em Symfony, Laravel ou Yii3, instale a bridge correspondente em vez de escrever você mesmo o código do front controller. A bridge inicializa o framework cedo no ciclo de vida da aplicação e permite registrar behavior classes como serviços do container do seu framework. Veja a página Integrações ou os repositórios goaop/goaop-symfony-bundle, goaop/goaop-laravel-bridge e goaop/goaop-yii3-bridge.
Atualizando a partir da 3.x
Seção intitulada “Atualizando a partir da 3.x”Vai atualizar uma aplicação da versão 3.x? Leia primeiro a página Limitações e atualização. Ela lista todas as mudanças.
Agentes de programação com IA
Seção intitulada “Agentes de programação com IA”O repositório do framework é um marketplace de plugins para agentes de programação. O plugin goaop dele traz uma Agent Skill que ensina um agente a escrever behavior classes, behaviors e matching rules, a integrar o framework, a fazer o deploy do cache e a descobrir por que um behavior não roda. No Claude Code:
/plugin marketplace add goaop/framework/plugin install goaop@goaop© 2026 Alexander Lisachenko
