Logger

Instantiation

Constructor injection can be used to automatically instantiate the logger:

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Service;

use Psr\Log\LoggerInterface;

class MyClass
{
    public function __construct(
        private readonly LoggerInterface $logger,
    ) {}
}

The log() method

The \TYPO3\CMS\Core\Log\Logger class provides a central point for submitting log messages, the log() method:

$this->logger->log($level, $message, $data);

which takes three parameters:

An early return in the log() method prevents unneeded computation work to be done. So you are safe to call the logger with the debug log level frequently without slowing down your code too much. The logger will know by its configuration, what the most explicit severity level is.

As a next step, all registered processors are notified. They can modify the log records or add extra information.

The logger then forwards the log records to all of its configured writers, which will then persist the log record.

Log levels and shorthand methods

The log levels - according to RFC 3164 - start from the lowest level. For each of the severity levels mentioned below, a shorthand method exists in \TYPO3\CMS\Core\Log\Logger :

Debug

Class constant

\Psr\Log\LogLevel::DEBUG

Shorthand method

$this->logger->debug($message, $context);

For debug information: give detailed status information during the development of PHP code.

Informational

Class constant

\Psr\Log\LogLevel::INFO

Shorthand method

$this->logger->info($message, $context);

For informational messages, some examples:

• A user logs in.
• Connection to third-party system established.
• Logging of SQL statements.

Notice

Class constant

\Psr\Log\LogLevel::NOTICE

Shorthand method

$this->logger->notice($message, $context);

For significant conditions. Things you should have a look at, nothing to worry about though. Some examples:

• A user logs in.
• Logging of SQL statements.

Warning

Class constant

\Psr\Log\LogLevel::WARNING

Shorthand method

$this->logger->warning($message, $context);

For warning conditions. Some examples:

• Use of a deprecated method.
• Undesirable events that are not necessarily wrong.

Error

Class constant

\Psr\Log\LogLevel::ERROR

Shorthand method

$this->logger->error($message, $context);

For error conditions. Some examples:

• A runtime error occurred.
• Some PHP coding error has happened.
• A white screen is shown.

Critical

Class constant

\Psr\Log\LogLevel::CRITICAL

Shorthand method

$this->logger->critical($message, $context);

For critical conditions. Some examples:

• An unexpected exception occurred.
• An important file has not been found.
• Data is corrupt or outdated.

Alert

Class constant

\Psr\Log\LogLevel::ALERT

Shorthand method

$this->logger->alert($message, $context);

For blocking conditions, action must be taken immediately. Some examples:

• The entire website is down.
• The database is unavailable.

Emergency

Class constant

\Psr\Log\LogLevel::EMERGENCY

Shorthand method

$this->logger->emergency($message, $context);

Nothing works, the system is unusable. You will likely not be able to reach

the system. You better have a system administrator reachable when this happens.

Channels

It is possible to group several classes into channels, regardless of the PHP namespace.

Services are able to control the component name that an injected logger is created with. This allows to group logs of related classes and is basically a channel system as often used in Monolog.

The \TYPO3\CMS\Core\Log\Channel attribute is supported for constructor argument injection as a class and parameter-specific attribute and for \Psr\Log\LoggerAwareInterface dependency injection services as a class attribute.

Registration via class attribute for \Psr\Log\LoggerInterface injection:

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Service\MyClass;

use Psr\Log\LoggerInterface;
use TYPO3\CMS\Core\Log\Channel;

#[Channel('security')]
class MyClass
{
    public function __construct(
        private readonly LoggerInterface $logger,
    ) {}
}

Registration via parameter attribute for \Psr\Log\LoggerInterface injection, overwrites possible class attributes:

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Service\MyClass;

use Psr\Log\LoggerInterface;
use TYPO3\CMS\Core\Log\Channel;

class MyClass
{
    public function __construct(
        #[Channel('security')]
        private readonly LoggerInterface $logger,
    ) {}
}

The instantiated logger will now have the channel "security", instead of the default one, which would be a combination of namespace and class of the instantiating class, such as MyVendor.MyExtension.Service.MyClass.

use Psr\Log\LogLevel;
use TYPO3\CMS\Core\Core\Environment;
use TYPO3\CMS\Core\Log\Writer\FileWriter;

$GLOBALS['TYPO3_CONF_VARS']['LOG']['security']['writerConfiguration'] = [
    LogLevel::DEBUG => [
        FileWriter::class => [
            'logFile' => Environment::getVarPath() . '/log/security.log'
        ]
    ],
];

Fri, 21 Jul 2023 16:26:13 +0000 [DEBUG] ... component="security": ...

Examples

Examples of the usage of the logger can be found in the extension EXT:examples. in file /Classes/Controller/ModuleController.php

Best practices

There are no strict rules or guidelines about logging. Still it can be considered to be best practice to follow these rules:

$this->logger->alert(
    'Password reset requested for email "'
    . $emailAddress . '" but was requested too many times.'
);

$this->logger->alert(
    'Password reset requested for email "{email}" but was requested too many times.',
    ['email' => $emailAddress]
);

"Something went wrong"

"Could not connect to database"

"Connection to MySQL database could not be established"

"Database not reached"
"Could not establish connection to memcache"

"Connection to MySQL database could not be established"
"Connection to memcache could not be established"