Go! AOP weaves aspects into your source code once, stores the result as plain PHP files and from then on serves those
files like any other code: OPcache caches them, Composer loads them, and no parser, reflection or eval() is involved
at runtime. A production request on a warm cache reads one metadata file, hands the woven classes to Composer and pays
only for the calls that are actually intercepted. Methods and properties without advices cost nothing.
This document shows the numbers, explains the optimizations behind them and how to get the most out of them in a real application: cache warm-up, OPcache tuning, Composer, Docker and Kubernetes.
- At a glance
- What a request does in each mode
- Optimizations in the framework
- Production checklist
- Warming up the cache
- Tuning OPcache
- Composer autoloader
- Docker and Kubernetes
- Writing aspects that stay fast
- How the numbers were measured
Measured on a small shop application: about 250 files below the include paths (94 woven classes), 120 library classes outside of them and 6 aspects with before, around, after-throwing and property advices. One request places 50 orders, which makes ~2,600 intercepted method calls and ~950 intercepted property accesses. PHP 8.5.12, OPcache in shared memory, JIT disabled. Details in How the numbers were measured.
- hot: AOP cache present, OPcache filled. The steady state of a production worker.
- warm: AOP cache present, OPcache empty: a freshly started PHP-FPM or a new pod.
- cold: nothing cached yet. The first request weaves every class it loads.
| Mode | hot | warm | Peak memory (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 |
| Same application without AOP (aspects do not run) | 2.1 ms | 36 ms | 0.7 MB |
- ~3,500 interceptions with real advice bodies (logging, cache lookups, timers) add ~3.3 ms to the request. Booting the kernel takes ~0.15 ms of it.
- One intercepted call costs about a third of a microsecond, every further advice on it ~70 ns, see Cost per call.
- The whole cache is built in under half a second with
cache:warmup:aop(2,000 files: 1.1 s with 4 workers). - Containers start hot: with a primed OPcache file cache the first request of a new PHP-FPM takes 19 ms instead of 71 ms, and with preloading on top 10 ms, the same as the plain application without AOP (9 ms). See Docker and Kubernetes.
Empty advices, so only the framework's own work is measured: the joinpoint, the interceptor chain and the call of the original method.
| Call | Overhead per call |
|---|---|
| Method or property without advice in a woven class | 0 |
Method with one #[Before] or #[Around] |
~0.33 µs |
Method with three #[Around] |
~0.48 µs |
Static method with one #[Around] |
~0.34 µs |
Property read with one #[Around] |
~0.22 µs |
Property write with one #[Around] |
~0.26 µs |
A million intercepted calls cost about a third of a second, so a typical request with a few hundred interceptions pays a fraction of a millisecond.
Every CLI process starts with an empty OPcache. A primed opcache.file_cache makes short-lived commands start almost
as fast as a hot web request:
| Script time per process | OPcache off | OPcache on (memory only) | opcache.file_cache, primed |
|---|---|---|---|
PREBUILT_CACHE |
33 ms | 69 ms | 21 ms |
debug => false |
30 ms | 69 ms | 22 ms |
| Without AOP | 19 ms | 34 ms | 10 ms |
| Step | debug => false (+ PREBUILT_CACHE) |
debug => true |
|---|---|---|
Kernel init() |
options, container, service factories (nothing is created) | the same, plus the kernel and aspect files tracked for changes |
_include.cache (class map, skip set) |
one include, served from OPcache, no stat() of the cache directory |
the same |
| Woven class | Composer's class map → cached file, from OPcache | freshness check, then the stream filter, so XDebug breakpoints and magic constants point at your original files |
| Untransformed class below the include paths | skip set → the original file, from OPcache | freshness check → the original file, from OPcache |
| Parser, transformers, stream filter | never loaded | stream filter registered, no transformer built |
| A changed source file | the cache built at deploy time is served as it is | woven again on the next request |
File-system calls of one hot request, counted by the profiler:
| Call | PREBUILT_CACHE |
debug => false |
debug => true |
Without AOP |
|---|---|---|---|---|
filemtime / filesize |
0 | 0 | 323 / 239 | 0 |
file_get_contents |
0 | 0 | 94 | 0 |
file_exists (Composer PSR-4) |
307 | 307 | 412 | 357 |
A production request checks no source file at all, and even needs fewer Composer lookups than the plain application, because the woven classes come straight from the class map. An optimized Composer class map removes the remaining lookups, see Composer autoloader.
- Deferred services. The framework's services, the transformers and your aspects are registered as factories: one array write each. Nothing is autoloaded, reflected or created at boot, so a warm request never loads the parser, the pointcut grammar, the advice matcher or the transformers.
- Aspects are created on the first call of one of their advices, as PHP 8.4 native lazy objects. Weaving and the cache warm-up never create an aspect at all; they only read its class.
- One eager service. The cache index (
CachePathManager) is the only service built ininit(), because the autoloader reads the class map right away. - Zero-cost registration in production. Debug mode tracks aspect files for changes through a registration listener that resolves the files through Composer without loading the classes; production arms no listener at all.
- Precompiled pointcut grammar. The parse table of the pointcut grammar is generated PHP, and pointcuts are parsed on first use only.
- Composer serves woven classes. In production the class map of the cache is handed to Composer with
addClassMap(): a woven class resolves to its cached file natively, withoutrealpath(), path filtering or a stream filter, and known untransformed classes return at once. - A minimal runtime index.
_include.cacheholds only what a request needs (class map, skip set, include map). The full build records live in_transformation.cache, which production never reads. - Constant arrays instead of
unserialize(). Both metadata files arevar_export()ed arrays with__DIR__-relative paths. OPcache keeps them immutable in shared memory, so including them copies nothing, and the cache stays valid when the application directory moves. - Trusted cache with
PREBUILT_CACHE. No sourcefilemtimecomparisons, no tracked-resource checks, no advisor cache freshness checks and no directory probes. It works on read-only file systems. - Opcache-friendly debug mode. A fresh untransformed file is included by its original path, so OPcache caches it even in debug mode (~38 µs → ~10 µs per file, debug requests 27–40 % faster).
- Native includes. With
Features::INTERCEPT_INCLUDES, anincludeof a file known to the cache is served by its original or cached path in production, without the stream filter (~250 µs → ~11 µs per include). - Atomic writes. Every cache file is written to a unique temporary file and renamed into place, then invalidated in OPcache. Concurrent requests never see a half-written file, no locks are needed, and concurrent writers of the metadata merge their records instead of overwriting each other.
- The cache hit path parses nothing. A fresh record is served as the cached content before any transformer exists; the stream filter and the transformer chain are built on the first miss only.
- One syntax tree walk for all rewriting rules. Rules declare the node types they handle and, optionally, source markers: a rule whose marker does not occur in the file is skipped, and a file without any applicable rule is not walked at all, which is the case for most files.
- Machinery switched on by your aspects.
newexpressions are rewritten only while aninitialization(...)pointcut is registered, function proxies only exist for function pointcuts, methods are matched only by method advisors, properties only by property advisors. - Unadvised classes skip the expensive checks. The aspect check, which reflects every ancestor, runs only for classes that have advices.
- Compiled advisor caches. The advisors of an aspect are compiled into a plain PHP file of static constructor
expressions, about twice as fast to load as
unserialize(); its interceptors are lazy, so loading it creates no aspect and no closure. - Proxies built as syntax trees and printed once (−43 % weaving time); the woven trait is produced by token edits that keep your line numbers for XDebug.
- Parallel warm-up.
cache:warmup:aop --workers=Nweaves in worker processes, largest files first; the coordinator writes the metadata once, and every process keeps a bounded number of syntax trees in memory.
- One static joinpoint per member. Every intercepted method declares
static $__joinPoint = InterceptorInjector::forMethod(...): the joinpoint and its interceptor list are built on its first call, every later call is a single$__joinPoint->__invoke($this, [$args]). - First-class callable advices. The interceptor list holds
The::aspect(X::class)->method(...)closures pointing straight at your aspect methods: no advisor lookup, no reflection, no__call(). - Hand-inlined
__invoke()/proceed(). Joinpoints keep their state in properties, push a stack frame only for recursive calls, merge variadic arguments only when there are any, and call the original method through one cachedReflectionMethod. Reflection for advices (getMethod(),getField()) is created only when an advice asks for it. - Native property hooks. Property interception compiles to PHP 8.4
get/sethooks on the proxy: no__get()/__set()magic and no reflection per access. - Unadvised members are untouched. The proxy overrides only the advised members; every other method and property is your original code, so it runs at full speed.
'debug' => falseand'features' => Features::PREBUILT_CACHE.- Build the cache at deploy or image build time with
cache:warmup:aop. - Keep
includePathsnarrow: yoursrc/, notvendor/. - Register aspects with
addLazyService(). composer install --no-dev --classmap-authoritative.- OPcache with
opcache.validate_timestamps=0and enough memory and file slots for the woven files. - In containers: the cache inside the image, plus a primed
opcache.file_cacheor preloading.
rm -rf var/cache/aop
vendor/bin/aspect cache:warmup:aop public/index.php --workers=$(nproc)Start from an empty directory, so the cache contains exactly the current release. The argument is the file that initializes your kernel (the front controller or a bootstrap file). It is executed, so it initializes the kernel with the same options as production. The command:
- weaves every file below
includePaths(minusexcludePaths) and writes the woven files, the proxies, the advisor caches and both metadata files; - reports every file that can not be woven on stderr and exits with a non-zero code, so a deployment script or a
docker buildstops right there; --workers=Nweaves in N processes. Use the number of CPUs: a 2,047-file application took 2.2 s with one worker and 1.1 s with 4 workers on 4 CPUs;--cached-files=N(default: theparsedFilesLimitkernel option, 100) bounds the syntax trees kept in memory per process;--cache-dir=DIRbuilds the cache in another directory from scratch while the kernel keeps serving from its own: a release is prepared next to the running one and switched in atomically, e.g. with a symlink swap.- run over an existing directory, the command weaves again every file whose source changed (size or modification
time) and keeps the others, also with
PREBUILT_CACHE: only requests trust the cache as it is; --preloadwrites theopcache.preloadscript of the cache, see Preloading.
Rebuild the cache whenever the code, the aspects, the kernel options or composer.lock change; in practice, on every
deployment. Debug mode needs no rebuilds: it re-weaves changed classes, aspects and kernel files by itself.
Every woven class becomes two cached files (its original body as a trait, and the proxy), and every aspect gets an advisor cache file. Give OPcache room for them:
| Setting | Production value | Why |
|---|---|---|
opcache.enable |
1 |
Woven code is plain PHP, cached like the rest of the application. |
opcache.memory_consumption |
128–256 (MB) |
Check opcache_get_status()['memory_usage'] under load. |
opcache.interned_strings_buffer |
16–32 (MB) |
Proxies and woven traits share class and method names. |
opcache.max_accelerated_files |
≥ 2 × the PHP files of the application and vendor/ |
Every woven class adds one file. |
opcache.validate_timestamps |
0 |
Immutable releases and containers: no stat per include. Reload PHP-FPM after a deployment. |
opcache.file_update_protection |
0 |
The framework writes every cache file atomically, so OPcache can cache freshly woven files immediately instead of waiting 2 seconds (the default). |
opcache.file_cache |
a directory | A second-level cache on disk: a new PHP-FPM master or CLI process loads compiled scripts instead of compiling them. Prime it at build time. |
opcache.preload |
optional | Links the woven classes once at server start, see Preloading. |
realpath_cache_size / realpath_cache_ttl |
4096K / 600 |
With validate_timestamps=1: fewer path lookups per include. |
Debug mode is made for development: woven classes are served through the stream filter so that XDebug breakpoints and magic constants point at your original files, and changed files are re-woven automatically. Its hot requests take ~13 ms in the benchmark, production ~5.5 ms.
Woven code is ordinary PHP, compiled by the JIT like the rest of the application. A typical web request spends its time in many short calls, where
the JIT gains little, so measure before enabling it. On PHP 8.5.11 and 8.5.12 the tracing JIT (opcache.jit=tracing,
also the default of opcache.jit=on) has a bug of its own: use opcache.jit=disable with these versions.
Woven files are ordinary class declarations, so a prebuilt cache can be preloaded. cache:warmup:aop --preload writes
the opcache.preload script of the cache it builds, _preload.php in the cache directory (or the file given as
--preload=FILE):
vendor/bin/aspect cache:warmup:aop public/index.php --workers=$(nproc) --preloadopcache.preload=/app/var/cache/aop/_preload.php
opcache.preload_user=www-dataThe script requires Composer's autoloader, hands it the woven class map and links every woven class, its proxy and
every untransformed class known to the cache into OPcache when PHP-FPM starts. Composer's files autoloads (helper
functions, polyfill bootstraps) are not preloaded: the requests include them as before, and OPcache would warn about
an anonymous class of a helper function it can not link while preloading. It holds no absolute path (everything is
located through __DIR__, like the metadata files), so a cache moved together with the application stays valid, and
it lists the classes of exactly the cache it was built with: rebuild it with the cache. A class that can not be linked
while preloading (an optional dependency is missing) is written to the error log and left to the autoloader of the
request, like a class whose static initialization is advised: its advice needs the kernel, so the request loads it.
The kernel is initialized on every request as usual; the autoloader simply never has to load the preloaded classes. In the benchmark, preloading cut the included files per request from 517 to 174, the hot request from 5.2 ms to 4.9 ms and the first request after a server start from 71 ms to 24 ms (10 ms together with a primed file cache). Preloaded classes change with a restart of PHP-FPM, which is how containers are deployed anyway.
PHP reports preloading problems once, when the PHP-FPM master (or php -S) starts, in its error log:
| Message | Meaning and what to do |
|---|---|
Fatal Error "opcache.preload" requires "opcache.preload_user" when running under uid 0 |
The master runs as root: set opcache.preload_user to the user the workers run as (www-data). |
Failed opening required '.../_preload.php' |
The script is missing: the cache was built without --preload, or opcache.preload points at another cache directory. Rebuild with cache:warmup:aop --preload. |
Go! AOP preload: <class> is left to the autoloader: ... |
The script could not load a class of the cache, mostly because an optional dependency is not installed (a --no-dev image). Harmless: the class is not preloaded, and a request that needs it autoloads it as usual. |
Can't preload unlinked class <class>: Unknown parent/trait/interface <name> in <file> |
OPcache could not link a class of a file the preload included, for the same reason; it comes together with the line above for a class of the cache. Harmless, the class is simply not preloaded. |
Can't preload unlinked class class@anonymous: Unknown trait ... in a vendor helper file |
An anonymous class of a Composer files autoload, e.g. Laravel's Illuminate/Reflection/helpers.php. The script of the cache leaves these files out; the warning comes from another script that requires vendor/autoload.php before it. Require the script of the cache first: Composer then returns its loader without including the files again. |
Nothing is preloaded in the CLI unless opcache.enable_cli=1 is set, and a script built for another cache, or not
rebuilt with the cache, preloads stale classes until PHP-FPM restarts: rebuild the script with every cache and restart
the master after a deployment.
Classes that are not woven are found by Composer as usual. With an optimized class map every lookup is an array access
instead of a file_exists(), and the woven class map is merged into it, so woven and untransformed classes are served
the same way. Hot request of the benchmark:
| Autoloader | PREBUILT_CACHE |
debug => false |
Without AOP |
|---|---|---|---|
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 |
With --classmap-authoritative Composer never looks for a class outside the class map: run dump-autoload after any
code generation and before the warm-up.
Build the AOP cache into the image. Every container then starts with a complete, read-only cache, every replica serves exactly the same woven code, and no pod ever weaves. The shop demo ships this setup as a working image.
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 AOP cache: woven classes, proxies, advisor 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-datacache:warmup:opcache compiles what the application loads: the AOP cache (woven files, proxies, advisor caches and
metadata), Composer's class map and autoloaded files, the sources below the include paths that are not woven, the
loader file and the entry points given with --entry. Compiled scripts are written to disk only by a process started
with opcache.enable_cli=1, opcache.file_cache_only=1 and opcache.file_cache=DIR, which can not be set at runtime:
the command checks them (and that --file-cache=DIR is the configured directory) and prints the exact command to run
otherwise. The AOP cache, the loader and the entry points must compile; a file of the Composer class map that does not
(a vendor test stub written for a newer PHP) is listed and skipped, PHP logs the compile error. Run it after
cache:warmup:aop, in the final image, with the PHP binary that serves the requests: the file cache is keyed by the
PHP build and the absolute paths of the files.
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-dataThe kernel of the image:
ApplicationAspectKernel::getInstance()->init([
'debug' => false,
'appDir' => __DIR__ . '/..',
'cacheDir' => __DIR__ . '/../var/cache/aop',
'includePaths' => [__DIR__ . '/../src'],
'features' => Features::PREBUILT_CACHE,
]);In the benchmark this setup serves the first request of a fresh server in 19 ms with the file cache and in 10 ms with the file cache plus preloading, against 71 ms without either: pods are fast from their first request.
Running on Kubernetes or another orchestrator:
- Read-only root file system (
readOnlyRootFilesystem: true):PREBUILT_CACHEreads the cache built into the image and writes nothing at runtime. - One image, one cache. Keep the cache inside the image rather than on a shared volume, so every release serves exactly the code it was built from.
- Rolling updates need nothing special: new pods bring their own cache, old pods keep theirs.
- When the image can not contain the cache, run
cache:warmup:aopin an init container that writes to anemptyDirvolume mounted at the cache path of the application container, which keepsPREBUILT_CACHE. The pod becomes ready with a complete cache. - CLI containers (queue consumers, cron jobs) use the same image and cache; enable
opcache.enable_cli=1together with the primedopcache.file_cache, see CLI processes. - Long-running workers (RoadRunner, FrankenPHP worker mode, Swoole, ReactPHP) boot the kernel once per worker, and the joinpoints stay initialized from one request to the next.
- Target precisely. Only matched members are intercepted and only matched classes are woven, so a precise pointcut
is a fast one.
execution(public App\Service\*->*(*))also matches constructors; add&& !execution(**->__construct(*))when you do not need them. - Prefer method pointcuts to
initialization(...). While aninitializationpointcut is registered, everynewin the woven files goes through the transformer. A class without initialization advices (and with a public constructor) is still created by a nativenew, which costs roughly 130 ns more than a plainnew; a class with initialization advices goes through the full joinpoint. - Register aspects lazily with
addLazyService(): the aspect and its dependencies are created on the first advice call, not on every request. - Keep advices cheap.
getMethod()/getField()create a reflection object on first use per joinpoint; derive attributes or names from it once and keep them in the aspect, keyed byclass::method. - Format joinpoints lazily.
(string) $invocationbuilds a string on every call; use it for messages that are actually written.
- Application: ~45 hand-written classes (domain, repositories, services, controllers, in-memory infrastructure),
40 generated modules (service and repository woven; DTO, validator and event not woven) and 120 library classes
outside the include paths. Aspects: logging (
#[Before]on an attribute), caching and transactions (#[Around]on attributes), monitoring (#[Around]on repositories,#[AfterThrowing]on services), stock audit (#[Around]on a property), security (#[Before]on module services). The same code without the kernel is the baseline: its aspects do not run. - PHP 8.5.12 NTS, 4 CPUs, OPcache with
opcache.jit=disableandopcache.file_update_protection=0. - Web requests: the built-in web server (
php -S, one worker, OPcache shared memory kept between requests). Warm is the first request of a freshly started server (7 samples), hot the median of 350 requests. Times are measured inside the script withhrtime(). - Profiles: Xdebug 3.5
xdebug.mode=profileruns of every mode and state, used for call counts and the distribution of the time; the times above come from runs without Xdebug. - The ratios between the modes are what carries over to other machines.
- The application, the benchmark scripts and the Docker image are in goaop/shop-demo;
bash bench/run-all.shreproduces every table of this document.