Zum Inhalt springen
Dokumentation

Produktion & Performance

Was das Framework zur Laufzeit kostet und wie Sie den Cache bauen, abstimmen und ausliefern, damit die Produktion nur für die Aufrufe bezahlt, die Behaviors haben.

Aus dem Englischen übersetzt. Maßgeblich ist die englische Seite. Original lesen

Das Framework kompiliert Ihre Klassen samt ihren Behaviors (Verhalten) ein einziges Mal und legt das Ergebnis als gewöhnliche PHP-Dateien ab. Ab dann werden diese Dateien wie jeder andere Code ausgeliefert: OPcache cacht sie, Composer lädt sie, und zur Laufzeit einer Anfrage laufen weder Parser noch Reflection noch eval(). Eine Produktionsanfrage mit warmem Cache liest eine einzige Metadatendatei, übergibt die generierten Klassen an Composer und bezahlt nur für die Aufrufe, die tatsächlich abgefangen werden. Methoden und Properties ohne Behaviors kosten nichts.

Diese Seite nennt die gemessenen Zahlen, erklärt, woher die Kosten kommen, und zeigt, wie Sie den Cache ausliefern: Warm-up beim Deployment, OPcache, Composer, Docker und Kubernetes. Die Kernel-Optionen beschreibt Konfiguration & CLI. Eine visuelle Zusammenfassung zeigt die Feature-Seite zur Performance.

Alle Zahlen auf dieser Seite stammen aus der Upstream-Datei docs/performance.md von goaop/framework. Sie wurden auf einer einzigen Maschine gemessen; lesen Sie sie daher als Verhältnisse zwischen den Modi. Genau diese Verhältnisse lassen sich auf andere Maschinen übertragen.

  • Eine kleine Shop-Anwendung: etwa 250 Dateien unterhalb der Include-Pfade (94 kompilierte Klassen), 120 Bibliotheksklassen außerhalb davon und 6 Behavior-Klassen (Verhaltensklassen) mit #[Before], #[Around], #[AfterThrowing] und Property-Behaviors.
  • Eine Anfrage gibt 50 Bestellungen auf. Das ergibt ~2.600 abgefangene Methodenaufrufe und ~950 abgefangene Property-Zugriffe.
  • PHP 8.5.12 NTS, 4 CPUs, OPcache im Shared Memory, opcache.jit=disable, opcache.file_update_protection=0.

Das vollständige Vorgehen beschreibt Die Benchmarks nachvollziehen weiter unten.

Die drei Cache-Zustände:

  • heiß: kompilierter Cache vorhanden, OPcache gefüllt. Der Normalzustand eines Produktions-Workers.
  • warm: kompilierter Cache vorhanden, OPcache leer. Ein frisch gestartetes PHP-FPM oder ein neuer Pod.
  • kalt: noch nichts im Cache. Die erste Anfrage kompiliert jede Klasse, die sie lädt.
Modus heiß warm Spitzenspeicher (heiß)
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
Dieselbe Anwendung ohne das Framework (Behaviors laufen nicht) 2,1 ms 36 ms 0,7 MB
  • ~3.500 Interceptions mit echten Behavior-Rümpfen (Logging, Cache-Lookups, Timer) verlängern die Anfrage um ~3,3 ms. Davon entfallen ~0,15 ms auf den Boot des Kernels.
  • Ein abgefangener Aufruf kostet etwa eine Drittelmikrosekunde, jedes weitere Behavior darauf ~70 ns.
  • Der gesamte Cache entsteht mit cache:warmup:aop in weniger als einer halben Sekunde. Eine Anwendung mit 2.000 Dateien braucht mit 4 Workern 1,1 s.
  • Container starten heiß. Mit einem vorbefüllten OPcache-File-Cache dauert die erste Anfrage eines neuen PHP-FPM 19 ms statt 71 ms. Zusätzlich mit Preloading sind es 10 ms, so viel wie bei der reinen Anwendung ohne das Framework (9 ms).

Diese Werte verwenden leere Behaviors und messen damit nur die Arbeit des Frameworks selbst: den Call-Context (Aufrufkontext), die Kette der Interceptors und den Aufruf der ursprünglichen Methode.

