Ir al contenido
Documentación

Producción y rendimiento

Lo que cuesta el framework en tiempo de ejecución, y cómo construir, ajustar y desplegar la caché para que producción pague solo por las llamadas que tienen behaviors.

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

El framework compila tus clases con sus behaviors (comportamientos) una sola vez y guarda el resultado como archivos PHP normales. A partir de ahí esos archivos se sirven como cualquier otro código: OPcache los cachea, Composer los carga y en tiempo de petición no se ejecuta ningún parser, ni reflexión, ni eval(). Una petición de producción con la caché warm (templada) lee un archivo de metadatos, entrega las clases generadas a Composer y paga solo por las llamadas que realmente se interceptan. Los métodos y propiedades sin behaviors no cuestan nada.

Esta página da las cifras medidas, explica de dónde sale el coste y muestra cómo desplegar la caché: precalentamiento en el despliegue, OPcache, Composer, Docker y Kubernetes. Las opciones del kernel se describen en Configuración y CLI. Hay un resumen visual en la página de la funcionalidad Performance.

Todas las cifras de esta página proceden del docs/performance.md de goaop/framework en upstream. Se midieron en una sola máquina, así que léelas como proporciones entre modos. Las proporciones son lo que se traslada a otras máquinas.

  • Una pequeña aplicación de tienda: unos 250 archivos bajo las include paths (94 clases compiladas), 120 clases de bibliotecas fuera de ellas y 6 behavior classes (clases de comportamiento) con #[Before], #[Around], #[AfterThrowing] y behaviors de propiedad.
  • Una petición crea 50 pedidos. Eso supone ~2600 llamadas a métodos interceptadas y ~950 accesos a propiedades interceptados.
  • PHP 8.5.12 NTS, 4 CPU, OPcache en memoria compartida, opcache.jit=disable, opcache.file_update_protection=0.

El método completo está más abajo, en Reproducir los benchmarks.

Los tres estados de la caché:

  • hot (caliente): caché compilada presente, OPcache lleno. El estado estable de un worker de producción.
  • warm: caché compilada presente, OPcache vacío. Un PHP-FPM recién arrancado o un pod nuevo.
  • cold (fría): todavía no hay nada en caché. La primera petición compila cada clase que carga.
Modo hot warm Pico de memoria (hot)
debug => false + PREBUILT_CACHE 5.4 ms 59 ms 1.3 MB
debug => false 5.5 ms 62 ms 1.3 MB
debug => true 13.0 ms 63 ms 2.2 MB
La misma aplicación sin el framework (los behaviors no se ejecutan) 2.1 ms 36 ms 0.7 MB
  • ~3500 intercepciones con cuerpos de behavior reales (logging, consultas a la caché, temporizadores) añaden ~3.3 ms a la petición. Arrancar el kernel se lleva ~0.15 ms de ese tiempo.
  • Una llamada interceptada cuesta alrededor de un tercio de microsegundo, y cada behavior adicional sobre ella ~70 ns.
  • La caché completa se construye en menos de medio segundo con cache:warmup:aop. Una aplicación de 2000 archivos tarda 1.1 s con 4 workers.
  • Los contenedores arrancan en estado hot. Con una caché de archivos de OPcache poblada, la primera petición de un PHP-FPM nuevo tarda 19 ms en lugar de 71 ms. Si además se usa preloading, tarda 10 ms, lo mismo que la aplicación sin el framework (9 ms).

Estas cifras usan behaviors vacíos, así que miden solo el trabajo propio del framework: el call context (contexto de llamada), la cadena de interceptores y la llamada al método original.

Llamada Sobrecoste por llamada
Método o propiedad sin behavior en una clase compilada 0
Método con un #[Before] o #[Around] ~0.33 µs
Método con tres #[Around] ~0.48 µs
Método estático con un #[Around] ~0.34 µs
Lectura de propiedad con un #[Around] ~0.22 µs
Escritura de propiedad con un #[Around] ~0.26 µs

