Ir al contenido
Documentación · Integraciones

Symfony

Integración con Symfony mediante goaop/goaop-symfony-bundle 4.0: behavior classes autoconfiguradas, un panel en el web profiler y precalentamiento de la caché.

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

El bundle goaop/goaop-symfony-bundle 4.0 adjunta behaviors (comportamientos) a tus servicios a medida que se cargan. No necesitas clases base ni decoradores.

namespace App\Aspect;
use Go\Aop\Aspect;
use Go\Aop\Intercept\MethodInvocation;
use Go\Lang\Attribute\Around;
use Psr\Log\LoggerInterface;
final class TimingAspect implements Aspect
{
public function __construct(private readonly LoggerInterface $logger) {}
#[Around('execution(public App\Service\**->*(*))')]
public function measure(MethodInvocation $invocation): mixed
{
$start = hrtime(true);
try {
return $invocation->proceed();
} finally {
$this->logger->info('{method} took {ms} ms', [
'method' => (string) $invocation,
'ms' => (hrtime(true) - $start) / 1e6,
]);
}
}
}

Esa es toda la integración. La clase implementa Go\Aop\Aspect, así que la autoconfiguración la registra como behavior class (clase de comportamiento), y el autowiring le da su logger. A partir de la siguiente petición, se mide el tiempo de cada método público de cada clase bajo App\Service.

  • PHP 8.4 o posterior
  • Symfony 7.4 u 8.x
  • goaop/framework ^4.0 (behaviors declarados con atributos)
Ventana de terminal
composer require goaop/goaop-symfony-bundle

Registra el bundle como primera entrada de config/bundles.php:

config/bundles.php
return [
Go\Symfony\GoAopBundle\GoAopBundle::class => ['all' => true],
Symfony\Bundle\FrameworkBundle\FrameworkBundle::class => ['all' => true],
// ...
];

El compile step (paso de compilación) solo se aplica a las clases cargadas después de inicializar el kernel, y los bundles arrancan en el orden en que se registran. El bundle lo hace cumplir: si no está el primero, la construcción del contenedor falla con un mensaje claro.

El archivo de configuración es opcional. Con los valores por defecto de abajo, el bundle compila el directorio src/ en el modo del kernel y activa la caché preconstruida en producción:

config/packages/go_aop.yaml
go_aop:
include_paths: ['%kernel.project_dir%/src']
when@prod:
go_aop:
features: [PREBUILT_CACHE]

bin/console config:dump-reference go_aop imprime la referencia completa. Todas las opciones, con sus valores por defecto:

config/packages/go_aop.yaml
go_aop:
# Development mode: changed sources and behavior classes are compiled again on the next request,
# breakpoints work in the original files. Keep it off in production.
debug: '%kernel.debug%'
# Application root: only files below it can be compiled, cache paths mirror source paths relative to it.
app_dir: '%kernel.project_dir%'
# Directory for generated sources, proxies and behavior caches. Anchor it on %kernel.cache_dir%
# or %kernel.build_dir% so that cache:clear and cache:warmup manage it.
cache_dir: '%kernel.cache_dir%/aop'
# Permissions of the cache files: an octal literal (0o770), an octal string ("0770") or an integer.
# Defaults to 0770 minus the umask.
cache_file_mode: ~
# Directories that are compiled. Keep the list narrow: compiling vendor code is slow and rarely needed.
include_paths: ['%kernel.project_dir%/src']
# Directories below the include paths that are never compiled (the cache directory and the
# framework itself are always excluded).
exclude_paths: []
# Number of parsed source files the compiler keeps in memory (about 0.2 MB each).
parsed_files_limit: 100
# Framework features, by the name of the Go\Aop\Features constant:
# PREBUILT_CACHE trust the deployed cache completely, never check or write it at runtime
# INTERCEPT_INCLUDES route include/require in compiled files through the compiler (legacy code)
# PARTIAL_REFLECTION compile classes whose parent class, interface or trait Composer can not
# locate, with their own members
features: []
# Kernel class; extend Go\Symfony\GoAopBundle\Kernel\AspectSymfonyKernel to customize
# the transformation pipeline.
kernel_class: Go\Symfony\GoAopBundle\Kernel\AspectSymfonyKernel
# Compile every file below the include paths during cache:warmup and cache:clear.
cache_warmer: true
# Doctrine ORM integration, enabled automatically when DoctrineBundle is registered.
doctrine: ~

