Ir al contenido
Documentación · Integraciones

Laravel

Middleware para cualquier método, no solo para rutas. goaop/goaop-laravel-bridge 2.0 adjunta behaviors a tus clases, y el contenedor, la configuración y Artisan de Laravel hacen el resto.

Traducido del inglés. La página en inglés es la referencia. Leer el original

El middleware es una de las mejores ideas de Laravel. Una petición atraviesa una pila de clases pequeñas, y cada una añade una sola cosa (autenticación, limitación de peticiones, una sesión) sin tocar tu controlador. El bridge goaop/goaop-laravel-bridge 2.0 lleva esa idea a cada método y cada propiedad de tu aplicación, sean públicos, protegidos o privados. Escribes un behavior (comportamiento) una sola vez, indicas dónde se aplica, y se ejecuta alrededor de esas llamadas como middleware dinámico: en servicios, actions, jobs y cualquier otra clase de 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());
}
}

Ese es todo el patrón. Si has escrito alguna vez el handle($request, $next) de un middleware, ya lo conoces: $invocation->proceed() es tu $next($request). Cada método marcado con #[Transactional] hace ahora commit o rollback como una unidad, y OrderService sigue conteniendo solo la lógica de negocio. No necesitas una clase base, una interfaz, un decorador ni una llamada a app()->extend().

  • Se instala como cualquier otro paquete. composer require, y el package discovery registra el service provider. Un único archivo de configuración publicable, config/go_aop.php, con overrides GOAOP_* desde el entorno.
  • Las behavior classes (clases de comportamiento) son servicios del contenedor. El contenedor de Laravel construye cada behavior class la primera vez que se ejecuta uno de sus behaviors. La inyección por constructor funciona, igual que las facades, config() y cualquier servicio que registre tu aplicación.
  • Regístralas donde registras todo lo demás. Pon una clase en la lista de la configuración, o etiqueta un servicio con goaop.aspect en un service provider, para que un paquete pueda aportar sus propios behaviors.
  • Artisan se encarga del trabajo de producción. php artisan aop:warmup construye la caché en el despliegue, con workers en paralelo si quieres. Encaja en el despliegue que ya ejecutas, después de composer install y php artisan optimize. php artisan about muestra la ubicación de la caché y el modo debug.
  • Sin paso de build en desarrollo. Con debug activado, una clase modificada se vuelve a compilar en la siguiente petición, y los breakpoints funcionan en tus archivos originales.

Lo que un behavior alcanza y un decorador no

Sección titulada «Lo que un behavior alcanza y un decorador no»

Un decorador envuelve un objeto que resuelves desde el contenedor, así que solo ve los métodos públicos, y solo por ese camino. Un behavior se adjunta a la propia clase mientras se carga, así que:

  • Lo recibe cada instancia. Los objetos del contenedor y los que creas con new se comportan igual. Los type hints, instanceof y el nombre de la clase no cambian, porque no existe ningún objeto envoltorio.
  • Vale cualquier tipo de método. Métodos privados, protegidos, final y estáticos, y métodos de clases final y readonly (Intercept anything).
  • También las propiedades. Lecturas y escrituras de propiedades públicas, protegidas y privadas, incluidas las promovidas en el constructor, mediante property hooks nativos de PHP 8.4: access(private App\Domain\Order->status) o @access(App\Attributes\Audited) (Behaviors en propiedades).
  • Una regla puede cubrir un namespace. execution(public App\Services\**->*(*)) selecciona cada método público bajo App\Services, incluidas las clases que añadas el mes que viene (Matching rules).
  • El coste es pequeño. Los métodos y propiedades sin behaviors no cuestan nada extra. Un método o una propiedad con un behavior paga menos de 1 µs por llamada (costes medidos).
  • Es PHP normal. Sin extensión PECL y sin eval(). Las clases compiladas son archivos .php corrientes en storage/framework/aop, así que puedes leerlas (Pure PHP).
  • PHP 8.4 o posterior
  • Laravel 12 o 13
  • goaop/framework ^4.0 (behaviors declarados con atributos), que se instala con el bridge
Ventana de terminal
composer require goaop/goaop-laravel-bridge

El package discovery registra el service provider automáticamente. Publica la configuración si quieres cambiarla:

Ventana de terminal
php artisan vendor:publish --tag=goaop-config

Una behavior class (un aspect (aspecto), en la API) es una clase normal que implementa Go\Aop\Aspect. Cada uno de sus métodos públicos con #[Before], #[After], #[Around] o #[AfterThrowing] es un behavior, y la cadena de ese atributo es su matching rule (regla de coincidencia; un pointcut (punto de corte), en la API): indica dónde se ejecuta el behavior.

  1. Crea un atributo para marcar los métodos, o sáltate este paso y selecciona los métodos por nombre (consulta la sección siguiente).

    app/Attributes/Transactional.php
    namespace App\Attributes;
    use Attribute;
    #[Attribute(Attribute::TARGET_METHOD)]
    final class Transactional {}
  2. Escribe la behavior class. El TransactionalBehavior del principio de esta página está completo. #[Around] ejecuta el behavior en lugar del método, y @execution(App\Attributes\Transactional) selecciona cada método que lleva el atributo.

  3. Registra la behavior class en config/go_aop.php:

    config/go_aop.php
    'aspects' => [
    App\Behaviors\TransactionalBehavior::class,
    ],
  4. Marca un método con #[Transactional] y llámalo. La siguiente petición lo ejecuta dentro de una transacción.