Un millón de llamadas interceptadas cuesta alrededor de un tercio de segundo. Una petición típica con unos cientos de intercepciones paga una fracción de milisegundo.

Cada proceso CLI arranca con OPcache vacío. Un opcache.file_cache poblado hace que los comandos de vida corta arranquen casi tan rápido como una petición web hot.

Tiempo de script por proceso OPcache desactivado OPcache activado (solo memoria) opcache.file_cache, poblado
PREBUILT_CACHE 33 ms 69 ms 21 ms
debug => false 30 ms 69 ms 22 ms
Sin el framework 19 ms 34 ms 10 ms

El proxy sobrescribe solo los miembros que tienen behaviors. Cualquier otro método o propiedad es tu código original y se ejecuta a toda velocidad: el sobrecoste es 0. Las clases que ninguna matching rule (regla de coincidencia) selecciona ni siquiera se compilan.

Cada método interceptado declara un call context estático:

static $__joinPoint = InterceptorInjector::forMethod(...)

El call context y su lista de interceptores se construyen en la primera llamada. Cada llamada posterior es un único $__joinPoint->__invoke($this, [$args]). Esa lista contiene first-class callables que apuntan directamente a los métodos de tus behavior classes, así que no hay búsqueda de behaviors, ni reflexión, ni __call().

El primer behavior de un método cuesta ~0.33 µs. Cada behavior adicional suma ~70 ns, así que tres behaviors #[Around] cuestan ~0.48 µs. Un método estático con un #[Around] cuesta ~0.34 µs.

La reflexión para los behaviors (getMethod(), getField()) se crea solo cuando un behavior la pide.

La intercepción de propiedades se compila a hooks get y set nativos de PHP 8.4 en el proxy. No hay magia de __get() o __set() ni reflexión por acceso. Una lectura de propiedad con un #[Around] cuesta ~0.22 µs; una escritura, ~0.26 µs.

Arrancar el kernel lleva ~0.15 ms en el benchmark. Los servicios del framework, los transformadores y tus behavior classes se registran como factorías, con una escritura en un array cada una. En el arranque no se autocarga, refleja ni crea nada, así que una petición warm nunca carga el parser, la gramática de las matching rules, el matcher de behaviors ni los transformadores.

  • El índice de la caché (CachePathManager) es el único servicio que se construye en init(), porque el autoloader lee el class map de inmediato.
  • Las behavior classes se crean en la primera llamada a uno de sus behaviors, como lazy objects nativos de PHP 8.4. Ni el compile step (paso de compilación) ni el precalentamiento de la caché crean nunca una behavior class; solo la leen.
  • Producción no activa ningún listener de registro. El modo debug vigila los cambios en los archivos de las behavior classes mediante un listener que resuelve los archivos a través de Composer sin cargar las clases.
  • La tabla de análisis de la gramática de las matching rules es PHP generado, y las reglas se analizan solo en su primer uso.

Una petición warm (caché compilada presente, OPcache vacío) tarda 59 ms con PREBUILT_CACHE frente a 36 ms de la aplicación sin el framework. Se acorta con un opcache.file_cache poblado y preloading; consulta Docker y Kubernetes.

Una petición cold compila cada clase que carga. Con una caché construida en el despliegue y PREBUILT_CACHE, una petición de producción nunca compila.

La compilación ocurre una vez, en el despliegue.

  • La caché de la aplicación del benchmark se construye en menos de medio segundo.
  • Una aplicación de 2047 archivos tardó 2.2 s con un worker y 1.1 s con 4 workers en 4 CPU.
  • Cada archivo analizado que se mantiene en memoria durante la compilación ocupa ~0.2 MB. La opción del kernel parsedFilesLimit (por defecto 100) limita cuántos se conservan.

