Pular para o conteúdo
Documentação · Integrações

Laravel

Middleware para qualquer método, não só para rotas. A goaop/goaop-laravel-bridge 2.0 acopla behaviors às suas classes, e o container, a configuração e o Artisan do Laravel fazem o resto.

Traduzido do inglês. A página em inglês é a referência. Ler o original

O middleware é uma das melhores ideias do Laravel. Uma requisição passa por uma pilha de classes pequenas, e cada uma acrescenta uma única coisa (autenticação, throttling, uma sessão) sem tocar no seu controller. A bridge goaop/goaop-laravel-bridge 2.0 leva essa ideia a todo método e toda propriedade da sua aplicação, sejam públicos, protegidos ou privados. Você escreve um behavior (comportamento) uma única vez, diz onde ele se aplica, e ele roda em torno dessas chamadas como middleware dinâmico: em services, actions, jobs e qualquer outra classe em app/.

app/Services/OrderService.php
use App\Attributes\Transactional;
final class OrderService
{
public function __construct(private readonly Inventory $inventory) {}
#[Transactional]
public function place(Cart $cart): Order
{
$order = Order::create(['customer_id' => $cart->customerId]);
$order->lines()->createMany($cart->lines());
$this->inventory->reserve($cart);
return $order;
}
}
app/Behaviors/TransactionalBehavior.php
namespace App\Behaviors;
use Go\Aop\Aspect;
use Go\Aop\Intercept\MethodInvocation;
use Go\Lang\Attribute\Around;
use Illuminate\Support\Facades\DB;
final class TransactionalBehavior implements Aspect
{
#[Around('@execution(App\Attributes\Transactional)')]
public function inTransaction(MethodInvocation $invocation): mixed
{
return DB::transaction(fn () => $invocation->proceed());
}
}

Esse é o padrão completo. Se você já escreveu o handle($request, $next) de um middleware, já o conhece: $invocation->proceed() é o seu $next($request). Todo método marcado com #[Transactional] agora faz commit ou rollback como uma unidade, e o OrderService continua contendo só a lógica de negócio. Você não precisa de classe base, interface, decorator nem de uma chamada a app()->extend().

  • Instala como qualquer outro pacote. Um composer require, e o package discovery registra o service provider. Um único arquivo de configuração publicável, config/go_aop.php, com overrides pelas variáveis de ambiente GOAOP_*.
  • Behavior classes (classes de comportamento) são serviços do container. O container do Laravel constrói cada behavior class na primeira vez que um dos seus behaviors roda. A injeção pelo construtor funciona, assim como as facades, config() e todo serviço que a sua aplicação registra.
  • Registre-as onde você registra todo o resto. Liste uma classe na configuração, ou marque um serviço com a tag goaop.aspect em um service provider, para que um pacote possa contribuir com os próprios behaviors.
  • O Artisan faz o trabalho de produção. php artisan aop:warmup gera o cache no deploy, em workers paralelos se você quiser. Ele se encaixa no deploy que você já roda, depois de composer install e php artisan optimize. php artisan about mostra a localização do cache e o modo debug.
  • Sem etapa de build em desenvolvimento. Com debug ligado, uma classe alterada é compilada de novo na próxima requisição, e os breakpoints funcionam nos seus arquivos originais.

Um decorator envolve um objeto que você resolve do container, então ele só vê métodos públicos, e só nesse caminho. Um behavior é acoplado à própria classe enquanto ela é carregada, então:

  • Toda instância o recebe. Objetos vindos do container e objetos que você cria com new se comportam do mesmo jeito. Type hints, instanceof e o nome da classe não mudam, porque não existe nenhum objeto wrapper.
  • Todo tipo de método se qualifica. Métodos privados, protegidos, final e estáticos, e métodos de classes final e readonly (Intercept anything).
  • Propriedades também. Leituras e escritas de propriedades públicas, protegidas e privadas, incluindo as promovidas no construtor, por meio de property hooks nativos do PHP 8.4: access(private App\Domain\Order->status) ou @access(App\Attributes\Audited) (Behaviors em propriedades).
  • Uma regra pode cobrir um namespace. execution(public App\Services\**->*(*)) seleciona todo método público abaixo de App\Services, incluindo as classes que você adicionar no mês que vem (matching rules (regras de correspondência)).
  • O custo é pequeno. Métodos e propriedades sem behaviors não custam nada a mais. Um método ou uma propriedade com um behavior paga menos de 1 µs por chamada (custos medidos).
  • É PHP puro. Nenhuma extensão PECL e nenhum eval(). As classes compiladas são arquivos .php comuns em storage/framework/aop, então você pode lê-las (Pure PHP).
  • PHP 8.4 ou mais novo
  • Laravel 12 ou 13
  • goaop/framework ^4.0 (behaviors declarados com atributos), instalado junto com a bridge
