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é.
El kernel
Sección titulada «El kernel»Tu kernel extiende Go\Core\AspectKernel y registra las behavior classes (aspects (aspectos), en la API; consulta la tabla de términos) en configureAop():
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:
include __DIR__ . '/../vendor/autoload.php';
ApplicationAspectKernel::getInstance()->init([ 'debug' => false, 'appDir' => __DIR__ . '/..', 'cacheDir' => __DIR__ . '/../var/cache/aop', 'includePaths' => [__DIR__ . '/../src'],]);Opciones del kernel
Sección titulada «Opciones del kernel»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. |
Feature flags
Sección titulada «Feature flags»Los feature flags son constantes de la clase final Go\Aop\Features. Combínalos con |:
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. |
INTERCEPT_INCLUDES
Sección titulada «INTERCEPT_INCLUDES»Hace pasar por el compilador los include y require de los archivos compilados. Úsalo con código legacy que no carga Composer.
PREBUILT_CACHE
Sección titulada «PREBUILT_CACHE»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.
PARTIAL_REFLECTION
Sección titulada «PARTIAL_REFLECTION»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 expresionesnew Foo(...)en los archivos compilados. Mientras haya una registrada, cadanewreescrito 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:
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 conaddLazyService(). - 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
AspectCircularReferenceExceptionque 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.
Clase de contenedor propia
Sección titulada «Clase de contenedor propia»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.
Modo de desarrollo y de producción
Sección titulada «Modo de desarrollo y de producción»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.
El directorio de caché
Sección titulada «El directorio de caché»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é concache: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 es0770menos 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_CACHEuna caché construida por otra versión del framework se rechaza.
La consola
Sección titulada «La consola»vendor/bin/aspect cache:warmup:aop public/index.phpvendor/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. |
cache:warmup:aop
Sección titulada «cache:warmup:aop»rm -rf var/cache/aopvendor/bin/aspect cache:warmup:aop public/index.php --workers=8El 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-dires 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.--preloaden 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.
cache:warmup:opcache
Sección titulada «cache:warmup:opcache»vendor/bin/aspect cache:warmup:opcache public/index.php --file-cache=/var/cache/opcache --entry=public/index.phpCompila 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.
debug:aspect
Sección titulada «debug:aspect»vendor/bin/aspect debug:aspect public/index.phpLista las behavior classes registradas y sus behaviors. También acepta la opción --aspect=....
debug:advisor
Sección titulada «debug:advisor»vendor/bin/aspect debug:advisor public/index.phpLista 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.
debug:weaving
Sección titulada «debug:weaving»vendor/bin/aspect debug:weaving public/index.phpPrecalienta 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.
Fundamentos del despliegue
Sección titulada «Fundamentos del despliegue»rm -rf var/cache/aopvendor/bin/aspect cache:warmup:aop public/index.php --workers=8- Vacía el directorio de caché.
- 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. - Ejecuta con
'debug' => falseyFeatures::PREBUILT_CACHE.
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