Lo que mantiene rápida la compilación:

  • El camino de acierto de la caché no analiza nada. Un registro vigente se sirve como contenido cacheado antes de que exista ningún transformador. El stream filter y la cadena de transformadores se construyen solo en el primer fallo.
  • Todas las reglas de reescritura comparten un único recorrido del árbol sintáctico. Una regla cuyo marcador de código fuente no aparece en el archivo se omite, y un archivo sin ninguna regla aplicable ni siquiera se recorre. Es el caso de la mayoría de los archivos.
  • Son tus behavior classes las que activan la maquinaria. Las expresiones new se reescriben solo mientras haya registrada una regla initialization(...). Los proxies de funciones solo existen para reglas de funciones.
  • La comprobación de behavior class, que refleja cada ancestro, solo se ejecuta para las clases que tienen behaviors.
  • Los behaviors de una behavior class se cachean como un archivo PHP normal de expresiones de constructor estáticas, que se carga aproximadamente el doble de rápido que unserialize().
  • Los proxies se construyen como árboles sintácticos y se imprimen una sola vez (−43 % de tiempo de compilación). El trait generado se produce con ediciones de tokens que conservan tus números de línea para Xdebug.
Paso debug => false (+ PREBUILT_CACHE) debug => true
init() del kernel opciones, contenedor, factorías de servicios (no se crea nada) lo mismo, más la vigilancia de cambios en los archivos del kernel y de las behavior classes
_include.cache (class map, conjunto de omisión) un include, servido desde OPcache, sin stat() del directorio de la caché lo mismo
Clase compilada class map de Composer → archivo cacheado, desde OPcache comprobación de vigencia y después el stream filter, para que los breakpoints de Xdebug y las constantes mágicas apunten a tus archivos originales
Clase no transformada bajo las include paths conjunto de omisión → el archivo original, desde OPcache comprobación de vigencia → el archivo original, desde OPcache
Parser, transformadores, stream filter nunca se cargan stream filter registrado, ningún transformador construido
Un archivo fuente modificado la caché construida en el despliegue se sirve tal cual se recompila en la siguiente petición

Llamadas al sistema de archivos de una petición hot, contadas por el profiler:

Llamada PREBUILT_CACHE debug => false debug => true Sin el framework
filemtime / filesize 0 0 323 / 239 0
file_get_contents 0 0 94 0
file_exists (Composer PSR-4) 307 307 412 357

Una petición de producción no comprueba ningún archivo fuente. Incluso necesita menos búsquedas de Composer que la aplicación sin el framework, porque las clases generadas salen directamente del class map. Un class map optimizado de Composer elimina las búsquedas restantes; consulta Autoloader de Composer.

Dos detalles más del índice de tiempo de ejecución:

  • _include.cache contiene solo lo que necesita una petición: el class map, el conjunto de omisión y el include map. Los registros completos de construcción viven en _transformation.cache, que producción nunca lee.
  • Ambos archivos de metadatos son arrays exportados con var_export() con rutas relativas a __DIR__. OPcache los mantiene inmutables en memoria compartida, así que incluirlos no copia nada, y la caché sigue siendo válida cuando se mueve el directorio de la aplicación.

El modo debug está pensado para desarrollo. Sus peticiones hot tardan ~13 ms en el benchmark, frente a ~5.5 ms en producción. El modo debug sigue incluyendo un archivo no transformado vigente por su ruta original, así que OPcache lo cachea (~38 µs → ~10 µs por archivo, peticiones de debug un 27–40 % más rápidas).

  1. Configura 'debug' => false y 'features' => Features::PREBUILT_CACHE.

  2. Construye la caché en el despliegue o al construir la imagen con cache:warmup:aop.

  3. Mantén includePaths acotado: tu src/, no vendor/.

  4. Registra las behavior classes con addLazyService().

  5. Instala las dependencias con composer install --no-dev --classmap-authoritative.

  6. Ejecuta OPcache con opcache.validate_timestamps=0 y memoria y huecos de archivos suficientes para los archivos generados.

  7. En contenedores, construye la caché dentro de la imagen y añade un opcache.file_cache poblado o preloading.

