Study guide · Caching, Logging and Debugging
Fast, traceable, error-free: Caching, logging and debugging in TYPO3
A good TYPO3 site is fast, and when something goes wrong, you find the cause in minutes. The cache, the log and error handling make this possible. Our example is the extension my_extension with a conference list and a nightly import.
The page cache
A cache stores computed results so they are not produced again every time. This lowers response time and server load. It never replaces the database as the permanent source. The real difficulty is invalidation: outdated entries must disappear in time, through tags or a lifetime.
The most important cache is called pages. It stores the fully rendered output of a page, by default in the database table cache_pages. Uncached parts such as a USER_INT are only placeholders there and are rendered again on every request. The page cache separates languages and user groups by itself. Caching of Extbase plugins is covered in the course “Extbase: MVC, Plugins und Views”.
Flushing on save: Every cached page carries the tag pageId_ followed by its UID. When an editor changes a text on page 12, the DataHandler flushes exactly this tag. Other pages stay cached.
Flushing other pages too: The home page shows teasers of our conferences from folder 20. When someone saves a conference there, the home page stays outdated. The page TSconfig TCEMAIN.clearCacheCmd on the folder fixes this. It lists pages that are flushed as well, several separated by commas.
TCEMAIN.clearCacheCmd = 1Lifetime: Globally, config.cache_period applies, in seconds. For a single page you choose the cache lifetime in the page properties, for example 15 minutes. The value of the page takes precedence. TYPO3 already respects start and stop times of the content on the page. For records from another folder you name the table and the folder in TypoScript. Then the cache expires exactly when the next conference becomes visible.
config.cache.1 = tx_myextension_domain_model_conference:20If a page shows old content after editing, usually a matching tag or a clearCacheCmd is missing. Or an upstream proxy or the browser still delivers the old copy.
The Caching Framework
Besides pages, TYPO3 has many named caches. Each one consists of a frontend, which defines how data is passed in, and a backend, which defines where it is stored. An entry has an identifier, data, a lifetime and any number of tags.
- The
VariableFrontendserializes any PHP value. It is the default. - The
PhpFrontendstores PHP code that TYPO3 includes with require. It needs a backend that can store PHP code, such asFileBackendorSimpleFileBackend.
The Core ships these backends: Typo3DatabaseBackend as the default, FileBackend, SimpleFileBackend, RedisBackend, MemcachedBackend, ApcuBackend, TransientMemoryBackend and NullBackend. The TransientMemoryBackend keeps values only for the current request. The NullBackend stores nothing. The SimpleFileBackend does not support tags.
In Composer installations, file caches live in var/cache, those with PHP code in var/cache/code, all others in var/cache/data. The folder var is deliberately outside the web root. In an emergency you may delete its cache contents.
Every cache belongs to groups. The group pages holds the frontend caches such as pages and rootline. The group system holds caches that are expensive to rebuild, such as core and fluid_template. lowlevel holds caches you should never flush by hand, and all stands for all the others. A custom cache in the group pages is flushed together with the page cache.
Flushing: On the command line, cache:flush flushes all caches. The command belongs in every deployment. With the option group you flush only one group, such as pages, system or di. New in TYPO3 14 is cache:flushtags for flushing by tag. cache:warmup, in contrast, builds caches up.
vendor/bin/typo3 cache:flush
vendor/bin/typo3 cache:flush --group pages
vendor/bin/typo3 cache:flushtags tx_myextension_conference_5composer clear-cache only flushes the download cache of Composer. There is no command cache:clear like in Symfony, and no URL parameter for flushing either.
In the backend, the lightning icon in the toolbar flushes the frontend caches or all caches. Editors without admin rights only see the entry for the frontend caches with the user TSconfig options.clearCache.pages. In the same way, options.clearCache.all controls flushing all caches. The Maintenance module has the card “Flush TYPO3 and PHP Cache”. It also flushes the PHP opcode cache.
A custom cache for my_extension
The import stores conferences in a custom cache myextension_conferences. You register it in ext_localconf.php. Without further settings it uses the VariableFrontend and the database. The assignment operator with a double question mark lets administrators override the settings.
$GLOBALS['TYPO3_CONF_VARS']['SYS']['caching']['cacheConfigurations']['myextension_conferences'] ??= [];You get the cache through dependency injection. In Services.yaml you define a service that the CacheManager creates with getCache(). Do not use the CacheManager itself in ext_localconf.php. The Core provides the runtime cache the same way, as cache.runtime.
services:
cache.myextension_conferences:
class: TYPO3\CMS\Core\Cache\Frontend\FrontendInterface
factory: ['@TYPO3\CMS\Core\Cache\CacheManager', 'getCache']
arguments: ['myextension_conferences']The method get() returns false if no valid entry exists, not null. You check for that, compute the value and store it with set(). A check with has() is unnecessary and can hit an entry that has just expired.
$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);
}- Allowed characters: An identifier contains only letters, digits, underscore, percent, minus and ampersand, with at most 250 characters. Question marks or spaces from a search query lead to an InvalidArgumentException. That is why you use a prefix plus a hash of the input.
- Full context: A custom cache knows neither the language nor the user groups. If the identifier is just
teaser_list, everyone gets the list built first, even in the wrong language or with members-only entries. - Tags and lifetime: The third parameter sets tags, the fourth the lifetime in seconds. Without it, the default of the backend applies. With
flushByTag()you delete all entries of a tag. Reading only works through the identifier.
If you need a value several times during one request only, use the cache runtime. It uses the TransientMemoryBackend.
Tagging pages: When the import changes conference 5, its detail page should be rebuilt. To do this, the controller gives the page a tag. In the frontend, the request attribute frontend.cache.collector collects all tags of the page. The former TSFE no longer exists in TYPO3 14.
$request->getAttribute('frontend.cache.collector')
->addCacheTags(new CacheTag('tx_myextension_conference_5'));After the import, flushCachesInGroupByTags() flushes the entries with these tags in all caches of the group pages. flushCachesByTag() does this in all caches. flushCaches() would flush everything and is needlessly expensive. remove(), in contrast, expects the identifier of a single entry, not a tag.
Logging with PSR-3
TYPO3 logs according to the PSR-3 standard. The easiest way is to have a LoggerInterface injected through the constructor. The logger is then named after your class. Alternatively the class implements LoggerAwareInterface with the LoggerAwareTrait, and the container calls setLogger(). Creating loggers or writers yourself is not intended.
public function __construct(private readonly LoggerInterface $logger) {}
try {
$this->importFile($file);
} catch (ImportFailedException $e) {
$this->logger->error('Import of {file} failed', ['file' => $file, 'exception' => $e]);
}Because the code only knows the interface, you can swap the implementation without changing the class. In a test you pass a NullLogger, which discards everything. PSR-3 does not define where messages are written.
Placeholders in curly braces keep the text the same. The values go into the context array, and the writers fill them in when writing. That way you can search and group similar entries. Concatenated strings or sprintf are harder to analyse. An exception belongs in the context under the key exception. There is no method exception().
PSR-3 knows eight levels from RFC 5424. Each has its own method, plus log() with level, message and context.
If the import skips a broken record and continues, warning fits. If the database is gone and the site is down, that is alert, because someone must act immediately. emergency means the system is unusable. Levels such as fatal or trace do not exist in PSR-3.
Where the messages go
Without its own configuration, the FileWriter writes all entries from warning upwards to a file typo3_ plus hash in the folder var/log. In classic installations this is typo3temp/var/log. So messages from debug() are discarded until you enable them.
Writers decide the target. FileWriter and RotatingFileWriter write to files. The DatabaseWriter writes to the table sys_log, visible in the module Administration, Log. The SyslogWriter writes to the syslog of the operating system, the PhpErrorLogWriter to the PHP error log. Since TYPO3 14.2 the option logTable of the DatabaseWriter is deprecated. For a custom table you derive a writer from AbstractWriter.
Configuration lives in the LOG section of TYPO3_CONF_VARS, by namespace and level. This line applies to all classes under MyVendor\ from info upwards:
$GLOBALS['TYPO3_CONF_VARS']['LOG']['MyVendor']['MyExtension']['writerConfiguration'][LogLevel::INFO][FileWriter::class] = ['logFileInfix' => 'myextension'];- The entries end up in a file such as
typo3_myextension_plus hash. - A level applies to itself and all more severe levels. A writer under
ERRORtherefore takes nowarning. - The LogManager searches from general to specific for the most specific configuration. It replaces the global one, and the two do not apply together.
Channels: If classes from different namespaces should write together to a file security.log, you put their loggers into a channel security with the attribute Channel. TYPO3 then looks up the configuration under this name.
Processors enrich entries. The IntrospectionProcessor adds file, line, class and function of the caller. Others add memory usage or request data. They live under processorConfiguration.
An entry is a LogRecord made of requestId, creation time, component, level, message and data.
Showing or hiding errors
On the live server the application context Production applies. On errors, visitors only see a short message, no paths or SQL queries. In the context Development, details with file and line appear. In public that would be a security risk. Development does not switch off the cache.
Which handler displays an exception is decided by displayErrors under SYS:
The setting exceptionalErrors defines which PHP errors become exceptions. You register a custom productionExceptionHandler in config/system/additional.php. In ext_localconf.php it would be too late, because TYPO3 sets up the handlers before that.
The fastest way to switch is in the module System, Settings under “Configuration Presets”. The preset Debug sets displayErrors to 1 and devIPmask to an asterisk, switches on the debug options for frontend and backend and enables the deprecation log. The preset Live switches all of this off. Public systems always run with Live.
Errors in a plugin: In the production context, a separate handler replaces only the affected content element with “Oops, an error occurred!” and an identifier. In TYPO3 14 this is the request ID. With it you find the entry in the log. With config.contentObjectExceptionHandler set to 0 you see the exception with stack trace instead. On live systems the handler stays active. At most you switch it off for administrators with a condition.
Error pages: In the site configuration you choose a handler per HTTP code under errorHandling. Page shows a TYPO3 page from errorContentSource, which editors maintain as usual. Fluid renders the file from errorFluidTemplate. PHP calls a class from errorPhpClassFQCN, which returns its own response through PageErrorHandlerInterface and handlePageError(). A page named 404 or an ErrorDocument in the htaccess file has no effect.
errorHandling:
- errorCode: 404
errorHandler: Page
errorContentSource: 't3://page?uid=42'
- errorCode: 503
errorHandler: Fluid
errorFluidTemplate: 'EXT:site/Resources/Private/Templates/Error503.fluid.html'If a controller must output the 403 page immediately, it creates the response with accessDeniedAction() of the ErrorController and throws it as a PropagateResponseException. The middleware ResponsePropagation catches it.
Finding errors
Where to look? First in the TYPO3 logs in var/log. A white page is usually caused by a fatal error before TYPO3 can output anything. Then the PHP error log and the error.log of Apache or nginx in /var/log help. Where PHP writes is set by error_log in the php.ini. If the database is reachable, the module Administration, Log shows the table sys_log. The table sys_history only contains changes to records.
Reading a stack trace: At the top is the place where the exception was thrown, below it the callers. The first line from your own code is often the best starting point. You can search for the TYPO3 exception code directly.
Looking at values:
- In a Fluid template, the ViewHelper
f:debugshows a variable with type and properties, and with inline set to 1 right in place. There is no ViewHelperf:dump. DebuggerUtility::var_dump()from Extbase shows objects including lazy proxies. The depth is limited to 8, and maxDepth plus lists of class and property names to hide make the output smaller. On the command line, plainText gives text instead of HTML, and ansiColors adds colour. With return you get a string.- The global function
debug()only outputs something if the IP matchesdevIPmask. - In PHP,
var_dump()also shows types and lengths.print_r()with true as the second parameter returns a string. An echo on an array only prints the word Array. Exit or die end the script immediately.
Debug output does not appear again from cached pages. It does not belong on live systems.
php -l Classes/Service/ConferenceImporter.php
xdebug.mode=debug
xdebug.start_with_request=triggerThe lint command php -l only reports syntax errors and does not run the code. That is why it does not find a missing class. You switch on Xdebug 3 with the mode debug. With the start value trigger, a session only begins when the request carries XDEBUG_TRIGGER as a cookie or parameter. The IDE listens on port 9003, port 9000 was for Xdebug 2. At a breakpoint you inspect variables and the call stack and continue step by step. Xdebug slows things down and does not belong on live systems.
Your own exceptions: Throw your own classes such as ImportFailedException, which extend RuntimeException. Then callers can catch them specifically. The code is usually a Unix timestamp. The class Error is meant for errors of the PHP engine. Exception and Error both implement Throwable, but Error does not extend Exception. So a catch for Exception does not catch a TypeError. Only catch where you can react sensibly, never with an empty catch block.
try {
$this->readRows($handle);
} catch (\JsonException $e) {
throw new ImportFailedException('File not readable', 1763197200, $e);
} finally {
fclose($handle);
}With the old exception as previous, getPrevious() later returns the cause. The finally block always runs, which is why fclose belongs there.
- Make the error reproducible with minimal steps.
- Put log output or breakpoints at the decisive places.
- If it used to work, git bisect finds the change to blame.
- Afterwards, keep the case as a test.
Investigating slow pages
TYPO3 itself gives you a first value: if debug in the FE section is set to true, it sends the header X-TYPO3-Parsetime with the rendering time.
The Admin Panel shows more. It is a bar at the bottom of the frontend from the system extension adminpanel. It has nothing to do with the backend module Administration. It only appears under three conditions:
- You are logged in to the backend in the same browser. A frontend login is not enough.
- In user TSconfig at least one module is enabled, for example with
admPanel.enable.all. Administrators have this by default. - In TypoScript,
config.admPanelis set to 1.
The application context does not matter. The Info module shows the cache status and the number of USER_INT objects. The TypoScript module shows run times. The Debug module shows PSR-14 events, log entries and all SQL queries. In the preview, the panel also shows hidden content.
You register custom modules in ext_localconf.php, in the EXTCONF section under adminpanel and modules, with the class under module and optionally before or after. The module implements ModuleInterface, usually through AbstractModule. The ShortInfoProviderInterface provides a short info for the bar, the ResourceProviderInterface its own CSS and JavaScript. The ModuleSettingsProviderInterface offers settings that the user sets in the panel. The RequestEnricherInterface enriches the request before rendering, and the DataProviderInterface collects data for display.
Key points
- Saving flushes the tag of the page, and
TCEMAIN.clearCacheCmdflushes further pages. - You register custom caches in
ext_localconf.phpand get them through dependency injection.get()returnsfalseif nothing is there. - An identifier contains only simple characters and everything the result depends on.
cache:flushflushes everything, and since TYPO3 14cache:flushtagsflushes by tag.- Logger through injection, placeholders in the text, values and exception in the context.
- By default, entries from
warningupwards go tovar/log. The most specific writer configuration replaces the general one. displayErrorsanddevIPmaskchoose the exception handler. On live systems the preset Live applies.- The Admin Panel needs a backend login, user TSconfig and
config.admPanel.
Terms
- Cache tag
- A label that lets you delete many cache entries at once.
- Cache group
- Caches that are flushed together, such as pages or system.
- devIPmask
- IP addresses that may see developer output.
- N+1 problem
- One query for the list and another one for each entry.
- Processor
- Adds data to a log entry before it is written.
- Writer
- Decides where a log entry is written.