Aufruf Overhead pro Aufruf
Methode oder Property ohne Behavior in einer kompilierten Klasse 0
Methode mit einem #[Before] oder #[Around] ~0,33 µs
Methode mit drei #[Around] ~0,48 µs
Statische Methode mit einem #[Around] ~0,34 µs
Lesen einer Property mit einem #[Around] ~0,22 µs
Schreiben einer Property mit einem #[Around] ~0,26 µs

Eine Million abgefangener Aufrufe kostet etwa eine Drittelsekunde. Eine typische Anfrage mit einigen Hundert Interceptions bezahlt den Bruchteil einer Millisekunde.

Jeder CLI-Prozess startet mit leerem OPcache. Ein vorbefüllter opcache.file_cache lässt kurzlebige Befehle fast so schnell starten wie eine heiße Webanfrage.

Skriptzeit pro Prozess OPcache aus OPcache an (nur Speicher) opcache.file_cache, vorbefüllt
PREBUILT_CACHE 33 ms 69 ms 21 ms
debug => false 30 ms 69 ms 22 ms
Ohne das Framework 19 ms 34 ms 10 ms

Der Proxy überschreibt nur die Member, die Behaviors haben. Jede andere Methode und jede andere Property ist Ihr ursprünglicher Code und läuft mit voller Geschwindigkeit: Der Overhead ist 0. Klassen, die keine Matching-Rule (Auswahlregel) auswählt, werden gar nicht kompiliert.

Jede abgefangene Methode deklariert einen statischen Call-Context:

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

Der Call-Context und seine Liste von Interceptors entstehen beim ersten Aufruf. Jeder spätere Aufruf ist ein einziges $__joinPoint->__invoke($this, [$args]). Diese Liste enthält First-Class-Callables, die direkt auf die Methoden Ihrer Behavior-Klassen zeigen: kein Nachschlagen von Behaviors, keine Reflection und kein __call().

Das erste Behavior an einer Methode kostet ~0,33 µs. Jedes weitere Behavior kommt mit ~70 ns hinzu, drei #[Around]-Behaviors kosten also ~0,48 µs. Eine statische Methode mit einem #[Around] kostet ~0,34 µs.

Reflection für Behaviors (getMethod(), getField()) wird erst erzeugt, wenn ein Behavior danach fragt.

Property-Interception wird zu nativen PHP-8.4-Hooks get und set auf dem Proxy kompiliert. Es gibt keine __get()- oder __set()-Magie und keine Reflection pro Zugriff. Das Lesen einer Property mit einem #[Around] kostet ~0,22 µs, das Schreiben ~0,26 µs.

Der Boot des Kernels dauert im Benchmark ~0,15 ms. Die Services des Frameworks, die Transformer und Ihre Behavior-Klassen werden als Factorys registriert, jeweils mit einem einzigen Array-Schreibzugriff. Beim Boot wird nichts per Autoload geladen, nichts reflektiert und nichts instanziiert; eine warme Anfrage lädt also nie den Parser, die Grammatik der Matching-Rules, den Matcher der Behaviors oder die Transformer.

  • Der Cache-Index (CachePathManager) ist der einzige Service, der in init() gebaut wird, weil der Autoloader die Class-Map sofort liest.
  • Behavior-Klassen werden beim ersten Aufruf eines ihrer Behaviors erzeugt, als native Lazy Objects von PHP 8.4. Der Compile-Step (Kompilierschritt) und das Cache-Warm-up erzeugen nie eine Behavior-Klasse; sie lesen sie nur.
  • Die Produktion registriert keinen Registrierungs-Listener. Der Debug-Modus überwacht die Dateien der Behavior-Klassen auf Änderungen, und zwar über einen Listener, der die Dateien über Composer auflöst, ohne die Klassen zu laden.
  • Die Parse-Tabelle der Matching-Rule-Grammatik ist generiertes PHP, und Regeln werden erst bei der ersten Verwendung geparst.

Eine warme Anfrage (kompilierter Cache vorhanden, OPcache leer) dauert mit PREBUILT_CACHE 59 ms, gegenüber 36 ms für die reine Anwendung. Verkürzen lässt sie sich mit einem vorbefüllten opcache.file_cache und Preloading, siehe Docker und Kubernetes.

Eine kalte Anfrage kompiliert jede Klasse, die sie lädt. Mit einem beim Deployment gebauten Cache und PREBUILT_CACHE kompiliert eine Produktionsanfrage nie.