El kernel de producción:

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,
]);
Ventana de terminal
rm -rf var/cache/aop
vendor/bin/aspect cache:warmup:aop public/index.php --workers=$(nproc)

Parte de un directorio vacío, para que la caché contenga exactamente la release actual. El argumento es el archivo que inicializa tu kernel: el controlador frontal o un archivo de bootstrap. El comando lo ejecuta, de modo que el kernel arranca con las mismas opciones que en producción.

El comando:

  • compila cada archivo bajo includePaths (menos excludePaths) y escribe los archivos generados, los proxies, las cachés de las behavior classes y ambos archivos de metadatos;
  • informa en stderr de cada archivo que no se puede compilar y termina con un código distinto de cero, para que un script de despliegue o un docker build se detenga ahí en lugar de publicar una caché incompleta.

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 debug no necesita reconstrucciones: recompila por sí solo las clases, las behavior classes y los archivos del kernel que cambian.

La firma completa del comando:

cache:warmup:aop [<loader>] [--fail-fast] [--workers=N] [--cached-files=N] [--cache-dir=DIR] [--preload[=FILE]]

Dentro de una aplicación que ya ha inicializado su kernel (la consola de una integración con un framework), se omite el argumento con el archivo de carga y el comando usa el kernel del proceso. Consulta Integraciones.

--workers=N compila en N procesos worker, empezando por los archivos más grandes. El valor por defecto es 1, que compila en el propio proceso del comando. Usa el número de CPU. El coordinador escribe los metadatos una sola vez, y cada proceso mantiene en memoria un número acotado de árboles sintácticos.

--cached-files=N fija ese límite por proceso. Por defecto toma la opción del kernel parsedFilesLimit (100). Más archivos cacheados significan menos reanálisis; menos, menos memoria. Añade -v para listar cada archivo en lugar de la barra de progreso.

--cache-dir=DIR construye la caché en otro directorio, desde cero, mientras el kernel sigue sirviendo desde el suyo. Úsalo para preparar la caché de la siguiente release junto a la que está en ejecución y cambiarla de forma atómica, por ejemplo con un intercambio de symlink.

Una caché construida así es completa e independiente de la ubicación, también cuando la construye un kernel de producción con su propia caché warm. El compilador siempre lee los fuentes originales de las clases que refleja, nunca los archivos generados que Composer sirve en producción.

Si se ejecuta sobre un directorio existente, el comando recompila cada archivo cuyo fuente haya cambiado (tamaño o fecha de modificación) y conserva los demás. Esto también vale con PREBUILT_CACHE: solo las peticiones confían en la caché tal cual; el comando de precalentamiento no.

PREBUILT_CACHE y sistemas de archivos de solo lectura

Sección titulada «PREBUILT_CACHE y sistemas de archivos de solo lectura»

Features::PREBUILT_CACHE hace que las peticiones confíen por completo en la caché construida en el despliegue. Se salta:

  • las comprobaciones del directorio de la caché y de permisos de escritura;
  • las comparaciones de filemtime de los fuentes;
  • las comprobaciones de recursos vigilados;
  • las comprobaciones de vigencia de las cachés de las behavior classes.

Una petición nunca compila ni escribe en el directorio de la caché, así que funciona en sistemas de archivos de solo lectura. Por eso la caché debe estar completa. Una clase o un archivo incluido bajo las include paths del que la caché no tiene registro, o un registro cuyo archivo cacheado ha desaparecido, hace fallar la petición con una WeavingException antes de compilar nada. Eso incluye un archivo añadido después de la construcción, aunque no necesite compilarse.

Los archivos que el compilador nunca toma se cargan tal cual: los archivos fuera de las include paths, los archivos excluidos y los archivos que no son .php, como una plantilla incluida.

Cada archivo de la caché se escribe en un archivo temporal único, se renombra a su ubicación y después se invalida en OPcache. Las peticiones concurrentes nunca ven un archivo a medio escribir, no hacen falta bloqueos, y los escritores concurrentes de los metadatos fusionan sus registros.