Las variables de entorno funcionan como en el resto de Symfony, por ejemplo debug: '%env(bool:GOAOP_DEBUG)%'. Las matching rules (reglas de coincidencia) de funciones e initialization() no necesitan ningún flag de funcionalidad: activan su maquinaria por sí mismas.

Una behavior class es un servicio con autowiring normal. La autoconfiguración registra cada servicio que implementa Go\Aop\Aspect. Sin autoconfiguración, etiqueta el servicio con goaop.aspect:

services:
Acme\Audit\AuditAspect:
tags: [goaop.aspect]

Una behavior class es un singleton: registrarla como dos servicios es un error de compilación del contenedor.

El compilador solo necesita las behavior classes. El contenedor de Symfony crea una behavior class cuando uno de sus behaviors se ejecuta por primera vez, nunca durante el compile step ni durante el precalentamiento de la caché. El contenedor del kernel (AspectContainer) también delega en el contenedor de Symfony, así que $aspectContainer->get(LoggerInterface::class) funciona. Go\Core\AspectKernel y Go\Core\AspectContainer son servicios con autowiring, y goaop.aspect_kernel es público.

Comprueba qué selecciona una behavior class antes de confiar en ella:

Ventana de terminal
bin/console debug:aspect # behavior classes with their rules and behaviors
bin/console debug:advisor --advisor='App\Aspect\TimingAspect->measure' # the methods one behavior matches

En modo debug, las clases bajo las include paths se compilan en su primera carga, y se vuelven a compilar cuando cambia su código fuente o una behavior class.

Con symfony/web-profiler-bundle instalado, la barra de herramientas muestra el número de behavior classes. El panel Go! AOP lista:

  • las behavior classes con sus advisors, sus atributos de behavior y sus matching rules;
  • las clases compiladas cargadas durante la petición, con sus archivos proxy;
  • las clases bajo las include paths que se cargaron antes de inicializar el kernel (el panel se pone amarillo);
  • la configuración efectiva del kernel.

La tercera lista es el diagnóstico para un bundle que arranca antes que GoAopBundle, y para la petición que reconstruyó el contenedor. Esa petición tiene que cargar las clases de los servicios antes de que arranque el bundle, así que las ejecuta una vez sin sus behaviors. La petición siguiente se ejecuta completamente compilada. Los despliegues no se ven afectados, porque cache:clear y cache:warmup construyen juntos el contenedor y la caché del framework.

El bundle también desactiva el .container.dumper.inline_class_loader de Symfony, salvo que tu configuración lo establezca. Esa opción incluye directamente los archivos de los servicios, lo que se salta el class loader y, con él, el compile step.

Ventana de terminal
composer install --no-dev --optimize-autoloader # runs cache:clear through the auto-scripts
# or explicitly
bin/console cache:clear
bin/console cache:warmup

cache:clear y cache:warmup compilan toda la aplicación mediante un cache warmer. cache:clear construye la nueva caché junto a la que está en uso y después la renombra. El warmer construye la caché del framework en ese nuevo directorio, desde cero, así que tus pasos de despliegue habituales no necesitan cambios. El precalentamiento falla cuando un archivo no se puede compilar, de modo que el despliegue se detiene en lugar de publicar una caché incompleta. Ejecuta cache:warmup:aop --fail-fast -vvv para ver el archivo y el error.

Los comandos del framework se registran en la consola de tu aplicación. Trabajan sobre el kernel en ejecución, así que omites el argumento con el archivo de carga de vendor/bin/aspect.