Kompiliert wird einmal, beim Deployment.

  • Der Cache der Benchmark-Anwendung entsteht in weniger als einer halben Sekunde.
  • Eine Anwendung mit 2.047 Dateien brauchte mit einem Worker 2,2 s und mit 4 Workern auf 4 CPUs 1,1 s.
  • Jede geparste Datei, die während des Kompilierens im Speicher bleibt, belegt ~0,2 MB. Die Kernel-Option parsedFilesLimit (Standard 100) begrenzt, wie viele davon gehalten werden.

Was das Kompilieren schnell hält:

  • Der Pfad eines Cache-Treffers parst nichts. Ein aktueller Eintrag wird als gecachter Inhalt ausgeliefert, bevor überhaupt ein Transformer existiert. Stream-Filter und Transformer-Kette werden erst beim ersten Fehltreffer gebaut.
  • Alle Umschreiberegeln teilen sich einen einzigen Durchlauf über den Syntaxbaum. Eine Regel, deren Quellmarker in der Datei nicht vorkommt, wird übersprungen, und eine Datei ohne anwendbare Regel wird gar nicht durchlaufen. Das trifft auf die meisten Dateien zu.
  • Erst Ihre Behavior-Klassen schalten die Maschinerie ein. new-Ausdrücke werden nur umgeschrieben, solange eine initialization(...)-Regel registriert ist. Funktions-Proxys gibt es nur für Funktionsregeln.
  • Die Prüfung der Behavior-Klassen, die jede Elternklasse reflektiert, läuft nur für Klassen mit Behaviors.
  • Die Behaviors einer Behavior-Klasse werden als gewöhnliche PHP-Datei aus statischen Konstruktor-Ausdrücken gecacht, die sich etwa doppelt so schnell lädt wie unserialize().
  • Proxys werden als Syntaxbäume gebaut und einmal ausgegeben (−43 % Kompilierzeit). Der generierte Trait entsteht durch Token-Edits, die Ihre Zeilennummern für Xdebug erhalten.
Schritt debug => false (+ PREBUILT_CACHE) debug => true
Kernel init() Optionen, Container, Service-Factorys (nichts wird erzeugt) dasselbe, zusätzlich werden die Dateien des Kernels und der Behavior-Klassen auf Änderungen überwacht
_include.cache (Class-Map, Skip-Set) ein include, aus OPcache bedient, kein stat() des Cache-Verzeichnisses dasselbe
Kompilierte Klasse Composers Class-Map → gecachte Datei, aus OPcache Aktualitätsprüfung, dann der Stream-Filter, damit Xdebug-Breakpoints und magische Konstanten auf Ihre ursprünglichen Dateien zeigen
Nicht transformierte Klasse unterhalb der Include-Pfade Skip-Set → die ursprüngliche Datei, aus OPcache Aktualitätsprüfung → die ursprüngliche Datei, aus OPcache
Parser, Transformer, Stream-Filter nie geladen Stream-Filter registriert, kein Transformer gebaut
Eine geänderte Quelldatei der beim Deployment gebaute Cache wird unverändert ausgeliefert wird bei der nächsten Anfrage neu kompiliert

Dateisystemaufrufe einer heißen Anfrage, gezählt vom Profiler:

Aufruf PREBUILT_CACHE debug => false debug => true Ohne das Framework
filemtime / filesize 0 0 323 / 239 0
file_get_contents 0 0 94 0
file_exists (Composer PSR-4) 307 307 412 357

Eine Produktionsanfrage prüft keine einzige Quelldatei. Sie braucht sogar weniger Composer-Lookups als die reine Anwendung, weil die generierten Klassen direkt aus der Class-Map kommen. Eine optimierte Composer-Class-Map entfernt die restlichen Lookups, siehe Composer-Autoloader.

Zwei weitere Details des Laufzeit-Index:

  • _include.cache enthält nur, was eine Anfrage braucht: die Class-Map, das Skip-Set und die Include-Map. Die vollständigen Build-Einträge liegen in _transformation.cache, das die Produktion nie liest.
  • Beide Metadatendateien sind per var_export() geschriebene Arrays mit Pfaden relativ zu __DIR__. OPcache hält sie unveränderlich im Shared Memory, sodass das Einbinden nichts kopiert, und der Cache bleibt gültig, wenn das Anwendungsverzeichnis verschoben wird.