Composer encuentra como siempre las clases que no se compilan. Con un class map optimizado, cada búsqueda es un acceso a un array en lugar de un file_exists(), y el class map de las clases generadas se fusiona en él con addClassMap(). Las clases generadas y las no transformadas se sirven entonces de la misma forma.

Petición hot del benchmark:

Autoloader PREBUILT_CACHE debug => false Sin el framework
PSR-4 (composer install) 5.5 ms 6.7 ms 2.3 ms
--optimize-autoloader (-o) 5.2 ms 5.0 ms 1.6 ms
--classmap-authoritative (-a) 4.8 ms 4.6 ms 1.9 ms

Con --classmap-authoritative, Composer nunca busca una clase fuera del class map. Ejecuta dump-autoload después de cualquier generación de código y antes del precalentamiento.

Cada clase compilada se convierte en dos archivos cacheados: su cuerpo original como trait, y el proxy. Cada behavior class tiene además su propio archivo de caché. Deja sitio en OPcache para todos ellos.

Ajuste Valor en producción Por qué
opcache.enable 1 El código generado es PHP normal, cacheado como el resto de la aplicación.
opcache.memory_consumption 128–256 (MB) Revisa opcache_get_status()['memory_usage'] bajo carga.
opcache.interned_strings_buffer 16–32 (MB) Los proxies y los traits generados comparten nombres de clases y métodos.
opcache.max_accelerated_files ≥ 2 × los archivos PHP de la aplicación y de vendor/ Cada clase compilada añade un archivo.
opcache.validate_timestamps 0 Releases y contenedores inmutables: ningún stat por include. Recarga PHP-FPM después de un despliegue.
opcache.file_update_protection 0 El framework escribe cada archivo de la caché de forma atómica, así que OPcache puede cachear los archivos recién generados de inmediato en lugar de esperar 2 segundos (el valor por defecto).
opcache.file_cache un directorio Una caché de segundo nivel en disco: un nuevo master de PHP-FPM o un proceso CLI carga los scripts compilados en lugar de compilarlos. Puéblala al construir la imagen.
opcache.preload opcional Enlaza las clases generadas una vez al arrancar el servidor; consulta Preloading.
realpath_cache_size / realpath_cache_ttl 4096K / 600 Con validate_timestamps=1: menos búsquedas de rutas por include.

El código generado es PHP corriente, que el JIT compila como el resto de la aplicación. Una petición web típica pasa su tiempo en muchas llamadas cortas, donde el JIT gana poco, así que mide antes de activarlo.

Los archivos generados son declaraciones de clase corrientes, así que una caché preconstruida se puede precargar. --preload escribe el script opcache.preload de la caché que construye: _preload.php en el directorio de la caché, o el archivo indicado con --preload=FILE.

Ventana de terminal
vendor/bin/aspect cache:warmup:aop public/index.php --workers=$(nproc) --preload
opcache.ini
opcache.preload=/app/var/cache/aop/_preload.php
opcache.preload_user=www-data

El --preload sin valor debe ir después del argumento con el archivo de carga; si no, toma ese archivo como su valor.

Cuando arranca PHP-FPM, el script hace require del autoloader de Composer, le entrega el class map de las clases generadas y enlaza en OPcache cada clase compilada, su proxy y cada clase no transformada que conoce la caché.

  • Los autoloads files de Composer (funciones auxiliares, bootstraps de polyfills) no se precargan. Las peticiones los incluyen como antes.
  • El script no contiene ninguna ruta absoluta. Todo se localiza mediante __DIR__, como los archivos de metadatos, así que una caché que se mueve junto con la aplicación sigue siendo válida.
  • Lista las clases de exactamente la caché con la que se construyó. Reconstrúyelo junto con la caché.
  • Una clase que no se puede enlazar durante el preloading (falta una dependencia opcional) se escribe en el log de errores y se deja al autoloader de la petición.
  • Una clase con un behavior en su inicialización estática también se deja al autoloader: el behavior necesita el kernel, así que la carga la petición.

