Ir al contenido
Documentación

Configuración y CLI

Configura el kernel, elige los feature flags, proporciona a las behavior classes sus dependencias desde el contenedor de tu aplicación y usa la consola.

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

Todo lo que el framework necesita saber de tu aplicación pasa por una sola llamada: init() en tu kernel. Esta página enumera todas las opciones que acepta el kernel, los feature flags, cómo obtienen las behavior classes (clases de comportamiento) sus dependencias del contenedor de tu aplicación y la consola vendor/bin/aspect con la que construyes e inspeccionas la caché.

Tu kernel extiende Go\Core\AspectKernel y registra las behavior classes (aspects (aspectos), en la API; consulta la tabla de términos) en configureAop():

app/ApplicationAspectKernel.php
use Aspect\MonitorAspect;
use Go\Core\AspectContainer;
use Go\Core\AspectKernel;
class ApplicationAspectKernel extends AspectKernel
{
protected function configureAop(AspectContainer $container): void
{
// Deferred (recommended): constructed on first use
$container->addLazyService(MonitorAspect::class, static fn() => new MonitorAspect());
// Eager alternative: $container->add(MonitorAspect::class, new MonitorAspect());
}
}

Lo inicializas una sola vez, normalmente en el controlador frontal, justo después del autoloader de Composer:

public/index.php
include __DIR__ . '/../vendor/autoload.php';
ApplicationAspectKernel::getInstance()->init([
'debug' => false,
'appDir' => __DIR__ . '/..',
'cacheDir' => __DIR__ . '/../var/cache/aop',
'includePaths' => [__DIR__ . '/../src'],
]);

Solo se aceptan las opciones de abajo. Una clave desconocida, un containerClass desconocido o un bit de feature desconocido lanzan Go\Aop\Exception\InvalidConfigurationException, así que una errata falla al arrancar en lugar de pasar inadvertida.

Opción Tipo Por defecto Para qué sirve
cacheDir string ninguno, obligatoria Directorio de los fuentes compilados, los proxies, las cachés de advisors y el class map.
appDir string el directorio que contiene vendor/ Raíz de la aplicación. Las rutas de la caché reflejan las rutas de los fuentes relativas a ella, y solo se compilan los archivos que están por debajo.
debug bool false Modo de desarrollo: los cambios en el archivo del kernel y en los archivos de behavior classes invalidan la caché, y cada clase e include se carga a través del stream filter del framework que compila. Con false, las clases compiladas se cargan desde la caché a través del class map de Composer. Usa false en producción.
includePaths string[] [] (todo lo que hay por debajo de appDir) Los directorios que se compilan. Mantenlo acotado: compilar el código de vendor es lento y rara vez hace falta.
excludePaths string[] [] Los directorios que nunca se compilan. El directorio de caché, el propio framework y sus dependencias de ejecución (goaop/dissect, goaop/parser-reflection, nikic/php-parser, psr/container, symfony/finder) siempre se excluyen.
features int 0 Máscara de bits de los flags de Go\Aop\Features; consulta la sección siguiente.
cacheFileMode int 0770 menos la umask Permisos de los archivos de caché. Debe estar entre 0600 y 0777 y dar al propietario acceso de lectura y escritura; los directorios reciben los bits de búsqueda correspondientes.
containerClass class-string Go\Core\Container Implementación del contenedor del kernel. Debe implementar Go\Core\AspectContainer (un ContainerInterface de PSR-11).
parsedFilesLimit int 100 Número de archivos fuente analizados (árboles sintácticos, unos 0.2 MB cada uno) que goaop/parser-reflection mantiene en memoria al compilar. Debe ser un entero positivo: con más, vuelve a analizar menos; con menos, usa menos memoria. Sustituye a un límite fijado con ReflectionEngine::setMaximumCachedFiles() antes de init(), y es el valor por defecto de cache:warmup:aop --cached-files.

Los feature flags son constantes de la clase final Go\Aop\Features. Combínalos con |:

public/index.php
use Go\Aop\Features;
ApplicationAspectKernel::getInstance()->init([
'debug' => false,
'appDir' => __DIR__ . '/..',
'cacheDir' => __DIR__ . '/../var/cache/aop',
'includePaths' => [__DIR__ . '/../src'],
'features' => Features::INTERCEPT_INCLUDES | Features::PREBUILT_CACHE,
]);

Features::ALL combina todos los flags. AspectKernel::hasFeature() te dice si un flag está activo y lanza una excepción si el flag es desconocido.

Flag Úsalo cuando
INTERCEPT_INCLUDES Tu aplicación carga código con include/require en lugar de con Composer.
PREBUILT_CACHE Construyes la caché en el despliegue y quieres que las peticiones confíen plenamente en ella. El ajuste de producción.
PARTIAL_REFLECTION Una clase que quieres compilar extiende o implementa algo que el framework no puede localizar.

Hace pasar por el compilador los include y require de los archivos compilados. Úsalo con código legacy que no carga Composer.

Confía plenamente en la caché construida en el despliegue. El kernel se salta las comprobaciones del directorio de caché y de permisos de escritura, las comparaciones de filemtime de los fuentes, las comprobaciones de recursos rastreados y las de vigencia de la caché de advisors. Una petición nunca compila ni escribe en el directorio de caché, así que funciona en sistemas de archivos de solo lectura.

La otra cara: la caché debe estar completa. Los archivos que el compilador nunca toma (fuera de las include paths, excluidos, que no son .php, por ejemplo una plantilla incluida) se cargan tal cual. Todo lo demás que esté bajo las include paths debe tener un registro en la caché.

cache:warmup:aop no confía en la caché que construye. Si se ejecuta sobre un directorio existente, vuelve a compilar cada archivo cuyo fuente haya cambiado (tamaño o fecha de modificación). Su archivo de carga puede cargar clases que la caché todavía no conoce antes de que empiece el build: ahí se cargan sin compilar, y el build las compila.

Compila una clase cuya clase padre, interfaz o trait no se puede localizar: una declarada por código generado en tiempo de ejecución, por un class_alias() o en un archivo fuera del autoloader de Composer. La clase se compara y se compila con sus propios métodos y propiedades y con los de sus ancestros disponibles. Los miembros heredados de un ancestro que falta no se interceptan.

Sin el flag, esa clase no compila. Actívalo cuando te encuentres con ese fallo.

Las reglas de funciones y de inicialización no necesitan flag

Sección titulada «Las reglas de funciones y de inicialización no necesitan flag»

El framework activa la maquinaria para estas matching rules (reglas de coincidencia) a partir de las behavior classes registradas, incluidas las registradas de forma lazy. No tienes que poner nada en features:

  • Una regla execution(Namespace\function(*)) añade proxies de funciones a los namespaces que coinciden.
  • Una regla initialization(...) activa la reescritura de las expresiones new Foo(...) en los archivos compilados. Mientras haya una registrada, cada new reescrito pasa por el interceptor, así que limita esas reglas al código que las necesita.

La sintaxis de las matching rules está en Behaviors y matching rules.

Behavior classes desde el contenedor de la aplicación

Sección titulada «Behavior classes desde el contenedor de la aplicación»

El contenedor del kernel es un contenedor PSR-11 (Go\Core\AspectContainer extiende Psr\Container\ContainerInterface). Puede delegar en el contenedor de tu aplicación: Symfony, Laravel, PHP-DI o cualquier otro contenedor PSR-11. get(), getService() y has() recurren al delegado para los ids que no están registrados en el contenedor del kernel.

El kernel se inicializa antes de que la aplicación construya su contenedor. Así que registras las behavior classes como siempre y dejas que resuelvan sus dependencias de forma lazy:

app/ApplicationAspectKernel.php
protected function configureAop(AspectContainer $container): void
{
// Runs when one of its behaviors first runs, after the application container is attached
$container->addLazyService(
MonitorAspect::class,
static fn(AspectContainer $container) => new MonitorAspect($container->getService(LoggerInterface::class)),
);
// or take the whole behavior class from the application container, by the id it has there
// $container->addLazyService(MonitorAspect::class, static fn(AspectContainer $c) => $c->get('app.monitor_aspect'));
}

En cuanto existe el contenedor de la aplicación, por ejemplo justo después de que arranque el kernel de tu framework, conéctalo:

ApplicationAspectKernel::getInstance()->getContainer()->setDelegate($psrContainer);

El compile step (paso de compilación) y el precalentamiento de la caché solo necesitan la behavior class en sí. Se ejecutan antes de setDelegate(), también en vendor/bin/aspect, y nunca crean una instancia de ella. La factoría se ejecuta cuando uno de sus behaviors (comportamientos) se ejecuta por primera vez; una dependencia que en ese momento siga faltando lanza ServiceNotFoundException.

Los bridges de Symfony, Laravel y Yii 3 se tratan en Integraciones.

Reglas para las factorías de behavior classes

Sección titulada «Reglas para las factorías de behavior classes»
  • Una factoría nunca pide al contenedor del kernel su propio id. Ese id se resuelve en la behavior class que se está construyendo. Toma la instancia del contenedor de la aplicación por el id que tiene allí, o constrúyela a partir de sus dependencias.
  • Las behavior classes nunca se descubren en el delegado. Un contenedor PSR-11 no se puede introspeccionar: no hay una forma estándar de buscar servicios por interfaz o por etiqueta. Toda behavior class se registra en configureAop(). Un bridge para un framework concreto puede recopilar servicios por etiqueta o interfaz de su propio contenedor y registrarlos con addLazyService().
  • El compile step nunca crea una instancia de una behavior class. Lee la behavior class, y el código generado se refiere a cada behavior por el nombre de la clase y del método. Toda behavior class, también una sin propiedades de instancia (que PHP no puede hacer lazy), la crea su factoría cuando uno de sus behaviors se ejecuta por primera vez, una vez conectado el contenedor de la aplicación.
  • Crear una behavior class no debe ejecutar uno de sus propios behaviors. Si la behavior class depende de un servicio cuya construcción intercepta uno de sus behaviors (el constructor del servicio, o un método al que llama el constructor), ese behavior se ejecutaría sobre una instancia que todavía no existe. El interceptor lo notifica con una AspectCircularReferenceException que nombra la behavior class, la llamada interceptada y las llamadas desde la creación hasta el behavior. Inyecta la dependencia de forma lazy (un servicio lazy, un closure o un service locator), o acota la matching rule para que la behavior class no intercepte la creación de sus propias dependencias.

Para sustituir el contenedor del kernel, pasa tu clase como containerClass. Debe implementar Go\Core\AspectContainer, es decir, los get() y has() de PSR-11 y además setDelegate(). Un id desconocido lanza ServiceNotFoundException, que implementa Psr\Container\NotFoundExceptionInterface.

La opción debug alterna entre dos modos. Tus behavior classes y matching rules son las mismas en ambos.

'debug' => true 'debug' => false
Carga de clases Cada clase e include pasa por el stream filter que compila. Las clases compiladas salen de la caché a través del class map de Composer.
Cambios en un fuente, una behavior class o el archivo del kernel Se vuelve a compilar en la siguiente petición. La caché se sirve tal cual.
Reconstrucción de la caché No hace falta. En cada despliegue, con cache:warmup:aop.
Para qué usarlo Desarrollo local. Producción. Añade Features::PREBUILT_CACHE.

En desarrollo no hay paso de build: edita una clase o un behavior, recarga, y el framework vuelve a compilar lo que ha cambiado. Los breakpoints funcionan en tu código original.

En producción, el framework entrega a Composer el class map de la caché, y el parser y los transformadores no se cargan en las peticiones warm (templadas). Si además activas PREBUILT_CACHE, una petición se salta también todas las comprobaciones de archivos fuente y de vigencia de la caché. Cómo afinarlo más (OPcache, preloading, contenedores) está en Producción y rendimiento.