Der Debug-Modus ist für die Entwicklung gemacht. Seine heißen Anfragen dauern im Benchmark ~13 ms, in Produktion ~5,5 ms. Auch der Debug-Modus bindet eine aktuelle, nicht transformierte Datei über ihren ursprünglichen Pfad ein, sodass OPcache sie cacht (~38 µs → ~10 µs pro Datei, Debug-Anfragen 27–40 % schneller).

  1. Setzen Sie 'debug' => false und 'features' => Features::PREBUILT_CACHE.

  2. Bauen Sie den Cache beim Deployment oder beim Image-Build mit cache:warmup:aop.

  3. Halten Sie includePaths eng: Ihr src/, nicht vendor/.

  4. Registrieren Sie Behavior-Klassen mit addLazyService().

  5. Installieren Sie die Abhängigkeiten mit composer install --no-dev --classmap-authoritative.

  6. Betreiben Sie OPcache mit opcache.validate_timestamps=0 und genügend Speicher und Datei-Slots für die generierten Dateien.

  7. Bauen Sie den Cache in Containern ins Image, und ergänzen Sie einen vorbefüllten opcache.file_cache oder Preloading.

Der Produktions-Kernel:

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

Beginnen Sie mit einem leeren Verzeichnis, damit der Cache genau das aktuelle Release enthält. Das Argument ist die Datei, die Ihren Kernel initialisiert: der Front-Controller oder eine Bootstrap-Datei. Der Befehl führt sie aus, sodass der Kernel mit denselben Optionen startet wie in Produktion.

Der Befehl:

  • kompiliert jede Datei unterhalb von includePaths (abzüglich excludePaths) und schreibt die generierten Dateien, die Proxys, die Caches der Behavior-Klassen und beide Metadatendateien;
  • meldet jede Datei, die sich nicht kompilieren lässt, auf stderr und endet mit einem Exit-Code ungleich null, sodass ein Deploy-Skript oder ein docker build an dieser Stelle abbricht, statt einen unvollständigen Cache auszuliefern.

Bauen Sie den Cache neu, sobald sich der Code, die Behavior-Klassen, die Kernel-Optionen oder composer.lock ändern. In der Praxis heißt das: bei jedem Deployment. Der Debug-Modus braucht keine Neubauten: Er kompiliert geänderte Klassen, Behavior-Klassen und Kernel-Dateien selbstständig neu.

Die vollständige Signatur des Befehls:

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

Innerhalb einer Anwendung, die ihren Kernel bereits initialisiert hat (die Konsole einer Framework-Integration), entfällt das Loader-Argument, und der Befehl verwendet den Kernel des Prozesses. Siehe Integrationen.

--workers=N kompiliert in N Worker-Prozessen, die größten Dateien zuerst. Der Standard ist 1; dann kompiliert der Befehlsprozess selbst. Verwenden Sie die Anzahl der CPUs. Der Koordinator schreibt die Metadaten einmal, und jeder Prozess hält eine begrenzte Anzahl von Syntaxbäumen im Speicher.

--cached-files=N setzt diese Grenze pro Prozess. Standard ist die Kernel-Option parsedFilesLimit (100). Mehr gecachte Dateien bedeuten weniger erneutes Parsen, weniger bedeuten weniger Speicher. Mit -v wird statt des Fortschrittsbalkens jede Datei aufgelistet.

--cache-dir=DIR baut den Cache von Grund auf in einem anderen Verzeichnis, während der Kernel weiter aus seinem eigenen ausliefert. So bereiten Sie den Cache des nächsten Release neben dem laufenden vor und schalten ihn atomar um, zum Beispiel per Symlink-Tausch.

Ein so gebauter Cache ist vollständig und ortsunabhängig, auch wenn ein Produktions-Kernel ihn baut, während sein eigener Cache warm ist. Der Compiler liest immer die ursprünglichen Quellen der Klassen, die er reflektiert, nie die generierten Dateien, die Composer in Produktion ausliefert.

Über einem bestehenden Verzeichnis ausgeführt, kompiliert der Befehl jede Datei neu, deren Quelle sich geändert hat (Größe oder Änderungszeit), und behält die übrigen. Das gilt auch mit PREBUILT_CACHE: Nur Anfragen vertrauen dem Cache, wie er ist, der Warm-up-Befehl nicht.

