OPcache-Tuning für Produktionsumgebungen: Werte, die wirklich zählen

1. Was OPcache tatsächlich tut

OPcache übersetzt PHP-Quellcode einmalig in Opcodes (den kompilierten Bytecode der Zend Engine) und hält diese Struktur im Shared Memory des Prozesses vor. Ohne OPcache parst und kompiliert PHP bei jedem einzelnen Request jede eingebundene Datei neu, unabhängig davon, ob sich am Code seit dem letzten Aufruf etwas geändert hat. Bei einer typischen Anwendung mit mehreren tausend PHP-Dateien bedeutet das tausende Parse- und Compile-Vorgänge pro Sekunde, die durch OPcache-Tuning vollständig entfallen können, weil der Bytecode direkt aus dem Shared Memory ausgeführt wird.

Das Problem: Die Werkseinstellungen, wie sie in einer Standard-php.ini oder im OPcache-Default-Build ausgeliefert werden, sind für ein breites Spektrum an Anwendungsfällen kalibriert, nicht für einen spezifischen Produktionsworkload. opcache.memory_consumption steht standardmäßig auf 128 MB, was für größere Codebasen zu knapp bemessen ist. opcache.validate_timestamps ist standardmäßig aktiv und sorgt dafür, dass bei jedem Request ein stat()-Syscall pro eingebundener Datei ausgeführt wird, um Änderungen zu erkennen, ein Overhead, den man in Produktion nicht braucht, weil sich der Code zwischen Deployments nicht ändert.

OPcache-Tuning bedeutet also nicht, OPcache zu aktivieren (das ist in praktisch jeder aktuellen PHP-Installation bereits Standard), sondern die Parameter gezielt auf den tatsächlichen Workload abzustimmen: genug Speicher für den gesamten Codebestand, keine Dateisystem-Prüfungen bei jedem Request, ein korrekt dimensioniertes Interned-Strings-Buffer und ein Deployment-Prozess, der den Cache zuverlässig und ohne Downtime aktualisiert. Die folgenden Abschnitte gehen jeden dieser Hebel im Detail durch.

2. memory_consumption und interned_strings_buffer richtig dimensionieren

opcache.memory_consumption legt fest, wie viel Shared Memory OPcache für kompilierten Bytecode reserviert, angegeben in Megabyte. Ist der Wert zu niedrig gewählt, beginnt OPcache, ältere Cache-Einträge zu verdrängen, sobald der Speicher voll ist, ein Vorgang, der als Cache-Wrap oder Restart bekannt ist und dazu führt, dass bereits kompilierte Dateien erneut geparst werden müssen. Das äußert sich in opcache_get_status() als steigender Wert bei opcache_restarts und ist ein klares Signal für zu wenig Speicher, unabhängig davon, wie hoch die Hit-Rate gerade aussieht.

Die richtige Größe ermittelt man, indem man used_memory aus opcache_get_status() unter realistischer Last beobachtet und mit einem Sicherheitspuffer von 30 bis 50 Prozent versieht, um Wachstum durch neue Dateien oder zusätzliche Deployments abzufangen. Für mittelgroße Anwendungen mit einigen tausend PHP-Dateien sind 256 bis 512 MB ein üblicher Ausgangspunkt, für große monolithische Codebasen oder Anwendungen mit vielen Vendor-Paketen können 512 MB bis 1 GB notwendig sein. Wichtig ist, wasted_memory regelmäßig zu prüfen: Ein hoher Wasted-Memory-Anteil relativ zu used_memory deutet nicht auf zu wenig, sondern auf fragmentierten Speicher hin, meist verursacht durch häufige Neukompilierungen einzelner Dateien bei aktivem validate_timestamps.

opcache.interned_strings_buffer ist ein separater Speicherbereich für interned Strings, also identische String-Literale, die PHP intern dedupliziert, um Speicher zu sparen. Der Standardwert von 8 MB reicht für kleine Skripte, wird aber bei Frameworks mit vielen Klassennamen, Konstanten und String-Literalen schnell knapp. Ist der Buffer voll, dedupliziert PHP nicht mehr zuverlässig, was sich in höherem Speicherverbrauch pro Worker-Prozess niederschlägt, ohne dass das in opcache_get_status() direkt sichtbar wird. Ein Wert zwischen 16 und 32 MB ist für die meisten Produktionsanwendungen ausreichend dimensioniert und ein zentraler, oft übersehener Baustein beim OPcache-Tuning.

3. max_accelerated_files: die richtige Dateianzahl ermitteln