Un behavior no necesita un atributo en el destino. Una matching rule puede seleccionar métodos por nombre, namespace o visibilidad, de modo que toda una capa de la aplicación recibe el behavior sin ningún cambio en sus clases:

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() se ejecuta antes de cada método público bajo App\Services. measureCharge() envuelve un método y mide su tiempo, también cuando lanza una excepción. Los cuatro atributos, el call context (contexto de llamada) ($invocation) y la sintaxis completa de las reglas están en Behaviors y matching rules. Para recorridos completos, consulta el behavior de caché y el behavior de logging.

Nunca entregas tú las behavior classes al motor. Durante la fase de arranque, después de que todos los service providers se hayan registrado y antes de que se ejecute el código de tu aplicación, el bridge las recoge de dos fuentes.

La lista de la configuración. Pon la clase en config/go_aop.php, como en los pasos de arriba. Una clase de la lista se registra en cuanto arranca el kernel, sin cargar la clase. El contenedor de Laravel la resuelve en la primera llamada a uno de sus behaviors, así que una behavior class puede depender de servicios que solo existen una vez que la aplicación ha arrancado por completo. Una petición que no ejecuta ninguno de sus behaviors nunca la crea.

La etiqueta goaop.aspect. Etiqueta un servicio en uno de tus 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');

Usa la etiqueta cuando una behavior class necesite una construcción no trivial, o cuando un paquete aporte behavior classes sin tocar tu configuración. Los servicios etiquetados se resuelven cuando arranca el provider del bridge, porque en Laravel una etiqueta solo se puede enumerar resolviendo sus servicios. Para las behavior classes con constructores pesados o que dependen del arranque, prefiere la lista de la configuración.

Puedes combinar ambas fuentes; los duplicados se registran una sola vez. Una clase descubierta que no implementa Go\Aop\Aspect falla con una excepción descriptiva. El contenedor de Laravel se conecta al contenedor del kernel como su delegado PSR-11, así que los behaviors y las factorías de las behavior classes pueden obtener a través de él los servicios de la aplicación.

Opciones principales de config/go_aop.php. Cada una se puede sobrescribir desde el entorno.

Opción Valor por defecto Propósito
debug GOAOP_DEBUG → APP_DEBUG Volver a compilar cuando cambian los fuentes, con breakpoints en los archivos originales; mantenlo desactivado en producción
appDir base_path() Directorio raíz que el compilador puede tocar
cacheDir storage_path('framework/aop') (GOAOP_CACHE_DIR) Dónde se cachean los fuentes compilados y los proxies
cacheFileMode 0770 (GOAOP_CACHE_PERMISSIONS, dígitos octales, p. ej. "770") chmod de los archivos de la caché
parsedFilesLimit 100 (GOAOP_PARSED_FILES_LIMIT) Archivos fuente analizados (unos 0.2 MB cada uno) que se mantienen en memoria durante la compilación; el valor por defecto de aop:warmup --cached-files
includePaths [app_path()] Solo se compilan estos directorios
excludePaths [] Nunca se compilan estos
features 0 (GOAOP_FEATURES) Máscara de bits de flags de Go\Aop\Features: INTERCEPT_INCLUDES = 4, PREBUILT_CACHE = 64, PARTIAL_REFLECTION = 256
aspects [] Behavior classes que se registran

Los behaviors sobre llamadas a funciones y sobre la creación de objetos se activan por sus matching rules y no necesitan ningún flag. php artisan about muestra la ubicación actual de la caché del framework y el modo debug.

Ventana de terminal
php artisan aop:warmup

Sin precalentamiento, cada clase se compila en su primera carga. Ejecuta aop:warmup en el despliegue para compilarlas todas por adelantado; se recomienda con debug desactivado. El comando termina con un código distinto de cero cuando un archivo no se puede compilar, para que un script de despliegue se detenga en lugar de publicar una caché incompleta. Pasa --fail-fast para detenerte en el primer error.

Ventana de 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 en procesos worker en paralelo. Cada worker es tu propio artisan, así que arranca con el mismo entorno, la misma configuración y las mismas behavior classes.
  • --cache-dir=DIR construye la caché de una nueva release junto a la que está en ejecución. La caché construida así es completa e independiente de la ubicación.
  • --preload escribe un script opcache.preload: _preload.php en el directorio de la caché que se está construyendo, o el archivo indicado con --preload=FILE.

Para distribuir scripts compilados con una imagen de contenedor, puebla opcache.file_cache después del precalentamiento y de php artisan optimize, en la imagen final:

Ventana de 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
Ventana de 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

Con GOAOP_FEATURES=64 (PREBUILT_CACHE), una petición nunca compila. Una clase bajo las include paths que falta en la caché falla con una WeavingException, así que ejecuta aop:warmup en cada despliegue. Los comandos de caché de Laravel (package:discover, optimize, optimize:clear y los comandos de cache y clear de config, event, route y view) no sirven ninguna petición, así que cargan las clases desde su código fuente original. Por eso funciona el orden de arriba.

Una vez cacheada la configuración, env() ya no se lee. Ejecuta optimize (o config:cache) con el entorno de producción, GOAOP_FEATURES incluido. La lista de comprobación completa está en Producción y rendimiento.

  • El compile step (paso de compilación) empieza al principio de la fase de arranque. Las clases cargadas antes (código de bootstrap muy temprano, el interior de los register() de otros paquetes, tus propios service providers) no pueden recibir behaviors.
  • Solo se tienen en cuenta las clases bajo appDir e includePaths. El código de vendor no se compila.
  • Excluye los manejadores de excepciones mediante excludePaths: cuando se produce un error fatal, puede que un manejador compilado no se pueda cargar desde una caché cold (fría).

© 2026 Alexander Lisachenko