PREBUILT_CACHE und schreibgeschützte Dateisysteme

Abschnitt betitelt „PREBUILT_CACHE und schreibgeschützte Dateisysteme“

Features::PREBUILT_CACHE lässt Anfragen dem beim Deployment gebauten Cache vollständig vertrauen. Es entfallen:

  • die Prüfungen von Cache-Verzeichnis und Schreibbarkeit;
  • filemtime-Vergleiche der Quellen;
  • Prüfungen überwachter Ressourcen;
  • Aktualitätsprüfungen der Caches der Behavior-Klassen.

Eine Anfrage kompiliert nie und schreibt nie in das Cache-Verzeichnis; sie funktioniert daher auf schreibgeschützten Dateisystemen. Der Cache muss deshalb vollständig sein. Eine Klasse oder eine eingebundene Datei unterhalb der Include-Pfade, zu der der Cache keinen Eintrag hat, oder ein Eintrag, dessen gecachte Datei fehlt, lässt die Anfrage mit einer WeavingException scheitern, bevor irgendetwas kompiliert wird. Das betrifft auch eine Datei, die nach dem Build hinzukam, selbst wenn sie nicht kompiliert werden muss.

Dateien, die der Compiler nie übernimmt, werden unverändert geladen: Dateien außerhalb der Include-Pfade, ausgeschlossene Dateien und Nicht-.php-Dateien wie ein eingebundenes Template.

Jede Cache-Datei wird in eine eindeutige temporäre Datei geschrieben, an ihren Platz umbenannt und dann in OPcache invalidiert. Parallele Anfragen sehen nie eine halb geschriebene Datei, es sind keine Locks nötig, und parallele Schreiber der Metadaten führen ihre Einträge zusammen.

Klassen, die nicht kompiliert werden, findet Composer wie gewohnt. Mit einer optimierten Class-Map ist jeder Lookup ein Array-Zugriff statt eines file_exists(), und die Class-Map der generierten Klassen wird mit addClassMap() hineingemischt. Generierte und nicht transformierte Klassen werden dann auf dieselbe Weise ausgeliefert.

Heiße Anfrage des Benchmarks:

Autoloader PREBUILT_CACHE debug => false Ohne das 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

Mit --classmap-authoritative sucht Composer nie nach einer Klasse außerhalb der Class-Map. Führen Sie dump-autoload nach jeder Codegenerierung und vor dem Warm-up aus.

Jede kompilierte Klasse wird zu zwei gecachten Dateien: ihrem ursprünglichen Rumpf als Trait und dem Proxy. Jede Behavior-Klasse bekommt eine eigene Cache-Datei. Geben Sie OPcache Platz dafür.

Einstellung Wert in Produktion Warum
opcache.enable 1 Generierter Code ist gewöhnliches PHP und wird wie der Rest der Anwendung gecacht.
opcache.memory_consumption 128–256 (MB) Prüfen Sie opcache_get_status()['memory_usage'] unter Last.
opcache.interned_strings_buffer 16–32 (MB) Proxys und generierte Traits teilen sich Klassen- und Methodennamen.
opcache.max_accelerated_files ≥ 2 × die PHP-Dateien der Anwendung und von vendor/ Jede kompilierte Klasse fügt eine Datei hinzu.
opcache.validate_timestamps 0 Unveränderliche Releases und Container: kein stat pro Include. Laden Sie PHP-FPM nach einem Deployment neu.
opcache.file_update_protection 0 Das Framework schreibt jede Cache-Datei atomar, daher kann OPcache frisch generierte Dateien sofort cachen, statt 2 Sekunden zu warten (der Standard).
opcache.file_cache ein Verzeichnis Ein Second-Level-Cache auf der Platte: Ein neuer PHP-FPM-Master oder CLI-Prozess lädt kompilierte Skripte, statt sie zu kompilieren. Befüllen Sie ihn beim Build vor.
opcache.preload optional Linkt die generierten Klassen einmal beim Serverstart, siehe Preloading.
realpath_cache_size / realpath_cache_ttl 4096K / 600 Mit validate_timestamps=1: weniger Pfad-Lookups pro Include.

Generierter Code ist gewöhnliches PHP und wird wie der Rest der Anwendung vom JIT kompiliert. Eine typische Webanfrage verbringt ihre Zeit in vielen kurzen Aufrufen, bei denen der JIT wenig gewinnt; messen Sie daher, bevor Sie ihn aktivieren.