opcache.max_accelerated_files begrenzt, wie viele einzelne PHP-Dateien OPcache gleichzeitig im Cache halten kann. Intern verwaltet OPcache diese Dateien in einer Hash-Tabelle fester Größe, die zur Optimierung intern auf die nächste Primzahl über dem konfigurierten Wert angehoben wird. Ist der konfigurierte Wert niedriger als die tatsächliche Anzahl der PHP-Dateien im Projekt, beginnt OPcache, Einträge zu verdrängen, sobald das Limit erreicht ist, mit denselben negativen Effekten wie bei zu wenig memory_consumption: erneutes Parsen, höhere Latenz, sinkende Hit-Rate.

Die tatsächliche Dateianzahl eines Projekts lässt sich einfach ermitteln, inklusive aller Vendor-Abhängigkeiten, da auch Third-Party-Bibliotheken im selben Cache landen. Ein einfacher Zähl-Befehl über das gesamte Projektverzeichnis liefert die Basis für die Dimensionierung, und genau diese Basis ist der Ausgangspunkt für jedes seriöse OPcache-Tuning.

# Count all PHP files in the project, including vendor dependencies
find . -name "*.php" -not -path "*/node_modules/*" | wc -l

# Example output for a mid-sized application with framework and dependencies
# 14832

# Cross-check against currently cached files at runtime
php -r 'var_dump(opcache_get_status(false)["opcache_statistics"]["num_cached_scripts"]);'

# Compare against the configured limit
php -i | grep opcache.max_accelerated_files

Die gängige Empfehlung lautet, den ermittelten Wert auf die nächste sinnvolle Größenordnung aufzurunden und einen Puffer von 20 bis 30 Prozent für zukünftiges Wachstum einzuplanen. Bei rund 15.000 Dateien ist ein Wert von 20.000 bis 30.000 eine solide Wahl. Der maximal zulässige Wert liegt bei 1.000.000, und da der interne Hash-Tabellen-Overhead pro zusätzlichem Slot minimal ist, gibt es selten einen Grund, hier zu knapp zu kalkulieren, ein zu niedriger Wert kostet in Produktion deutlich mehr als ein paar zusätzliche Megabyte Verwaltungsoverhead. Ein Blick auf opcache_restarts in Kombination mit num_cached_scripts nahe am konfigurierten Limit ist das verlässlichste Signal dafür, dass max_accelerated_files zu niedrig gesetzt ist.

4. validate_timestamps und revalidate_freq: Dev vs. Produktion

opcache.validate_timestamps steuert, ob OPcache bei jedem Zugriff (beziehungsweise im Intervall von opcache.revalidate_freq) die Änderungszeit einer Datei prüft, um festzustellen, ob eine Neukompilierung nötig ist. In der Entwicklung ist das essenziell: Ohne diese Prüfung würde eine geänderte Datei erst nach einem manuellen Cache-Reset berücksichtigt, was den Entwicklungsworkflow erheblich verlangsamen würde. Hier ist opcache.revalidate_freq=0 in Kombination mit aktivem validate_timestamps sinnvoll, das prüft bei jedem Request und liefert sofortiges Feedback auf Codeänderungen.

In Produktion ist genau diese Prüfung unnötiger Overhead. Der Code ändert sich zwischen Deployments nicht, jeder stat()-Aufruf pro eingebundener Datei kostet jedoch Zeit, die sich bei tausenden Requests pro Sekunde summiert, insbesondere auf Dateisystemen mit höherer I/O-Latenz wie Netzwerkspeicher oder bestimmten Cloud-Volumes. Die korrekte Produktionseinstellung ist opcache.validate_timestamps=0, das deaktiviert die Timestamp-Prüfung vollständig. OPcache geht dann davon aus, dass sich der einmal kompilierte Code nicht mehr ändert, und liest ihn ausschließlich aus dem Shared Memory.

Die Deployment-Implikation ist entscheidend: Mit validate_timestamps=0 erkennt PHP Codeänderungen nach einem Deployment nicht mehr automatisch. Ein einfaches Überschreiben von Dateien auf dem Server reicht nicht mehr aus, der OPcache-Zustand muss nach jedem Deployment explizit invalidiert werden, entweder über opcache_reset(), einen FPM-Neustart oder das Neuladen des File Cache. Wer diesen Schritt im Deployment-Skript vergisst, liefert nach dem Deployment weiterhin die alte Codeversion aus dem Cache aus, ein klassischer und schwer zu diagnostizierender Fehler, weil im Dateisystem bereits der neue Code liegt, während die laufenden Worker-Prozesse noch die alten Opcodes ausführen.

5. save_comments und Auswirkung auf Attribute und Reflection