El kernel se sigue inicializando en cada petición; simplemente, el autoloader nunca tiene que cargar las clases precargadas. En el benchmark, el preloading redujo los archivos incluidos por petición de 517 a 174, la petición hot de 5.2 ms a 4.9 ms, y la primera petición tras arrancar el servidor de 71 ms a 24 ms (10 ms junto con una caché de archivos poblada).

Las clases precargadas solo cambian al reiniciar PHP-FPM, que es como se despliegan los contenedores de todos modos. En la CLI no se precarga nada salvo que esté configurado opcache.enable_cli=1.

Construye la caché del framework dentro de la imagen. Así cada contenedor arranca con una caché completa y de solo lectura, cada réplica sirve exactamente el mismo código generado y ningún pod compila nunca. La shop demo incluye esta configuración como una imagen funcional.

Dockerfile
FROM php:8.5-fpm
# OPcache is part of PHP 8.5, no docker-php-ext-install needed
COPY docker/opcache.ini /usr/local/etc/php/conf.d/opcache.ini
COPY --from=composer:2 /usr/bin/composer /usr/bin/composer
WORKDIR /app
COPY composer.json composer.lock ./
RUN composer install --no-dev --no-scripts --no-autoloader --prefer-dist
COPY . .
RUN composer dump-autoload --no-dev --classmap-authoritative
# 1. The framework's cache: generated classes, proxies, behavior caches, metadata, owned by the user that serves it
# (cache files get the `cacheFileMode` kernel option, by default 0770 minus the umask)
RUN rm -rf var/cache/aop \
&& php vendor/bin/aspect cache:warmup:aop public/index.php --workers="$(nproc)" --preload \
&& chown -R www-data:www-data var/cache/aop \
&& chmod -R a-w var/cache/aop
# 2. The OPcache file cache: a new PHP-FPM master loads compiled scripts instead of compiling them.
# Built in the final image, as the file cache belongs to this PHP build and these paths.
RUN mkdir -p /var/cache/opcache \
&& php -d opcache.enable_cli=1 -d opcache.file_cache_only=1 -d opcache.file_cache=/var/cache/opcache \
vendor/bin/aspect cache:warmup:opcache public/index.php --file-cache=/var/cache/opcache --entry=public/index.php \
&& chown -R www-data /var/cache/opcache
USER www-data

cache:warmup:opcache compila lo que carga la aplicación: la caché del framework (archivos generados, proxies, cachés de las behavior classes y metadatos), el class map y los archivos autocargados de Composer, los fuentes bajo las include paths que no se compilan, el archivo de carga y los puntos de entrada indicados con --entry.

  • Los scripts compilados solo los escribe en disco un proceso arrancado con opcache.enable_cli=1, opcache.file_cache_only=1 y opcache.file_cache=DIR. Estos ajustes no se pueden cambiar en tiempo de ejecución. El comando los comprueba, y también que --file-cache=DIR sea el directorio configurado; si no, imprime el comando exacto que hay que ejecutar.
  • La caché del framework, el archivo de carga y los puntos de entrada deben compilar, o el comando falla. Un archivo del class map de Composer que no compila (un stub de tests de un vendor escrito para un PHP más reciente) se lista y se omite; PHP registra el error de compilación.
  • Ejecútalo después de cache:warmup:aop, en la imagen final, con el binario de PHP que sirve las peticiones. La caché de archivos va ligada a la build de PHP y a las rutas absolutas de los archivos.