cacheDir es la única opción obligatoria. El directorio contiene:

  • los fuentes compilados: el cuerpo original de cada clase como trait <Class>OriginalTrait, en la ruta relativa de su archivo fuente;
  • los proxies, junto a los fuentes compilados, con el nombre original de la clase;
  • las cachés de advisors de tus behavior classes, como archivos PHP normales junto a los fuentes compilados;
  • los metadatos, incluido _include.cache, el class map que se entrega a Composer;
  • _preload.php, cuando construyes la caché con cache:warmup:aop --preload.

Conviene saber:

  • Refleja appDir. Las rutas de la caché son relativas a la raíz de la aplicación, y las rutas dentro de los metadatos se guardan relativas a __DIR__, así que la caché sigue siendo válida si el directorio de la aplicación se mueve.
  • Nunca se compila. El directorio de caché siempre se excluye, pongas lo que pongas en excludePaths.
  • Los permisos vienen de cacheFileMode. El valor por defecto es 0770 menos la umask. Construye la caché como el usuario que sirve las peticiones, o para él.
  • Bórralo al actualizar desde 3.x. No se reutiliza ningún archivo de caché de 3.x, y con PREBUILT_CACHE una caché construida por otra versión del framework se rechaza.
Ventana de terminal
vendor/bin/aspect cache:warmup:aop public/index.php

vendor/bin/aspect necesita symfony/console (^7.4 || ^8.0). Instálalo con Composer si tu aplicación todavía no lo tiene.

Todos los comandos reciben la ruta del archivo que inicializa tu kernel, normalmente el controlador frontal o un archivo de bootstrap. Ese archivo se ejecuta, así que el comando ve el kernel con las mismas opciones que tu aplicación. Dentro de una aplicación que ya ha inicializado su kernel (la consola de una integración con un framework, donde los comandos se registran como servicios), omites el argumento: los comandos usan el kernel del proceso.

Todos los comandos devuelven Command::SUCCESS o Command::FAILURE. Comprueba el código de salida en tus scripts.

Comando Para qué sirve
cache:warmup:aop Compila en la caché todos los archivos bajo las include paths.
cache:warmup:opcache Puebla opcache.file_cache con la caché del framework y lo que carga una petición.
debug:aspect Lista las behavior classes registradas y sus behaviors.
debug:advisor Lista los advisors (cada behavior con su matching rule), o las llamadas interceptadas que coinciden con un advisor.
debug:weaving Precalienta la caché dos veces e informa de los proxies que se generan de forma distinta.
Ventana de terminal
rm -rf var/cache/aop
vendor/bin/aspect cache:warmup:aop public/index.php --workers=8

El comando compila todos los archivos bajo includePaths (menos excludePaths) y escribe los archivos compilados, los proxies, las cachés de advisors y los metadatos. Muestra una barra de progreso. Informa en stderr de cada archivo que no se puede compilar y termina con un código distinto de cero, así que un script de despliegue o un docker build se detienen ahí en lugar de publicar una caché incompleta.

Opción Por defecto Para qué sirve
--workers=N 1 (compila en el proceso del comando) Compila en N procesos worker en paralelo. Usa el número de CPU.
--cached-files=N la opción del kernel parsedFilesLimit, 100 Número de archivos analizados que cada proceso mantiene en memoria.
--fail-fast desactivado Se detiene en el primer archivo que no se puede compilar.
--cache-dir=DIR el cacheDir del kernel Construye la caché en otro directorio, desde cero, mientras el kernel y los workers siguen usando el suyo.
--preload[=FILE] desactivado Escribe también el script opcache.preload de la caché: _preload.php en el directorio de caché, o FILE.
-v desactivado Imprime cada archivo en lugar de solo la barra de progreso.