Janela do terminal
composer require goaop/goaop-laravel-bridge

O package discovery registra o service provider automaticamente. Publique a configuração se quiser alterá-la:

Janela do terminal
php artisan vendor:publish --tag=goaop-config

Uma behavior class, que na API se chama aspect (aspecto), é uma classe comum que implementa Go\Aop\Aspect. Cada um dos seus métodos públicos com #[Before], #[After], #[Around] ou #[AfterThrowing] é um behavior, e a string nesse atributo é a sua matching rule, que na API se chama pointcut (ponto de corte): ela diz onde o behavior roda.

  1. Crie um atributo para marcar os métodos, ou pule este passo e selecione os métodos pelo nome (veja a próxima seção).

    app/Attributes/Transactional.php
    namespace App\Attributes;
    use Attribute;
    #[Attribute(Attribute::TARGET_METHOD)]
    final class Transactional {}
  2. Escreva a behavior class. O TransactionalBehavior do topo desta página está completo. #[Around] roda o behavior no lugar do método, e @execution(App\Attributes\Transactional) seleciona todo método que carrega o atributo.

  3. Registre a behavior class em config/go_aop.php:

    config/go_aop.php
    'aspects' => [
    App\Behaviors\TransactionalBehavior::class,
    ],
  4. Marque um método com #[Transactional] e chame-o. A próxima requisição o executa dentro de uma transação.

Um behavior não precisa de um atributo no alvo. Uma matching rule pode selecionar métodos por nome, namespace ou visibilidade, então uma camada inteira da aplicação recebe o behavior sem nenhuma mudança nas suas classes:

app/Behaviors/ServiceTimingBehavior.php
namespace App\Behaviors;
use Go\Aop\Aspect;
use Go\Aop\Intercept\MethodInvocation;
use Go\Lang\Attribute\Around;
use Go\Lang\Attribute\Before;
use Illuminate\Support\Facades\Log;
final class ServiceTimingBehavior implements Aspect
{
#[Before('execution(public App\Services\**->*(*))')]
public function logCall(MethodInvocation $invocation): void
{
Log::debug('Calling ' . $invocation->getMethod()->getName());
}
#[Around('execution(public App\Services\PaymentService->charge(*))')]
public function measureCharge(MethodInvocation $invocation): mixed
{
$start = hrtime(true);
try {
return $invocation->proceed();
} finally {
Log::info('charge() took ' . (hrtime(true) - $start) / 1e6 . ' ms');
}
}
}

logCall() roda antes de todo método público abaixo de App\Services. measureCharge() envolve um método e mede o seu tempo, também quando ele lança uma exceção. Os quatro atributos, o call context (contexto de chamada, $invocation) e a sintaxe completa das regras estão em Behaviors e matching rules. Para passo a passo completos, veja o behavior de cache e o behavior de logging.

Você nunca entrega behavior classes ao engine por conta própria. Durante a fase de boot, depois que todos os service providers fizeram o registro e antes que o código da sua aplicação rode, a bridge as coleta de duas fontes.

A lista na configuração. Liste a classe em config/go_aop.php, como nos passos acima. Uma classe listada é registrada assim que o kernel inicia, sem que a classe seja carregada. O container do Laravel a resolve na primeira chamada de um dos seus behaviors, então uma behavior class pode depender de serviços que só existem depois que a aplicação concluiu o boot. Uma requisição que não roda nenhum dos seus behaviors nunca a cria.

A tag goaop.aspect. Marque um serviço com a tag em um dos seus service providers:

app/Providers/AppServiceProvider.php
use App\Behaviors\ServiceTimingBehavior;
use Psr\Log\LoggerInterface;
// in register()
$this->app->singleton(ServiceTimingBehavior::class, function ($app) {
return new ServiceTimingBehavior($app->make(LoggerInterface::class));
});
$this->app->tag([ServiceTimingBehavior::class], 'goaop.aspect');

Use a tag quando uma behavior class precisa de uma construção não trivial, ou quando um pacote contribui com behavior classes sem mexer na sua configuração. Os serviços com a tag são resolvidos quando o provider da bridge faz o boot, porque uma tag do Laravel só pode ser enumerada resolvendo os seus serviços. Prefira a lista na configuração para behavior classes com construtores pesados ou que dependam do boot.

