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/.
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; }}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().
Por que parece parte do Laravel
Seção intitulada “Por que parece parte do Laravel”- 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 ambienteGOAOP_*. - 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.aspectem 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:warmupgera o cache no deploy, em workers paralelos se você quiser. Ele se encaixa no deploy que você já roda, depois decomposer installephp artisan optimize.php artisan aboutmostra a localização do cache e o modo debug. - Sem etapa de build em desenvolvimento. Com
debugligado, uma classe alterada é compilada de novo na próxima requisição, e os breakpoints funcionam nos seus arquivos originais.
O que um behavior alcança e um decorator não
Seção intitulada “O que um behavior alcança e um decorator não”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
newse comportam do mesmo jeito. Type hints,instanceofe 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,
finale estáticos, e métodos de classesfinalereadonly(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 deApp\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.phpcomuns emstorage/framework/aop, então você pode lê-las (Pure PHP).
Requisitos
Seção intitulada “Requisitos”- PHP 8.4 ou mais novo
- Laravel 12 ou 13
goaop/framework^4.0 (behaviors declarados com atributos), instalado junto com a bridge
Instalação
Seção intitulada “Instalação”composer require goaop/goaop-laravel-bridgeO package discovery registra o service provider automaticamente. Publique a configuração se quiser alterá-la:
php artisan vendor:publish --tag=goaop-configSeu primeiro behavior
Seção intitulada “Seu primeiro behavior”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.
-
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 {} -
Escreva a behavior class. O
TransactionalBehaviordo 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. -
Registre a behavior class em
config/go_aop.php:config/go_aop.php 'aspects' => [App\Behaviors\TransactionalBehavior::class,], -
Marque um método com
#[Transactional]e chame-o. A próxima requisição o executa dentro de uma transação.
Behaviors por regra
Seção intitulada “Behaviors por regra”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:
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.
Registrando behavior classes
Seção intitulada “Registrando behavior classes”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:
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.
Configuração
Seção intitulada “Configuração”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.
Deploy: php artisan aop:warmup
Seção intitulada “Deploy: php artisan aop:warmup”php artisan aop:warmupSem 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.
php artisan aop:warmup --workers=8php artisan aop:warmup --cache-dir=/srv/app/releases/next/storage/framework/aopphp artisan aop:warmup --preload--workers=Ncompila em processos worker paralelos. Cada worker é o seu próprioartisan, então ele faz o boot com o mesmo ambiente, a mesma configuração e as mesmas behavior classes.--cache-dir=DIRgera o cache de uma nova release ao lado da que está rodando. O cache gerado assim é completo e independente de localização.--preloadgrava um scriptopcache.preload:_preload.phpno 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:
php artisan optimizemkdir -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/opcacheProdução com PREBUILT_CACHE
Seção intitulada “Produção com PREBUILT_CACHE”composer install --no-dev --optimize-autoloader # runs package:discover, with an empty framework cachephp artisan optimize # the cached configuration carries GOAOP_FEATURESphp artisan aop:warmupCom 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.
Ressalvas
Seção intitulada “Ressalvas”- 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
appDireincludePathssã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
