Attention
TYPO3 v11 has reached end-of-life as of October 31th 2024 and is no longer being maintained. Use the version switcher on the top left of this page to select documentation for a supported version of TYPO3.
Need more time before upgrading? You can purchase Extended Long Term Support (ELTS) for TYPO3 v11 here: TYPO3 ELTS.
Log writers
The purpose of a log writer is (usually) to save all log records into a persistent storage, like a log file, a database table, or to a remote syslog server.
Different log writers offer possibilities to log into different targets. Custom log writers can extend the functionality shipped with TYPO3 Core.
Table of Contents
Built-in log writers
This section describes the log writers shipped with the TYPO3 Core. Some writers have options to allow customization of the particular writer. See the configuration section on how to use these options.
DatabaseWriter
The database writer logs into a database table. This table has to reside in the database used by TYPO3 and is not automatically created.
The following option is available:
logTable
-
- Type
- string
- Mandatory
- no
- Default
sys_
log
The database table to write to.
Warning
The Admin Tools > Log module is not adapted to the records written by the
Database
into theWriter sys_
table. If you write such records there, you will not be able to see them using that module.log Tip
There is the third-party extension EXT:logs available for viewing such records in the TYPO3 backend.
Example of a
CREATE TABLE
statement forlog
:Table # # Table structure for table 'tx_examples_log' # # The KEY on request_id is optional # CREATE TABLE tx_examples_log ( request_id varchar(13) DEFAULT '' NOT NULL, time_micro double(16,4) NOT NULL default '0.0000', component varchar(255) DEFAULT '' NOT NULL, level tinyint(1) unsigned DEFAULT '0' NOT NULL, message text, data text, KEY request (request_id) );
Copied!The corresponding configuration might look like this for the example class
\T3docs\
:Examples\ Controller use TYPO3\CMS\Core\Log\LogLevel; use TYPO3\CMS\Core\Log\Writer\DatabaseWriter; $GLOBALS['TYPO3_CONF_VARS']['LOG']['T3docs']['Examples']['Controller']['writerConfiguration'] = [ LogLevel::DEBUG => [ DatabaseWriter::class => [ 'logTable' => 'tx_examples_log', ], ], ];
Copied!
Warning
If you are using a MariaDB Galera Cluster you should definitely add a
primary key field to the database definition, since it is required by
Galera (this can be a normal uid
autoincrement field as known from
other tables):
MariaDB Galera Cluster - Known Limitations.
FileWriter
The file writer logs into a log file, one log record per line. If the log file does not exist, it will be created (including parent directories, if needed).
Please make sure:
- Your web server has write permissions to that path.
- The path is below the root directory of your website (defined by Environment::getPublicPath()).
The filename is appended with a hash, that depends on the
encryption key. If
$GLOBALS['TYPO3_CONF_VARS']['SYS']['generateApacheHtaccess']
is set, an .htaccess
file is added to the directory. It protects your
log files from being accessed from the web. If the log
option is not
set, TYPO3 will use a filename containing a random hash, like
typo3temp/
.
The following options are available:
logFile
-
- Type
- string
- Mandatory
- no
- Default
typo3temp/
(for example, likelogs/ typo3_<hash>. log typo3temp/
)logs/ typo3_ 7ac500bce5. log
The path to the log file.
logFileInfix
-
- Type
- string
- Mandatory
- no
- Default
- (empty string)
This option allows to set a different name for the log file that is created by the
File
without having to define a full path to the file. For example, the settingsWriter 'log
results inFile Infix' => 'special' typo3_
.special_<hash>. log
The corresponding configuration might look like this for the example class
\T3docs\
:
use TYPO3\CMS\Core\Core\Environment;
use TYPO3\CMS\Core\Log\LogLevel;
use TYPO3\CMS\Core\Log\Writer\FileWriter;
// Add example configuration for the logging API
$GLOBALS['TYPO3_CONF_VARS']['LOG']['T3docs']['Examples']['Controller']['writerConfiguration'] = [
// configuration for ERROR level log entries
LogLevel::ERROR => [
// Add a FileWriter
FileWriter::class => [
// Configuration for the writer
'logFile' => Environment::getVarPath() . '/log/typo3_examples.log',
],
],
];
PhpErrorLogWriter
This writer logs into the PHP error log using error_log()
SyslogWriter
The syslog writer logs into the syslog (Unix only).
The following option is available:
facility
-
- Type
- string
- Mandatory
- no
- Default
USER
The syslog facility to log into.
Custom log writers
Custom log writers can be added through extensions. Every log writer has to implement the interface EXT:core/Classes/Log/Writer/WriterInterface.php (GitHub). It is suggested to extend the abstract class EXT:core/Classes/Log/Writer/AbstractWriter.php (GitHub) which allows you to use configuration options by adding the corresponding properties and setter methods.
Please keep in mind that TYPO3 will silently continue operating, in case a log
writer is throwing an exception while executing the write
method.
Only in the case that all registered writers fail, the log entry with additional
information will be added to the configured fallback logger (which defaults to
the PhpErrorLog writer).
Usage in a custom class
All log writers can be used in your own classes. If the service is configured to
use autowiring you can inject a logger into the __
method of
your class \My
) since TYPO3 v11 LTS.
<?php
declare(strict_types=1);
namespace MyVendor\MyExtension;
use Psr\Log\LoggerInterface;
final class MyClass
{
private LoggerInterface $logger;
public function __construct(LoggerInterface $logger)
{
$this->logger = $logger;
}
public function doSomething()
{
$this->logger->info('My class is executed.');
$error = false;
// ... something is done ...
if ($error) {
$this->logger->error('Error in class MyClass');
}
}
}
If autowiring is disabled, the service class however must implement the
interface \Psr\
and use the
\Psr\
.
<?php
declare(strict_types=1);
namespace MyVendor\MyExtension;
use Psr\Log\LoggerAwareInterface;
use Psr\Log\LoggerAwareTrait;
final class MyClass implements LoggerAwareInterface
{
use LoggerAwareTrait;
public function doSomething()
{
$this->logger->info('My class is executed.');
$error = false;
// ... something is done ...
if ($error) {
$this->logger->error('Error in class MyClass');
}
}
}
One or more log writers for this class are configured in the file
ext_
:
use TYPO3\CMS\Core\Core\Environment;
use TYPO3\CMS\Core\Log\LogLevel;
use TYPO3\CMS\Core\Log\Writer\FileWriter;
// Add example configuration for the logging API
$GLOBALS['TYPO3_CONF_VARS']['LOG']['MyVendor']['MyExtension']['MyClass']['writerConfiguration'] = [
// Configuration for ERROR level log entries
LogLevel::ERROR => [
// Add a FileWriter
FileWriter::class => [
// Configuration for the writer
'logFile' => Environment::getVarPath() . '/log/my_extension.log',
],
],
];
Examples
Working examples of the usage of different Log writers can be found in the extension EXT:examples.