Pular para o conteúdo
Documentação

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.

  • 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, runkit ou uopz, e sem eval(). Usa a extensão tokenizer.
  • Composer. O framework e suas dependências são instalados como pacotes Composer comuns.

Começar leva cinco passos:

  1. Instalar o framework com o Composer.
  2. Criar o kernel da aplicação.
  3. Inicializar o kernel no front controller (controlador frontal).
  4. Escrever uma behavior class.
  5. Registrar a behavior class no kernel.
Janela do terminal
composer require goaop/framework

O 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 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
{
}
}

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.

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

Chame 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.

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";
}
}

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 classe Example.
  • 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.

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());
}
}

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.

Adicione uma classe para a matching rule selecionar:

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

Depois use-a no front controller, após init():

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

O console bin/aspect precisa de symfony/console:

Janela do terminal
composer require symfony/console
vendor/bin/aspect debug:aspect public/index.php

debug: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.

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.

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.

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.

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.

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:

  1. Limpe o diretório de cache.

  2. Faça o aquecimento do cache:

    Janela do terminal
    vendor/bin/aspect cache:warmup:aop public/index.php

    O 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.

  3. Rode com 'debug' => false e a feature 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,
    ]);

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.

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.

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.

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