Generierte Dateien sind gewöhnliche Klassendeklarationen, ein vorab gebauter Cache lässt sich also preloaden. --preload schreibt das opcache.preload-Skript des Caches, den der Befehl baut: _preload.php im Cache-Verzeichnis oder die mit --preload=FILE angegebene Datei.

Terminal-Fenster
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

Ein bloßes --preload muss nach dem Loader-Argument stehen, sonst nimmt es den Loader als seinen Wert.

Beim Start von PHP-FPM bindet das Skript Composers Autoloader ein, übergibt ihm die Class-Map der generierten Klassen und linkt jede kompilierte Klasse, ihren Proxy und jede dem Cache bekannte, nicht transformierte Klasse in OPcache.

  • Composers files-Autoloads (Hilfsfunktionen, Polyfill-Bootstraps) werden nicht preloadet. Anfragen binden sie wie bisher ein.
  • Das Skript enthält keinen absoluten Pfad. Alles wird wie bei den Metadatendateien über __DIR__ gefunden, sodass ein zusammen mit der Anwendung verschobener Cache gültig bleibt.
  • Es listet die Klassen genau des Caches, mit dem es gebaut wurde. Bauen Sie es mit dem Cache neu.
  • Eine Klasse, die sich beim Preloading nicht linken lässt (eine optionale Abhängigkeit fehlt), wird ins Error-Log geschrieben und dem Autoloader der Anfrage überlassen.
  • Eine Klasse mit einem Behavior an ihrer statischen Initialisierung wird ebenfalls dem Autoloader überlassen: Das Behavior braucht den Kernel, also lädt die Anfrage sie.

Der Kernel wird weiterhin bei jeder Anfrage initialisiert; der Autoloader muss die preloadeten Klassen nur nie laden. Im Benchmark senkte Preloading die eingebundenen Dateien pro Anfrage von 517 auf 174, die heiße Anfrage von 5,2 ms auf 4,9 ms und die erste Anfrage nach einem Serverstart von 71 ms auf 24 ms (10 ms zusammen mit einem vorbefüllten File-Cache).

Preloadete Klassen ändern sich nur mit einem Neustart von PHP-FPM, und genau so werden Container ohnehin ausgerollt. In der CLI wird nichts preloadet, solange opcache.enable_cli=1 nicht gesetzt ist.

Bauen Sie den Cache des Frameworks ins Image. Dann startet jeder Container mit einem vollständigen, schreibgeschützten Cache, jede Replica liefert exakt denselben generierten Code aus, und kein Pod kompiliert jemals. Die Shop-Demo liefert dieses Setup als lauffähiges Image.

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 kompiliert, was die Anwendung lädt: den Cache des Frameworks (generierte Dateien, Proxys, Caches der Behavior-Klassen und Metadaten), Composers Class-Map und automatisch geladene Dateien, die nicht kompilierten Quellen unterhalb der Include-Pfade, die Loader-Datei und die mit --entry angegebenen Einstiegspunkte.

  • Kompilierte Skripte schreibt nur ein Prozess auf die Platte, der mit opcache.enable_cli=1, opcache.file_cache_only=1 und opcache.file_cache=DIR gestartet wurde. Diese Einstellungen lassen sich zur Laufzeit nicht setzen. Der Befehl prüft sie, und ob --file-cache=DIR das konfigurierte Verzeichnis ist, und gibt andernfalls den exakten Befehl aus, den Sie ausführen müssen.
  • Der Cache des Frameworks, der Loader und die Einstiegspunkte müssen sich kompilieren lassen, sonst schlägt der Befehl fehl. Eine Datei der Composer-Class-Map, die sich nicht kompilieren lässt (ein Test-Stub eines Vendors, geschrieben für ein neueres PHP), wird aufgelistet und übersprungen; PHP protokolliert den Kompilierfehler.
  • Führen Sie ihn nach cache:warmup:aop aus, im finalen Image, mit dem PHP-Binary, das die Anfragen bedient. Der File-Cache ist an den PHP-Build und die absoluten Pfade der Dateien gebunden.
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

Der Kernel des Images ist der Produktions-Kernel aus der Checkliste: debug => false, includePaths auf src/ beschränkt und Features::PREBUILT_CACHE.

