Lernseite · Caching, Logging und Fehlersuche
Schnell, nachvollziehbar, fehlerfrei: Caching, Logging und Fehlersuche in TYPO3
Eine gute TYPO3-Seite ist schnell, und wenn etwas schiefgeht, findest du die Ursache in Minuten. Dafür sorgen der Cache, das Log und die Fehlerbehandlung. Unser Beispiel ist die Extension my_extension mit einer Konferenzliste und einem nächtlichen Import.
Der Seitencache
Ein Cache speichert berechnete Ergebnisse, damit sie nicht jedes Mal neu entstehen. Das senkt Antwortzeit und Serverlast. Die Datenbank als dauerhafte Quelle ersetzt er nie. Die eigentliche Schwierigkeit ist die Invalidierung: Veraltete Einträge müssen rechtzeitig verschwinden, über Tags oder eine Lebensdauer.
Der wichtigste Cache heißt pages. Er speichert die fertig gerenderte Ausgabe einer Seite, standardmäßig in der Datenbanktabelle cache_pages. Ungecachte Teile wie ein USER_INT stehen dort nur als Platzhalter und werden bei jedem Aufruf nachgerendert. Sprache und Benutzergruppen trennt der Seitencache selbst. Das Caching von Extbase-Plugins behandelt der Kurs „Extbase: MVC, Plugins und Views“.
Leeren beim Speichern: Jede gecachte Seite trägt den Tag pageId_ mit ihrer UID. Ändert ein Redakteur einen Text auf Seite 12, leert der DataHandler genau diesen Tag. Andere Seiten bleiben gecacht.
Andere Seiten mit leeren: Die Startseite zeigt Teaser unserer Konferenzen aus dem Ordner 20. Speichert jemand dort eine Konferenz, bleibt die Startseite alt. Abhilfe schafft die Page TSconfig TCEMAIN.clearCacheCmd auf dem Ordner. Sie nennt Seiten, die zusätzlich geleert werden, mehrere durch Komma getrennt.
TCEMAIN.clearCacheCmd = 1Lebensdauer: Global gilt config.cache_period in Sekunden. Für eine einzelne Seite wählst du in den Seiteneigenschaften die Cache-Lebensdauer, zum Beispiel 15 Minuten. Der Wert der Seite hat Vorrang. Start- und Stoppzeiten der Inhalte auf der Seite beachtet TYPO3 ohnehin. Für Datensätze aus einem anderen Ordner nennst du Tabelle und Ordner in TypoScript. Dann verfällt der Cache genau, wenn die nächste Konferenz sichtbar wird.
config.cache.1 = tx_myextension_domain_model_conference:20Zeigt eine Seite nach dem Bearbeiten alten Inhalt, fehlt meist ein passender Tag oder ein clearCacheCmd. Oder ein vorgelagerter Proxy oder der Browser liefert noch die alte Kopie.
Das Caching Framework
Neben pages hat TYPO3 viele benannte Caches. Jeder besteht aus einem Frontend, das bestimmt, wie Daten übergeben werden, und einem Backend, das bestimmt, wo sie liegen. Ein Eintrag hat einen Identifier, Daten, eine Lebensdauer und beliebig viele Tags.
- Das
VariableFrontendserialisiert beliebige PHP-Werte. Es ist der Standard. - Das
PhpFrontendspeichert PHP-Code, den TYPO3 per require einbindet. Es braucht ein Backend, das PHP-Code ablegen kann, etwaFileBackendoderSimpleFileBackend.
Der Core bringt diese Backends mit: Typo3DatabaseBackend als Standard, FileBackend, SimpleFileBackend, RedisBackend, MemcachedBackend, ApcuBackend, TransientMemoryBackend und NullBackend. Das TransientMemoryBackend hält Werte nur für den laufenden Request. Das NullBackend speichert nichts. Das SimpleFileBackend kennt keine Tags.
Datei-Caches liegen in Composer-Installationen unter var/cache, solche mit PHP-Code in var/cache/code, alle anderen in var/cache/data. Der Ordner var liegt bewusst außerhalb des Web-Roots. Seinen Cache-Inhalt darfst du im Notfall löschen.
Jeder Cache gehört zu Gruppen. In pages liegen die Frontend-Caches wie pages und rootline. In system liegen Caches, deren Neuaufbau teuer ist, etwa core und fluid_template. lowlevel enthält Caches, die man nie von Hand leeren sollte, all steht für alle übrigen. Ein eigener Cache in der Gruppe pages wird mit dem Seitencache geleert.
Leeren: Auf der Kommandozeile leert cache:flush alle Caches. Der Befehl gehört in jedes Deployment. Mit der Option group leerst du nur eine Gruppe wie pages, system oder di. Neu in TYPO3 14 ist cache:flushtags zum Leeren nach Tag. cache:warmup baut Caches dagegen auf.
vendor/bin/typo3 cache:flush
vendor/bin/typo3 cache:flush --group pages
vendor/bin/typo3 cache:flushtags tx_myextension_conference_5composer clear-cache leert nur den Download-Cache von Composer. Einen Befehl cache:clear wie in Symfony gibt es nicht, einen URL-Parameter zum Leeren auch nicht.
Im Backend leert das Blitz-Symbol der Werkzeugleiste die Frontend-Caches oder alle Caches. Redakteure ohne Administratorrechte sehen den Eintrag für die Frontend-Caches nur mit der User TSconfig options.clearCache.pages. Entsprechend regelt options.clearCache.all das Leeren aller Caches. Das Modul Wartung hat die Karte „Flush TYPO3 and PHP Cache“. Sie leert zusätzlich den Opcode-Cache von PHP.
Ein eigener Cache für my_extension
Der Import speichert Konferenzen in einem eigenen Cache myextension_conferences. Du meldest ihn in ext_localconf.php an. Ohne weitere Angaben nutzt er das VariableFrontend und die Datenbank. Der Zuweisungsoperator mit doppeltem Fragezeichen lässt Administratoren die Einstellungen überschreiben.
$GLOBALS['TYPO3_CONF_VARS']['SYS']['caching']['cacheConfigurations']['myextension_conferences'] ??= [];Den Cache holst du per Dependency Injection. In der Services.yaml definierst du einen Service, den der CacheManager mit getCache() erzeugt. Den CacheManager selbst nutzt du nicht in ext_localconf.php. Der Core stellt etwa den Runtime-Cache genauso als cache.runtime bereit.
services:
cache.myextension_conferences:
class: TYPO3\CMS\Core\Cache\Frontend\FrontendInterface
factory: ['@TYPO3\CMS\Core\Cache\CacheManager', 'getCache']
arguments: ['myextension_conferences']Die Methode get() liefert false, wenn kein gültiger Eintrag existiert, nicht null. Darauf prüfst du, berechnest den Wert und speicherst ihn mit set(). Eine Prüfung mit has() ist unnötig und kann einen gerade abgelaufenen Eintrag treffen.
$id = 'list_' . $languageId . '_' . hash('xxh3', implode(',', $groupIds));
$value = $this->cache->get($id);
if ($value === false) {
$value = $this->buildList();
$this->cache->set($id, $value, ['tx_myextension_conference'], 86400);
}- Erlaubte Zeichen: Ein Identifier enthält nur Buchstaben, Ziffern, Unterstrich, Prozent, Minus und Und-Zeichen, höchstens 250 Zeichen. Fragezeichen oder Leerzeichen aus einer Suchanfrage führen zu einer InvalidArgumentException. Deshalb nimmt man ein Präfix plus Hash der Eingabe.
- Ganzer Kontext: Ein eigener Cache kennt weder Sprache noch Benutzergruppen. Heißt der Identifier nur
teaser_list, bekommen alle die zuerst erzeugte Liste, auch in falscher Sprache oder mit Mitglieder-Einträgen. - Tags und Lebensdauer: Der dritte Parameter vergibt Tags, der vierte die Lebensdauer in Sekunden. Fehlt sie, gilt die Voreinstellung des Backends. Mit
flushByTag()löschst du alle Einträge eines Tags. Lesen geht nur über den Identifier.
Brauchst du einen Wert nur mehrfach während eines Requests, nimm den Cache runtime. Er nutzt das TransientMemoryBackend.
Seiten markieren: Ändert der Import Konferenz 5, soll ihre Detailseite neu entstehen. Dafür gibt der Controller der Seite einen Tag. Im Frontend sammelt das Request-Attribut frontend.cache.collector alle Tags der Seite. Das frühere TSFE gibt es in TYPO3 14 nicht mehr.
$request->getAttribute('frontend.cache.collector')
->addCacheTags(new CacheTag('tx_myextension_conference_5'));Nach dem Import leert flushCachesInGroupByTags() die Einträge mit diesen Tags in allen Caches der Gruppe pages. flushCachesByTag() tut das in allen Caches. flushCaches() würde alles leeren und ist unnötig teuer. remove() erwartet dagegen den Identifier eines einzelnen Eintrags, keinen Tag.
Loggen nach PSR-3
TYPO3 loggt nach dem Standard PSR-3. Am einfachsten lässt du dir per Constructor Injection ein LoggerInterface geben. Der Logger heißt dann wie deine Klasse. Alternativ implementiert die Klasse LoggerAwareInterface mit dem LoggerAwareTrait, und der Container ruft setLogger() auf. Logger oder Writer selbst zu erzeugen, ist nicht vorgesehen.
public function __construct(private readonly LoggerInterface $logger) {}
try {
$this->importFile($file);
} catch (ImportFailedException $e) {
$this->logger->error('Import von {file} fehlgeschlagen', ['file' => $file, 'exception' => $e]);
}Weil der Code nur das Interface kennt, tauschst du die Implementierung, ohne die Klasse zu ändern. Im Test übergibst du einen NullLogger, der alles verwirft. Wohin geschrieben wird, legt PSR-3 nicht fest.
Platzhalter in geschweiften Klammern halten den Text gleich. Die Werte stehen im Kontext-Array, und die Writer setzen sie beim Schreiben ein. So kannst du gleichartige Einträge suchen und gruppieren. Verkettete Strings oder sprintf sind schlechter auswertbar. Eine Exception gehört in den Kontext unter dem Schlüssel exception. Eine Methode exception() gibt es nicht.
PSR-3 kennt acht Stufen aus RFC 5424. Jede hat eine eigene Methode, dazu kommt log() mit Stufe, Meldung und Kontext.
Überspringt der Import einen fehlerhaften Datensatz und läuft weiter, passt warning. Ist die Datenbank weg und die Website steht, ist das alert, denn jemand muss sofort handeln. emergency heißt: Das System ist unbenutzbar. Stufen wie fatal oder trace gibt es in PSR-3 nicht.
Wohin die Meldungen gehen
Ohne eigene Konfiguration schreibt der FileWriter alle Einträge ab warning in eine Datei typo3_ plus Hash im Ordner var/log. In Classic-Installationen ist das typo3temp/var/log. Meldungen mit debug() werden also verworfen, bis du sie freischaltest.
Writer bestimmen das Ziel. FileWriter und RotatingFileWriter schreiben in Dateien. Der DatabaseWriter schreibt in die Tabelle sys_log, sichtbar im Modul Administration, Log. Der SyslogWriter schreibt ins Syslog des Betriebssystems, der PhpErrorLogWriter ins Fehlerlog von PHP. Seit TYPO3 14.2 ist die Option logTable des DatabaseWriter veraltet. Für eine eigene Tabelle leitest du einen Writer von AbstractWriter ab.
Konfiguriert wird im Bereich LOG von TYPO3_CONF_VARS, nach Namensraum und Stufe. Diese Zeile gilt für alle Klassen unter MyVendor\ ab info:
$GLOBALS['TYPO3_CONF_VARS']['LOG']['MyVendor']['MyExtension']['writerConfiguration'][LogLevel::INFO][FileWriter::class] = ['logFileInfix' => 'myextension'];- Die Einträge landen in einer Datei wie
typo3_myextension_plus Hash. - Eine Stufe gilt für sich und alle schwereren. Ein Writer unter
ERRORnimmt also keinewarning. - Der LogManager sucht von allgemein nach speziell die genaueste Konfiguration. Sie ersetzt die globale, beide gelten nicht zusammen.
Kanäle: Sollen Klassen aus verschiedenen Namensräumen gemeinsam in eine Datei security.log schreiben, legst du ihre Logger mit dem Attribut Channel in einen Kanal security. Unter diesem Namen sucht TYPO3 dann die Konfiguration.
Processors reichern Einträge an. Der IntrospectionProcessor ergänzt Datei, Zeile, Klasse und Funktion des Aufrufers. Andere ergänzen Speicherverbrauch oder Request-Daten. Sie stehen unter processorConfiguration.
Ein Eintrag ist ein LogRecord aus requestId, Erstellungszeit, Komponente, Stufe, Meldung und Daten.
Fehler zeigen oder verbergen
Auf dem Live-Server gilt der Application Context Production. Besucher sehen bei Fehlern nur eine knappe Meldung, keine Pfade oder SQL-Abfragen. Im Context Development erscheinen Details mit Datei und Zeile. Öffentlich wäre das ein Sicherheitsrisiko. Den Cache schaltet Development nicht ab.
Welcher Handler eine Exception darstellt, entscheidet displayErrors unter SYS:
Die Einstellung exceptionalErrors legt fest, welche PHP-Fehler zu Exceptions werden. Einen eigenen productionExceptionHandler trägst du in config/system/additional.php ein. In ext_localconf.php wäre es zu spät, weil TYPO3 die Handler vorher einrichtet.
Am schnellsten schaltest du im Modul System, Settings unter „Configuration Presets“ um. Das Preset Debug setzt displayErrors auf 1 und devIPmask auf Stern, schaltet die Debug-Optionen für Frontend und Backend ein und aktiviert das Deprecation-Log. Das Preset Live schaltet all das ab. Öffentliche Systeme laufen immer mit Live.
Fehler in einem Plugin: Im Production-Kontext ersetzt ein eigener Handler nur das betroffene Inhaltselement durch „Oops, an error occurred!“ mit einer Kennung. In TYPO3 14 ist das die Request-ID. Mit ihr findest du den Eintrag im Log. Mit config.contentObjectExceptionHandler auf 0 siehst du stattdessen die Exception mit Stacktrace. Live bleibt der Handler aktiv, höchstens für Administratoren schaltest du ihn per Bedingung ab.
Fehlerseiten: In der Site-Konfiguration wählst du unter errorHandling je HTTP-Code einen Handler. Page zeigt eine TYPO3-Seite aus errorContentSource, die Redakteure normal pflegen. Fluid rendert die Datei aus errorFluidTemplate. PHP ruft eine Klasse aus errorPhpClassFQCN auf, die mit PageErrorHandlerInterface und handlePageError() eine eigene Response liefert. Eine Seite namens 404 oder ein ErrorDocument in der htaccess bewirken nichts.
errorHandling:
- errorCode: 404
errorHandler: Page
errorContentSource: 't3://page?uid=42'
- errorCode: 503
errorHandler: Fluid
errorFluidTemplate: 'EXT:site/Resources/Private/Templates/Error503.fluid.html'Muss ein Controller sofort die 403-Seite ausgeben, erzeugt er die Response mit accessDeniedAction() des ErrorController und wirft sie als PropagateResponseException. Die Middleware ResponsePropagation fängt sie.
Fehler finden
Wo nachsehen? Zuerst in den TYPO3-Logs unter var/log. Eine weiße Seite entsteht meist durch einen Fatal Error, bevor TYPO3 etwas ausgeben kann. Dann helfen das PHP-Fehlerlog und das error.log von Apache oder nginx unter /var/log. Wohin PHP schreibt, legt error_log in der php.ini fest. Ist die Datenbank erreichbar, zeigt das Modul Administration, Log die Tabelle sys_log. Die Tabelle sys_history enthält nur Änderungen an Datensätzen.
Stacktrace lesen: Oben steht die Stelle, an der die Exception geworfen wurde, darunter die Aufrufer. Die erste Zeile aus eigenem Code ist oft der beste Einstieg. Den Exception-Code von TYPO3 kannst du gezielt suchen.
Werte ansehen:
- Im Fluid-Template zeigt der ViewHelper
f:debugeine Variable mit Typ und Eigenschaften, mit inline gleich 1 an Ort und Stelle. Einen ViewHelperf:dumpgibt es nicht. DebuggerUtility::var_dump()aus Extbase zeigt Objekte samt Lazy-Proxies. Die Tiefe ist auf 8 begrenzt, maxDepth und Listen auszublendender Klassen und Eigenschaften verkleinern die Ausgabe. Auf der Kommandozeile liefert plainText Text statt HTML, ansiColors färbt ihn. Mit return bekommst du einen String.- Die globale Funktion
debug()gibt nur etwas aus, wenn die IP aufdevIPmaskpasst. - In PHP zeigt
var_dump()auch Typen und Längen.print_r()mit true als zweitem Parameter liefert einen String. Ein echo auf ein Array liefert nur das Wort Array. Exit oder die beenden das Skript sofort.
Aus gecachten Seiten erscheinen Debug-Ausgaben nicht erneut. Auf Live-Systeme gehören sie nicht.
php -l Classes/Service/ConferenceImporter.php
xdebug.mode=debug
xdebug.start_with_request=triggerDer Lint-Befehl php -l meldet nur Syntaxfehler und führt den Code nicht aus. Eine fehlende Klasse findet er deshalb nicht. Xdebug 3 schaltest du mit dem Modus debug ein. Mit dem Startwert trigger beginnt eine Sitzung nur, wenn die Anfrage XDEBUG_TRIGGER als Cookie oder Parameter mitbringt. Die IDE lauscht auf Port 9003, Port 9000 galt für Xdebug 2. An einem Breakpoint untersuchst du Variablen und Call Stack und gehst schrittweise weiter. Xdebug bremst und gehört nicht auf Live-Systeme.
Eigene Exceptions: Wirf eigene Klassen wie ImportFailedException, die von RuntimeException erben. Dann können Aufrufer gezielt fangen. Der Code ist meist ein Unix-Zeitstempel. Die Klasse Error ist für Fehler der PHP-Engine gedacht. Exception und Error implementieren beide Throwable, aber Error erbt nicht von Exception. Ein catch für Exception fängt also keinen TypeError. Fang nur dort, wo du sinnvoll reagieren kannst, nie mit leerem catch-Block.
try {
$this->readRows($handle);
} catch (\JsonException $e) {
throw new ImportFailedException('Datei nicht lesbar', 1763197200, $e);
} finally {
fclose($handle);
}Mit der alten Exception als previous liefert getPrevious() später die Ursache. Der finally-Block läuft immer, deshalb gehört fclose dorthin.
- Mach den Fehler mit minimalen Schritten reproduzierbar.
- Setz Log-Ausgaben oder Breakpoints an die entscheidenden Stellen.
- Ging es früher, findet git bisect die schuldige Änderung.
- Halte den Fall danach als Test fest.
Langsame Seiten untersuchen
Einen ersten Wert liefert TYPO3 selbst: Steht debug im Bereich FE auf true, sendet es den Header X-TYPO3-Parsetime mit der Renderzeit.
Mehr zeigt das Admin Panel, eine Leiste unten im Frontend aus der Systemerweiterung adminpanel. Mit dem Backend-Modul Administration hat es nichts zu tun. Es erscheint nur unter drei Bedingungen:
- Du bist im selben Browser im Backend angemeldet. Eine Frontend-Anmeldung reicht nicht.
- In der User TSconfig ist mindestens ein Modul aktiv, etwa mit
admPanel.enable.all. Administratoren haben das standardmäßig. - Im TypoScript steht
config.admPanelauf 1.
Der Application Context spielt keine Rolle. Das Modul Info zeigt Cache-Status und die Zahl der USER_INT-Objekte. Das Modul TypoScript zeigt Laufzeiten. Das Modul Debug zeigt PSR-14-Events, Log-Einträge und alle SQL-Abfragen. In der Vorschau blendet das Panel auch Verstecktes ein.
Eigene Module meldest du in ext_localconf.php an, im Bereich EXTCONF unter adminpanel und modules, mit der Klasse unter module und optional before oder after. Das Modul implementiert ModuleInterface, meist über AbstractModule. Das ShortInfoProviderInterface liefert eine Kurzinfo für die Leiste, das ResourceProviderInterface eigenes CSS und JavaScript. Das ModuleSettingsProviderInterface bietet Einstellungen an, die der Benutzer im Panel setzt. Das RequestEnricherInterface ergänzt den Request vor dem Rendern, das DataProviderInterface sammelt Daten für die Anzeige.
Das Wichtigste in Kürze
- Speichern leert den Tag der Seite, weitere Seiten leert
TCEMAIN.clearCacheCmd. - Eigene Caches meldest du in
ext_localconf.phpan und holst sie per Dependency Injection.get()liefertfalse, wenn nichts da ist. - Ein Identifier enthält nur einfache Zeichen und alles, wovon das Ergebnis abhängt.
cache:flushleert alles,cache:flushtagsseit TYPO3 14 nach Tag.- Logger per Injection, Platzhalter im Text, Werte und Exception im Kontext.
- Standardmäßig wird ab
warningnachvar/loggeschrieben. Die genaueste Writer-Konfiguration ersetzt die allgemeine. displayErrorsunddevIPmaskwählen den Exception-Handler. Live gilt das Preset Live.- Das Admin Panel braucht Backend-Anmeldung, User TSconfig und
config.admPanel.
Begriffe
- Cache-Tag
- Markierung, über die man viele Cache-Einträge auf einmal löscht.
- Cache-Gruppe
- Caches, die gemeinsam geleert werden, etwa pages oder system.
- devIPmask
- IP-Adressen, die Entwicklerausgaben sehen dürfen.
- N+1-Problem
- Eine Abfrage für die Liste und eine weitere je Eintrag.
- Processor
- Ergänzt einen Log-Eintrag vor dem Schreiben um Daten.
- Writer
- Bestimmt, wohin ein Log-Eintrag geschrieben wird.