Notas sobre las opciones:

  • --cache-dir es la forma en que un despliegue prepara la caché de la siguiente release junto a la que está en marcha y después la cambia de forma atómica, por ejemplo intercambiando un symlink. Una caché construida así está completa y no depende de su ubicación, también cuando la construye un kernel de producción con su propia caché warm: el compilador siempre lee los fuentes originales, nunca los archivos compilados que sirve Composer.
  • --preload en su forma sin valor debe ir después del argumento del archivo de carga; si no, toma ese archivo como valor. El script enlaza al arrancar PHP todas las clases compiladas y todas las clases sin transformar que conoce la caché; las clases con un behavior en la inicialización estática se dejan al autoloader. No contiene ninguna ruta absoluta y lista las clases de exactamente esta caché, así que lo reconstruyes junto con la caché. Cómo configurar el preloading se explica en Producción y rendimiento.
  • Sobre un directorio existente, el comando vuelve a compilar cada archivo cuyo fuente haya cambiado (tamaño o fecha de modificación) y conserva los demás, también con PREBUILT_CACHE. Empieza desde un directorio vacío cuando quieras que la caché contenga exactamente la release actual.
Ventana de terminal
vendor/bin/aspect cache:warmup:opcache public/index.php --file-cache=/var/cache/opcache --entry=public/index.php

Compila en opcache.file_cache lo que carga una petición de producción: la caché del framework, el class map y los archivos autocargados de Composer, los fuentes sin transformar, el archivo de carga y los puntos de entrada. Así, un nuevo proceso maestro de PHP-FPM o de CLI lee scripts compilados del disco en lugar de compilarlos.

Opción Para qué sirve
--file-cache=DIR El directorio de opcache.file_cache. Debe coincidir con el configurado.
--entry=FILE Un punto de entrada que compilar. Repítelo para varios archivos.

Los scripts compilados solo se escriben en disco desde un proceso arrancado con -d opcache.enable_cli=1 -d opcache.file_cache_only=1 -d opcache.file_cache=DIR. Si el comando se ejecuta sin ellos, imprime el comando exacto que hay que ejecutar.

La file cache pertenece al build de PHP y a las rutas absolutas de los archivos. Ejecuta el comando en la imagen final, después de cache:warmup:aop, con el binario de PHP que sirve las peticiones. La caché del framework, el archivo de carga y los puntos de entrada deben compilar, o el comando falla; los archivos del class map de Composer que no compilan se listan y se omiten.

Ventana de terminal
vendor/bin/aspect debug:aspect public/index.php

Lista las behavior classes registradas y sus behaviors. También acepta la opción --aspect=....

Ventana de terminal
vendor/bin/aspect debug:advisor public/index.php

Lista los advisors. Con --advisor=... muestra las llamadas interceptadas que coinciden con ese advisor, lo que te dice si tu matching rule selecciona los métodos que esperas.

Ventana de terminal
vendor/bin/aspect debug:weaving public/index.php

Precalienta la caché dos veces e informa de los proxies que se generan de forma distinta entre las dos ejecuciones. Una diferencia apunta a una behavior class no determinista.

Ventana de terminal
rm -rf var/cache/aop
vendor/bin/aspect cache:warmup:aop public/index.php --workers=8
  1. Vacía el directorio de caché.
  2. Precalienta la caché con cache:warmup:aop. El comando falla cuando un archivo no se puede compilar, así que el despliegue se detiene en lugar de publicar una caché incompleta. Los proyectos grandes compilan más rápido en paralelo con --workers.
  3. Ejecuta con 'debug' => false y Features::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,
]);

Reconstruye la caché cada vez que cambien el código, las behavior classes, las opciones del kernel o composer.lock. En la práctica, eso significa en cada despliegue. El modo de desarrollo no necesita reconstrucciones.

El ajuste de OPcache, el preloading, los flags del autoloader de Composer y la construcción de la caché dentro de una imagen Docker están en Producción y rendimiento. La actualización desde 3.x, incluido el cambio de formato de la caché, está en Limitaciones y actualización.

© 2026 Alexander Lisachenko