docker/opcache.ini
opcache.enable=1
opcache.memory_consumption=192
opcache.interned_strings_buffer=32
opcache.max_accelerated_files=50000
opcache.validate_timestamps=0
opcache.file_cache=/var/cache/opcache
opcache.file_cache_consistency_checks=0
; PHP 8.5: the primed file cache is only read at runtime, also on a read-only root file system
opcache.file_cache_read_only=1
; required on PHP 8.5.11 / 8.5.12, see "JIT"
opcache.jit=disable
; optional, see "Preloading" (written by cache:warmup:aop --preload)
; opcache.preload=/app/var/cache/aop/_preload.php
; opcache.preload_user=www-data

El kernel de la imagen es el kernel de producción de la lista de comprobación: debug => false, includePaths limitado a src/ y Features::PREBUILT_CACHE.

En el benchmark, esta configuración sirve la primera petición de un servidor recién arrancado en 19 ms con la caché de archivos, y en 10 ms con la caché de archivos más preloading, frente a 71 ms sin ninguno de los dos. Los pods son rápidos desde su primera petición.

  • Sistema de archivos raíz de solo lectura (readOnlyRootFilesystem: true). PREBUILT_CACHE lee la caché construida en la imagen y no escribe nada en tiempo de ejecución.
  • Una imagen, una caché. Mantén la caché dentro de la imagen en lugar de en un volumen compartido, para que cada release sirva exactamente el código a partir del que se construyó.
  • Los rolling updates no necesitan nada especial. Los pods nuevos traen su propia caché y los antiguos conservan la suya.
  • Cuando la imagen no puede contener la caché, ejecuta cache:warmup:aop en un init container que escriba en un volumen emptyDir montado en la ruta de la caché del contenedor de la aplicación. Así se mantiene PREBUILT_CACHE y el pod pasa a estar listo con una caché completa.
  • Los contenedores CLI (consumidores de colas, cron jobs) usan la misma imagen y la misma caché. Activa opcache.enable_cli=1 junto con el opcache.file_cache poblado; consulta Procesos CLI.

Los workers de larga duración (RoadRunner, el modo worker de FrankenPHP, Swoole, ReactPHP) arrancan el kernel una vez por worker. Los call contexts siguen inicializados de una petición a la siguiente.

  • Apunta con precisión. Solo se interceptan los miembros seleccionados y solo se compilan las clases seleccionadas, así que una regla precisa es una regla rápida. execution(public App\Service\*->*(*)) también selecciona los constructores. Añade && !execution(**->__construct(*)) cuando no los necesites.
  • Prefiere las reglas de métodos a initialization(...). Mientras haya registrada una regla initialization, cada new de los archivos generados pasa por el transformador. Una clase sin behaviors de inicialización (y con un constructor público) se sigue creando con un new nativo, que cuesta unos 130 ns más que un new normal. Una clase con behaviors de inicialización pasa por el call context completo.
  • Registra las behavior classes de forma lazy con addLazyService(). La behavior class y sus dependencias se crean en la primera llamada a un behavior, no en cada petición.
  • Mantén los behaviors baratos. getMethod() y getField() crean un objeto de reflexión en el primer uso por call context. Extrae de él los atributos o los nombres una sola vez y guárdalos en la behavior class, indexados por class::method.
  • Formatea los call contexts de forma lazy. (string) $invocation construye un string en cada llamada. Úsalo solo para los mensajes que realmente se escriben.
  • Includes nativos. Features::INTERCEPT_INCLUDES hace pasar los include/require de los archivos generados por el compilador, para código legacy que no carga Composer. Con esta opción, en producción un include de un archivo que conoce la caché se sirve por su ruta original o cacheada, sin el stream filter (~250 µs → ~11 µs por include).

Una behavior class registrada de forma lazy:

src/ApplicationAspectKernel.php
use Go\Core\AspectContainer;
use Go\Core\AspectKernel;
use Psr\Log\LoggerInterface;
class ApplicationAspectKernel extends AspectKernel
{
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)),
);
}
}

Cómo escribir behaviors y matching rules se explica en Behaviors y matching rules.