Você pode combinar as duas fontes; duplicatas são registradas uma única vez. Uma classe descoberta que não implementa Go\Aop\Aspect falha com uma exceção descritiva. O container do Laravel é ligado ao container do kernel como o seu delegate PSR-11, então os behaviors e as factories das behavior classes podem buscar serviços da aplicação por meio dele.

Principais opções em config/go_aop.php. Cada uma pode ser sobrescrita pelo ambiente.

Opção Padrão Finalidade
debug GOAOP_DEBUG → APP_DEBUG Compila de novo quando os fontes mudam, com breakpoints nos arquivos originais; mantenha desligado em produção
appDir base_path() Diretório raiz que o compilador pode tocar
cacheDir storage_path('framework/aop') (GOAOP_CACHE_DIR) Onde os fontes compilados e os proxies ficam em cache
cacheFileMode 0770 (GOAOP_CACHE_PERMISSIONS, dígitos octais, p. ex. "770") chmod dos arquivos de cache
parsedFilesLimit 100 (GOAOP_PARSED_FILES_LIMIT) Arquivos-fonte analisados (cerca de 0,2 MB cada) mantidos em memória durante a compilação; o padrão de aop:warmup --cached-files
includePaths [app_path()] Só estes diretórios são compilados
excludePaths [] Estes nunca são compilados
features 0 (GOAOP_FEATURES) Bitmask de flags de Go\Aop\Features: INTERCEPT_INCLUDES = 4, PREBUILT_CACHE = 64, PARTIAL_REFLECTION = 256
aspects [] Behavior classes a registrar

Behaviors em chamadas de função e na criação de objetos são guiados pelas suas matching rules e não precisam de flag. php artisan about mostra a localização atual do cache do framework e o modo debug.

Janela do terminal
php artisan aop:warmup

Sem um aquecimento, cada classe é compilada no seu primeiro carregamento. Rode aop:warmup no deploy para compilar todas de antemão; é o recomendado com debug desligado. O comando sai com status diferente de zero quando um arquivo não pode ser compilado, então um script de deploy para em vez de publicar um cache incompleto. Passe --fail-fast para parar no primeiro erro.

Janela do terminal
php artisan aop:warmup --workers=8
php artisan aop:warmup --cache-dir=/srv/app/releases/next/storage/framework/aop
php artisan aop:warmup --preload
  • --workers=N compila em processos worker paralelos. Cada worker é o seu próprio artisan, então ele faz o boot com o mesmo ambiente, a mesma configuração e as mesmas behavior classes.
  • --cache-dir=DIR gera o cache de uma nova release ao lado da que está rodando. O cache gerado assim é completo e independente de localização.
  • --preload grava um script opcache.preload: _preload.php no diretório de cache que está sendo gerado, ou o arquivo indicado em --preload=FILE.

Para entregar scripts compilados junto com uma imagem de container, pré-aqueça o opcache.file_cache depois do aquecimento e depois de php artisan optimize, na imagem final:

Janela do terminal
php artisan optimize
mkdir -p /var/cache/opcache && php -d opcache.enable_cli=1 -d opcache.file_cache_only=1 \
-d opcache.file_cache=/var/cache/opcache \
artisan aop:warmup-opcache --file-cache=/var/cache/opcache
Janela do terminal
composer install --no-dev --optimize-autoloader # runs package:discover, with an empty framework cache
php artisan optimize # the cached configuration carries GOAOP_FEATURES
php artisan aop:warmup

Com GOAOP_FEATURES=64 (PREBUILT_CACHE), uma requisição nunca compila. Uma classe abaixo dos include paths que falta no cache falha com uma WeavingException, então rode aop:warmup a cada deploy. Os comandos de cache do Laravel (package:discover, optimize, optimize:clear e os comandos de cache e de clear de config, event, route e view) não atendem requisições, então carregam as classes dos seus fontes originais. É por isso que a ordem acima funciona.

Depois que a configuração está em cache, env() não é mais lido. Rode optimize (ou config:cache) com o ambiente de produção, incluindo GOAOP_FEATURES. O checklist completo está em Produção e desempenho.

  • A compile step (etapa de compilação) começa no início da fase de boot. Classes carregadas antes disso (código de bootstrap muito inicial, o interior do register() de outros pacotes, os seus próprios service providers) não podem receber behaviors.
  • Só as classes abaixo de appDir e includePaths são consideradas. Código de vendor não é compilado.
  • Exclua os handlers de exceção com excludePaths: quando ocorre um erro fatal, um handler compilado pode não ser carregável a partir de um cache frio.

© 2026 Alexander Lisachenko