Im Benchmark bedient dieses Setup die erste Anfrage eines frischen Servers mit dem File-Cache in 19 ms und mit File-Cache plus Preloading in 10 ms, gegenüber 71 ms ohne beides. Pods sind ab ihrer ersten Anfrage schnell.

  • Schreibgeschütztes Root-Dateisystem (readOnlyRootFilesystem: true). PREBUILT_CACHE liest den ins Image gebauten Cache und schreibt zur Laufzeit nichts.
  • Ein Image, ein Cache. Halten Sie den Cache im Image statt auf einem geteilten Volume, damit jedes Release genau den Code ausliefert, aus dem es gebaut wurde.
  • Rolling Updates brauchen nichts Besonderes. Neue Pods bringen ihren eigenen Cache mit, alte Pods behalten ihren.
  • Wenn das Image den Cache nicht enthalten kann, führen Sie cache:warmup:aop in einem Init-Container aus, der in ein emptyDir-Volume schreibt, das unter dem Cache-Pfad des Anwendungscontainers eingehängt ist. So bleibt PREBUILT_CACHE erhalten, und der Pod wird mit einem vollständigen Cache bereit.
  • CLI-Container (Queue-Consumer, Cronjobs) verwenden dasselbe Image und denselben Cache. Aktivieren Sie opcache.enable_cli=1 zusammen mit dem vorbefüllten opcache.file_cache, siehe CLI-Prozesse.

Langlebige Worker (RoadRunner, FrankenPHP im Worker-Modus, Swoole, ReactPHP) booten den Kernel einmal pro Worker. Die Call-Contexts bleiben von einer Anfrage zur nächsten initialisiert.

  • Zielen Sie präzise. Nur ausgewählte Member werden abgefangen und nur ausgewählte Klassen kompiliert; eine präzise Regel ist also eine schnelle. execution(public App\Service\*->*(*)) trifft auch Konstruktoren. Ergänzen Sie && !execution(**->__construct(*)), wenn Sie diese nicht brauchen.
  • Bevorzugen Sie Methodenregeln gegenüber initialization(...). Solange eine initialization-Regel registriert ist, läuft jedes new in den generierten Dateien durch den Transformer. Eine Klasse ohne Initialisierungs-Behaviors (und mit öffentlichem Konstruktor) wird weiterhin mit einem nativen new erzeugt, das rund 130 ns mehr kostet als ein einfaches new. Eine Klasse mit Initialisierungs-Behaviors durchläuft den vollständigen Call-Context.
  • Registrieren Sie Behavior-Klassen lazy mit addLazyService(). Die Behavior-Klasse und ihre Abhängigkeiten entstehen beim ersten Behavior-Aufruf, nicht bei jeder Anfrage.
  • Halten Sie Behaviors billig. getMethod() und getField() erzeugen bei der ersten Verwendung pro Call-Context ein Reflection-Objekt. Leiten Sie Attribute oder Namen einmal daraus ab, und halten Sie sie in der Behavior-Klasse, mit class::method als Schlüssel.
  • Formatieren Sie Call-Contexts lazy. (string) $invocation baut bei jedem Aufruf einen String. Verwenden Sie es nur für Meldungen, die tatsächlich geschrieben werden.
  • Native Includes. Features::INTERCEPT_INCLUDES leitet include/require in generierten Dateien durch den Compiler, für Legacy-Code, den nicht Composer lädt. Damit wird ein include einer dem Cache bekannten Datei in Produktion über ihren ursprünglichen oder gecachten Pfad bedient, ohne den Stream-Filter (~250 µs → ~11 µs pro Include).

Eine lazy registrierte Behavior-Klasse:

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)),
);
}
}

Wie Sie Behaviors und Matching-Rules schreiben, beschreibt Behaviors & Matching-Rules.