Mensaje o síntoma Qué significa y qué hacer
cache:warmup:aop escribe errores en stderr y termina con un código distinto de cero Un archivo no se puede compilar. El despliegue o el docker build se detiene para que nunca se publique una caché incompleta. Corrige el archivo y vuelve a ejecutar el precalentamiento.
WeavingException: ... is missing from the prebuilt AOP cache in ... Con PREBUILT_CACHE, una clase o un archivo incluido bajo las include paths no tiene registro en la caché, o su archivo cacheado ha desaparecido. Reconstruye la caché con cache:warmup:aop.
cache:warmup:opcache imprime un comando en lugar de poblar la caché El proceso no se arrancó con -d opcache.enable_cli=1 -d opcache.file_cache_only=1 -d opcache.file_cache=DIR, o --file-cache indica otro directorio. Ejecuta el comando impreso.

PHP informa de los problemas de preloading una sola vez, cuando arranca el master de PHP-FPM (o php -S), en su log de errores.

Mensaje Qué significa y qué hacer
Fatal Error "opcache.preload" requires "opcache.preload_user" when running under uid 0 El master se ejecuta como root. Configura opcache.preload_user con el usuario con el que se ejecutan los workers (www-data).
Failed opening required '.../_preload.php' Falta el script: la caché se construyó sin --preload, o opcache.preload apunta a otro directorio de caché. Reconstruye con cache:warmup:aop --preload.
Go! AOP preload: <class> is left to the autoloader: ... El script no pudo cargar una clase de la caché, casi siempre porque una dependencia opcional no está instalada (una imagen --no-dev). Es inofensivo: la clase no se precarga, y una petición que la necesite la autocarga como siempre.
Can't preload unlinked class <class>: Unknown parent/trait/interface <name> in <file> OPcache no pudo enlazar una clase de un archivo que incluyó el preload, por el mismo motivo. Aparece junto con la línea anterior para una clase de la caché. Es inofensivo: la clase simplemente no se precarga.
Can't preload unlinked class class@anonymous: Unknown trait ... en un archivo auxiliar de un vendor Una clase anónima de un autoload files de Composer, por ejemplo Illuminate/Reflection/helpers.php de Laravel. El script de la caché deja fuera estos archivos; el aviso procede de otro script que hace require de vendor/autoload.php antes que él. Haz primero el require del script de la caché: Composer devuelve entonces su loader sin volver a incluir los archivos.

La aplicación, los scripts del benchmark y la imagen de Docker están en goaop/shop-demo. Un solo script reproduce todas las tablas de esta página:

Ventana de terminal
bash bench/run-all.sh
  • Aplicación: ~45 clases escritas a mano (dominio, repositorios, servicios, controladores, infraestructura en memoria), 40 módulos generados (servicio y repositorio compilados; DTO, validador y evento sin compilar) y 120 clases de bibliotecas fuera de las include paths.
  • Behavior classes: logging (#[Before] sobre un atributo), caché y transacciones (#[Around] sobre atributos), monitorización (#[Around] en los repositorios, #[AfterThrowing] en los servicios), auditoría de stock (#[Around] sobre una propiedad), seguridad (#[Before] en los servicios de los módulos).
  • Referencia: el mismo código sin el kernel. Sus behaviors no se ejecutan.
  • Entorno de ejecución: PHP 8.5.12 NTS, 4 CPU, OPcache con opcache.jit=disable y opcache.file_update_protection=0.
  • Peticiones web: el servidor web integrado (php -S, un worker, memoria compartida de OPcache conservada entre peticiones). Warm es la primera petición de un servidor recién arrancado (7 muestras); hot es la mediana de 350 peticiones. Los tiempos se miden dentro del script con hrtime().
  • Perfiles: ejecuciones con Xdebug 3.5 xdebug.mode=profile de cada modo y estado, usadas para el número de llamadas y el reparto del tiempo. Los tiempos proceden de ejecuciones sin Xdebug.

Las proporciones entre los modos son lo que se traslada a otras máquinas.

© 2026 Alexander Lisachenko