opcache.save_comments steuert, ob Doc-Comments (die /** */-Blöcke) beim Kompilieren im Bytecode erhalten bleiben oder verworfen werden. In sehr alten OPcache-Versionen wurde empfohlen, diesen Wert für maximale Performance zu deaktivieren, weil Doc-Comments zusätzlichen Speicher im Cache belegen. Diese Empfehlung ist heute in den allermeisten Fällen falsch und potenziell gefährlich.

Der Grund: Reflection-basierte Bibliotheken, Dependency-Injection-Container, ORMs und Validierungsframeworks lesen Metadaten häufig aus Doc-Comment-Annotationen aus, etwa im Format @ORM\Column oder ähnlichen Annotationsschemata. Ist save_comments deaktiviert, verschwinden diese Kommentare aus dem kompilierten Bytecode, und jede Reflection-basierte Logik, die auf sie angewiesen ist, bricht zur Laufzeit, oft ohne klare Fehlermeldung, sondern schlicht durch fehlendes Metadaten-Mapping.

Native PHP-Attribute (#[Attribute]-Syntax, verfügbar seit PHP 8.0) sind von dieser Einstellung nicht betroffen, da sie Teil der Sprachsyntax und nicht des Kommentarsystems sind und immer im Bytecode erhalten bleiben. Trotzdem sollte opcache.save_comments in praktisch jeder modernen Produktionsumgebung auf 1 (aktiviert, der Standardwert) belassen werden, da viele Bibliotheken weiterhin Annotationen nutzen und der Speicher-Overhead durch erhaltene Kommentare im Vergleich zum Risiko kaputter Reflection-Logik vernachlässigbar ist. Ein OPcache-Tuning, das an dieser Stelle spart, spart am falschen Ende.

6. OPcache Preloading: Vorteile und Fallstricke

Preloading, eingeführt in PHP 7.4, geht einen Schritt weiter als das reguläre Caching: Über opcache.preload wird eine PHP-Datei angegeben, die beim Start jedes FPM-Worker-Prozesses (beziehungsweise beim Start des Master-Prozesses, abhängig von der SAPI) ausgeführt wird und Klassen sowie Funktionen vorab in den Speicher lädt, bevor der erste Request überhaupt eintrifft. Diese vorgeladenen Klassen bleiben für die gesamte Lebensdauer des Worker-Prozesses im Speicher und werden nicht wie regulärer OPcache-Inhalt bei Timestamp-Änderungen invalidiert.

Der Performance-Vorteil ist real: Häufig genutzte Basisklassen, Interfaces und Kernkomponenten eines Frameworks müssen nicht mehr pro Request aus dem regulären Cache aufgelöst werden, die Klassenauflösung entfällt komplett, weil die Klassen bereits vollständig geladen und verlinkt im Speicher stehen. Bei Anwendungen mit tiefen Vererbungshierarchien oder vielen Interface-Implementierungen kann das spürbare Latenzreduktion bringen.

Der zentrale Fallstrick ist Zustand, der zwischen Requests durchsickert. Da vorgeladene Klassen im Speicher des Worker-Prozesses verbleiben, dürfen statische Properties oder Singleton-Instanzen in vorgeladenen Klassen keinen Request-spezifischen Zustand halten, sonst sickert der Zustand eines Requests in den nächsten Request desselben Worker-Prozesses durch, ein subtiler und schwer reproduzierbarer Bug, der nur unter Last und mit bestimmten Worker-Zuteilungen auftritt. opcache.preload_user legt fest, unter welchem Systembenutzer das Preload-Skript ausgeführt wird, wichtig für korrekte Dateisystem-Berechtigungen. Preloading sollte fest in den Deployment-Prozess integriert werden: Nach jedem Deployment muss der FPM-Prozess neu gestartet werden, damit das aktualisierte Preload-Skript greift, ein einfaches opcache_reset() reicht dafür nicht aus, da vorgeladene Klassen davon nicht betroffen sind. Wer Preloading als Baustein seines OPcache-Tuning einsetzt, sollte diesen Neustart-Schritt fest im Deployment-Skript verankern, statt sich auf manuelle Disziplin zu verlassen.

7. File Cache für CLI-Skripte und Neustart-Persistenz

opcache.file_cache aktiviert eine zweite Cache-Ebene, die kompilierten Bytecode zusätzlich zum Shared Memory auf die Festplatte schreibt. Der Hauptnutzen zeigt sich bei zwei Szenarien: kurzlebigen CLI-Prozessen und Neustarts des Webservers oder FPM-Pools. CLI-Skripte starten typischerweise einen neuen PHP-Prozess pro Aufruf und profitieren normalerweise nicht vom Shared-Memory-Cache eines langlebigen FPM-Workers. Mit aktiviertem File Cache liest ein CLI-Aufruf den bereits kompilierten Bytecode von der Festplatte statt den kompletten Quellcode erneut zu parsen, was besonders bei Cronjobs und Batch-Skripten, die häufig im Sekundentakt laufen, spürbar Zeit spart.

Beim Neustart eines FPM-Pools wird der Shared-Memory-Cache normalerweise komplett geleert, die ersten Requests nach einem Neustart treffen also auf einen kalten Cache und müssen jede Datei neu kompilieren, was zu einer kurzen Phase erhöhter Latenz führt. Mit aktivem File Cache kann OPcache stattdessen den bereits kompilierten Bytecode von der Festplatte laden, was den Kaltstart erheblich beschleunigt. opcache.file_cache_only=1 ist eine Sonderkonfiguration für Umgebungen ohne Shared Memory, etwa bestimmte eingeschränkte Container-Setups, hier läuft OPcache ausschließlich über den dateibasierten Cache, was langsamer als Shared Memory ist, aber immer noch erheblich schneller als kein Caching.

8. Monitoring via opcache_get_status()

Die Funktion opcache_get_status() liefert ein Array mit allen relevanten Laufzeitmetriken von OPcache und ist die Grundlage jedes ernsthaften OPcache-Tunings. Die wichtigste Kennzahl ist die Hit-Rate, das Verhältnis von Cache-Treffern zu Gesamtzugriffen. Eine Hit-Rate unter 99 Prozent in Produktion ist ein klares Warnsignal und deutet fast immer auf zu niedrig konfigurierte max_accelerated_files oder memory_consumption hin. wasted_memory zeigt Speicher, der durch verworfene, aber noch nicht bereinigte Cache-Einträge belegt ist, ein dauerhaft hoher Anteil deutet auf häufige Neukompilierungen hin, meist verursacht durch aktives validate_timestamps in Kombination mit sich häufig ändernden Dateien.

current_wasted_percentage ist der prozentuale Anteil von Wasted Memory am Gesamtspeicher. Überschreitet dieser Wert den in opcache.max_wasted_percentage konfigurierten Schwellwert (Standard 5 Prozent), löst OPcache automatisch einen vollständigen Cache-Restart aus, was kurzzeitig zu erhöhter Latenz führt. Ein regelmäßig überschrittener Schwellwert ist ein Symptom, das man beheben sollte, nicht durch Anheben des Schwellwerts kaschieren.

<?php

declare(strict_types=1);

/**
 * Minimal OPcache monitoring script for periodic health checks.
 * Run via cron or an internal admin endpoint, never expose publicly.
 */
function checkOpcacheHealth(): array
{
    $status = opcache_get_status(false);

    if ($status === false) {
        return ['error' => 'OPcache is not enabled'];
    }

    $stats = $status['opcache_statistics'];
    $memory = $status['memory_usage'];

    $hitRate = $stats['opcache_hit_rate'];
    $wastedPercentage = $memory['current_wasted_percentage'];
    $restarts = $stats['opcache_restarts'];
    $cachedScripts = $stats['num_cached_scripts'];
    $maxScripts = ini_get('opcache.max_accelerated_files');

    $warnings = [];

    if ($hitRate < 99.0) {
        $warnings[] = sprintf('Hit rate low: %.2f%% (expected >= 99%%)', $hitRate);
    }

    if ($wastedPercentage > 5.0) {
        $warnings[] = sprintf('Wasted memory high: %.2f%%', $wastedPercentage);
    }

    if ($cachedScripts >= (int) $maxScripts * 0.9) {
        $warnings[] = sprintf(
            'Approaching max_accelerated_files limit: %d / %d',
            $cachedScripts,
            (int) $maxScripts
        );
    }

    return [
        'hit_rate' => $hitRate,
        'wasted_percentage' => $wastedPercentage,
        'restarts' => $restarts,
        'cached_scripts' => $cachedScripts,
        'warnings' => $warnings,
    ];
}

$result = checkOpcacheHealth();
echo json_encode($result, JSON_PRETTY_PRINT), PHP_EOL;

Ein solches Skript lässt sich einfach in ein Monitoring-System integrieren, das die Metriken periodisch abfragt und bei Überschreitung der Schwellwerte Alarme auslöst. Wichtig ist, die Zugriffskontrolle sauber zu regeln, ein Endpoint, der interne Cache-Metriken preisgibt, gehört niemals öffentlich erreichbar ins Netz, sondern hinter Authentifizierung oder ausschließlich auf einer internen Netzwerkschnittstelle.

9. Zero-Downtime-Deployment: opcache_reset() vs. Rolling Restart

Nach jedem Deployment mit aktivem validate_timestamps=0 muss der OPcache-Zustand aktualisiert werden, damit die neue Codeversion tatsächlich ausgeliefert wird. Der naheliegende Ansatz ist ein Aufruf von opcache_reset(), das den kompletten Cache leert und beim nächsten Request neu aufbaut. Das Problem: opcache_reset() wirkt nur innerhalb des Prozesses, der es aufruft. In einem FPM-Pool mit mehreren Worker-Prozessen hat jeder Worker seinen eigenen PHP-Interpreter-Zustand, aber sie teilen sich denselben Shared-Memory-Cache-Bereich über die SHM-Segmente. Ein einzelner Reset-Aufruf über einen HTTP-Request trifft daher nur den einen Worker, der die Anfrage bearbeitet hat, während die übrigen Worker weiterhin den alten Bytecode aus dem gemeinsamen Speicher servieren, bis sie ihrerseits einen Reset auslösen oder neu gestartet werden.

Das führt zu einem Zeitfenster, in dem verschiedene Worker desselben Pools unterschiedliche Codeversionen ausliefern, ein inkonsistenter Zustand, der bei API-Anfragen zu widersprüchlichen Antworten führen kann und bei Datenbankmigrationen, die mit neuem Code Hand in Hand gehen müssen, zu echten Datenintegritätsproblemen führen kann. Ein einfaches, unkoordiniertes opcache_reset() pro Request ist daher in Produktionsumgebungen mit mehreren Workern ein Risiko, keine verlässliche Lösung.

Die robustere Alternative ist ein Rolling Restart des FPM-Pools, bei dem Worker-Prozesse nacheinander (nicht gleichzeitig) neu gestartet werden, sodass zu jedem Zeitpunkt genug Worker mit altem oder neuem Code verfügbar bleiben, um eingehende Requests zu bedienen, ohne dass der Dienst insgesamt ausfällt. Praktisch lässt sich das über einen graceful reload des FPM-Masterprozesses erreichen, der neue Worker mit frischem OPcache-Zustand startet und alte Worker erst nach Abschluss ihrer aktuellen Requests beendet. Alternativ, bei Systemen mit mehreren Servern hinter einem Load Balancer, funktioniert ein klassisches Blue-Green- oder rollierendes Server-für-Server-Deployment, bei dem jeder Server einzeln aus dem Load Balancer genommen, neu gestartet und wieder hinzugefügt wird. In beiden Fällen ist der entscheidende Punkt, dass der Cache-Zustand konsistent über den gesamten Pool hinweg aktualisiert wird, statt sich auf einzelne, unkoordinierte Reset-Aufrufe zu verlassen.

10. Zusammenfassung

Erfolgreiches OPcache-Tuning in Produktionsumgebungen dreht sich um wenige, aber entscheidende Parameter. opcache.memory_consumption und opcache.interned_strings_buffer müssen groß genug dimensioniert sein, um Cache-Restarts zu vermeiden, ermittelt anhand von used_memory und wasted_memory unter realer Last. opcache.max_accelerated_files muss die tatsächliche Dateianzahl des Projekts inklusive Vendor-Abhängigkeiten übersteigen, ermittelbar mit einem einfachen find-Befehl. opcache.validate_timestamps=0 spart den stat()-Overhead pro Request in Produktion, verlangt im Gegenzug einen zuverlässigen Cache-Invalidierungsschritt im Deployment-Prozess.

opcache.save_comments sollte aktiv bleiben, damit Reflection-basierte Bibliotheken funktionieren. Preloading und File Cache sind fortgeschrittene Hebel für zusätzliche Performance, bringen aber eigene Fallstricke mit, Zustandslecks bei Preloading, eingeschränkte Aktualität bei File Cache. Monitoring über opcache_get_status() macht die Wirkung jeder Einstellung messbar, statt sie zu erraten. Und beim Deployment gilt: Ein einzelner opcache_reset()-Aufruf in einem Multi-Worker-Pool ist riskant, ein koordinierter Rolling Restart ist die sichere Alternative für echtes Zero-Downtime-Deployment. OPcache-Tuning ist damit kein einmaliges Setzen von Werten, sondern ein fortlaufender Abgleich zwischen Konfiguration, Codebasis und Deployment-Prozess.

11. FAQ: OPcache-Tuning für Produktionsumgebungen