Meldung oder Symptom Bedeutung und was zu tun ist
cache:warmup:aop schreibt Fehler auf stderr und endet mit einem Exit-Code ungleich null Eine Datei lässt sich nicht kompilieren. Das Deployment oder docker build bricht ab, damit nie ein unvollständiger Cache ausgeliefert wird. Korrigieren Sie die Datei, und führen Sie das Warm-up erneut aus.
WeavingException: ... is missing from the prebuilt AOP cache in ... Mit PREBUILT_CACHE hat eine Klasse oder eingebundene Datei unterhalb der Include-Pfade keinen Eintrag im Cache, oder ihre gecachte Datei fehlt. Bauen Sie den Cache mit cache:warmup:aop neu.
cache:warmup:opcache gibt einen Befehl aus, statt den Cache vorzubefüllen Der Prozess wurde nicht mit -d opcache.enable_cli=1 -d opcache.file_cache_only=1 -d opcache.file_cache=DIR gestartet, oder --file-cache nennt ein anderes Verzeichnis. Führen Sie den ausgegebenen Befehl aus.

PHP meldet Preloading-Probleme einmalig beim Start des PHP-FPM-Masters (oder von php -S) in dessen Error-Log.

Meldung Bedeutung und was zu tun ist
Fatal Error "opcache.preload" requires "opcache.preload_user" when running under uid 0 Der Master läuft als root. Setzen Sie opcache.preload_user auf den Benutzer, unter dem die Worker laufen (www-data).
Failed opening required '.../_preload.php' Das Skript fehlt: Der Cache wurde ohne --preload gebaut, oder opcache.preload zeigt auf ein anderes Cache-Verzeichnis. Bauen Sie mit cache:warmup:aop --preload neu.
Go! AOP preload: <class> is left to the autoloader: ... Das Skript konnte eine Klasse des Caches nicht laden, meist weil eine optionale Abhängigkeit nicht installiert ist (ein --no-dev-Image). Harmlos: Die Klasse wird nicht preloadet, und eine Anfrage, die sie braucht, lädt sie wie gewohnt per Autoload.
Can't preload unlinked class <class>: Unknown parent/trait/interface <name> in <file> OPcache konnte eine Klasse aus einer vom Preload eingebundenen Datei aus demselben Grund nicht linken. Bei einer Klasse des Caches erscheint die Meldung zusammen mit der Zeile darüber. Harmlos: Die Klasse wird einfach nicht preloadet.
Can't preload unlinked class class@anonymous: Unknown trait ... in einer Hilfsdatei eines Vendors Eine anonyme Klasse aus einem Composer-files-Autoload, zum Beispiel Laravels Illuminate/Reflection/helpers.php. Das Skript des Caches lässt diese Dateien aus; die Warnung stammt von einem anderen Skript, das vorher vendor/autoload.php einbindet. Binden Sie das Skript des Caches zuerst ein: Composer gibt dann seinen Loader zurück, ohne die Dateien erneut einzubinden.

Die Anwendung, die Benchmark-Skripte und das Docker-Image liegen in goaop/shop-demo. Ein einziges Skript reproduziert jede Tabelle dieser Seite:

Terminal-Fenster
bash bench/run-all.sh
  • Anwendung: ~45 handgeschriebene Klassen (Domäne, Repositories, Services, Controller, In-Memory-Infrastruktur), 40 generierte Module (Service und Repository kompiliert; DTO, Validator und Event nicht kompiliert) und 120 Bibliotheksklassen außerhalb der Include-Pfade.
  • Behavior-Klassen: Logging (#[Before] auf einem Attribut), Caching und Transaktionen (#[Around] auf Attributen), Monitoring (#[Around] auf Repositories, #[AfterThrowing] auf Services), Bestandsaudit (#[Around] auf einer Property), Security (#[Before] auf Modul-Services).
  • Baseline: derselbe Code ohne den Kernel. Seine Behaviors laufen nicht.
  • Laufzeit: PHP 8.5.12 NTS, 4 CPUs, OPcache mit opcache.jit=disable und opcache.file_update_protection=0.
  • Webanfragen: der eingebaute Webserver (php -S, ein Worker, OPcache-Shared-Memory bleibt zwischen Anfragen erhalten). Warm ist die erste Anfrage eines frisch gestarteten Servers (7 Messungen); heiß ist der Median von 350 Anfragen. Die Zeiten werden im Skript mit hrtime() gemessen.
  • Profile: Läufe mit Xdebug 3.5 im Modus xdebug.mode=profile für jeden Modus und Zustand, verwendet für Aufrufzahlen und die Verteilung der Zeit. Die Zeiten stammen aus Läufen ohne Xdebug.

Die Verhältnisse zwischen den Modi sind das, was sich auf andere Maschinen übertragen lässt.

© 2026 Alexander Lisachenko