Comando Propósito
cache:warmup:aop [--fail-fast] [--cache-dir=DIR] [--cached-files=N] [--preload[=FILE]] Compila en la caché cada archivo bajo las include paths. Falla cuando un archivo no se puede compilar. --preload escribe además el script opcache.preload de la caché.
cache:warmup:opcache [--file-cache=DIR] [--entry=FILE] Puebla la caché de archivos de OPcache (opcache.file_cache) con la caché del framework y la aplicación. Ejecútalo en la imagen final.
debug:aspect [--aspect=FQCN] Lista las behavior classes con sus matching rules y sus advisors.
debug:advisor [--advisor=ID] Lista los advisors; con --advisor, lo que selecciona ese advisor.
debug:weaving [-v] Compila la aplicación dos veces e informa de los proxies que difieren, lo que señala una behavior class no determinista.

Aquí cache:warmup:aop --workers=N compila en un solo proceso: sus procesos worker arrancarían el kernel con un archivo de carga, y la consola de la aplicación no tiene ninguno.

config/packages/go_aop.yaml
when@prod:
go_aop:
features: [PREBUILT_CACHE]

Con PREBUILT_CACHE, el entorno de ejecución se salta todas las comprobaciones del sistema de archivos relacionadas con la caché y nunca compila ni escribe en el directorio de la caché. Una clase bajo las include paths que la caché no conoce falla con una WeavingException (“… is missing from the prebuilt AOP cache …”). Reconstruye la caché en cada despliegue. Es el ajuste recomendado para producción, y es lo que hace funcionar los sistemas de archivos de solo lectura y las imágenes inmutables.

Si tu kernel.build_dir es distinto de kernel.cache_dir, ancla la caché del framework en el directorio que construyes en el despliegue: cache_dir: '%kernel.build_dir%/aop'.

Para el preloading de OPcache, haz require del script de preload de la caché del framework antes que del archivo de preload del contenedor:

config/preload.php
if (is_file($aop = dirname(__DIR__).'/var/cache/prod/aop/_preload.php')) {
require $aop;
}
if (is_file($container = dirname(__DIR__).'/var/cache/prod/App_KernelProdContainer.preload.php')) {
require $container;
}

En modo producción, el cache warmer escribe _preload.php en el directorio de la caché del framework. Adapta su ruta cuando cache_dir no sea %kernel.cache_dir%/aop. No arranques el kernel en config/preload.php: falla con “Cannot redeclare class”. Más sobre las builds de producción: Producción y rendimiento.

Cuando DoctrineBundle está registrado, o cuando configuras doctrine: true, el bundle:

  • sustituye el escaneo de directorios de cada driver de atributos del ORM por Go\Bridge\Doctrine\WovenEntityClassLocator, que carga las entidades a través del class loader, de modo que conservan sus behaviors;
  • registra Go\Bridge\Doctrine\MetadataLoadInterceptor como listener de loadClassMetadata, que, al cargar los metadatos, informa de una propiedad de entidad interceptada cuando los lazy objects nativos están desactivados.

Las entidades deben estar bajo una include path para compilarse. Sus behaviors se aplican entonces tanto si las crea tu código como si las hidrata el ORM. La página de Doctrine ORM explica ambas clases.

  • Un behavior no se aplica. Ejecuta primero debug:advisor --advisor=...: lista lo que selecciona una matching rule. Después comprueba que la clase está bajo una include path y que no se carga antes de que arranque el bundle (panel del profiler, classes loaded before weaving). El código de vendor solo se compila cuando su directorio es una include path.

  • “Class … is missing from the prebuilt AOP cache”. El despliegue publicó código para el que no se construyó la caché. Ejecuta bin/console cache:clear (o cache:warmup) una vez que el código esté en su sitio.

  • “Circular reference detected for the aspect …”. Crear una de las dependencias de la behavior class ejecuta un behavior de esa misma clase. Inyecta la dependencia de forma lazy, o acota la matching rule:

    public function __construct(
    #[Autowire(lazy: true)] private readonly Wallet $wallet, // or #[AutowireServiceClosure(Wallet::class)], a service locator
    ) {}
  • “Class … was not found by locator”. Una clase bajo las include paths extiende código que Composer no puede localizar, como una clase base generada. Haz que Composer pueda localizarla, activa PARTIAL_REFLECTION, o excluye las clases dependientes con exclude_paths.

  • Manejadores de excepciones. Excluye mediante exclude_paths las clases que deben cargarse cuando todo lo demás ha fallado (manejadores de errores, el kernel).

© 2026 Alexander Lisachenko