Logging with PSR-3 to Improve Reusability

Share this article

Logging is one of the most ubiquitous tasks encountered in PHP. We use logs to track error messages, record important events, and debug problems with our code. In any PHP project, the code is likely to be full of calls to a logging library which handles these actions for us. Unfortunately, having calls to a logging library scattered throughout our code makes the code dependent on the availability of that library, a clear violation of the Dependency Inversion Principle. Even if we use dependency injection to give our objects access to the logging library, the differences between logging libraries means that it can be difficult and time consuming to switch between them, requiring a major refactoring of our entire codebase. To promote compatibility between logging libraries, the PHP-FIG group recently released PSR-3
, a common interface for logger objects. In this article, I’ll discuss how the logger interface defined by PSR-3 allows us to write reusable code that isn’t dependent on any particular logging implementation.

First, a Quick Primer

Before we look at how PSR-3 can make our code more reusable, it is necessary to understand what PSR-3 is. If you are already familiar with PSR-3, you can skip this section. The heart of the specification is an interface for logger objects. This interface exposes eight methods for handling messages of different severity, and a generic log() method which can accept an arbitrary severity level. The eight severity levels supported by PSR-3 are based on RFC 5424, and are described below:
  • Emergency – the system is unusable
  • Alert – immediate action is required
  • Critical – critical conditions
  • Error – errors that do not require immediate attention but should be monitored
  • Warning – unusual or undesirable occurrences that are not errors
  • Notice – normal but significant events
  • Info – interesting events
  • Debug – detailed information for debugging purposes
Each of the logging methods accepts a message, which must be a string or an object with a __toString() method. An additional argument accepts an array, which may be given to provide contextual information for the log message. A full explanation of these methods and parameters can be found in the PSR-3 specification.

Getting PSR-3 Files

Getting the files you need to work with PSR-3 is easy – you can find them in the Psr/Log GitHub repository. You can also use Composer to get the files from Packagist. Below is a sample composer.json file to retrieve the Psr/Log files:
{
    "require": {
        "psr/log": "dev-master"
    }
}

How Logging Can Limit Code Reuse

There are many different logging libraries for PHP, each with its own approach to collecting and recording data. While there are some common ideas among them, each library has its own unique set of logging methods. This means that switching between loggers can be challenging, often requiring code changes wherever logging is used. This works against the idea of code reuse and the SOLID principles of object-oriented design. We’re left with a situation that requires us to either declare a dependency on a specific logging library, or avoid logging entirely. To illustrate this problem more clearly, a concrete example is needed. Let’s say we’re creating a simple Mailer object to handle sending emails. We want the Mailer to log a message whenever an email is sent, and we decide to use the excellent Monolog library to handle our logging needs.
<?php
namespace Email;

class Mailer
{
    private $logger;
    
    public function __construct($logger)
    {
        $this->logger = $logger;
    }
    
    public function sendEmail($emailAddress)
    {
        // code to send an email...
        
        // log a message
        $this->logger->addInfo("Email sent to $emailAddress");
    }
}
We can use this class with the following code:
<?php
// create a Monolog object
$logger = new MonologLogger("Mail");
$logger->pushHandler(new MonologHandlerStreamHandler("mail.log"));

// create the mailer and send an email
$mailer = new EmailMailer($logger);
$mailer->sendEmail("email@example.com");
Running this code will result in a new entry in the mail.log file, recording that the email was sent. At this point, we might be tempted to say that we’ve written a reusable Mailer object. We’re making the logger available to the Mailer with dependency injection so we can swap out different logger configurations without having to touch our Mailer code. It appears that we’ve successfully followed the SOLID principles and avoided creating any hard dependencies. But suppose we want to reuse our Mailer class in a different project which uses Analog to handle logging interactions. Now we run into a problem, because Analog doesn’t have an addInfo() method. To log an info level message with Analog, we call Analog::log($message, Analog::INFO). We could modify our Mailer class to use Analog’s methods, as seen below.
<?php
namespace Email;

class Mailer
{
    public function sendEmail($emailAddress)
    {
        // code to send an email...
        
        // log a message
        Analog::log("Email sent to $emailAddress", Analog::INFO);
    }
}
We can consume the updated Mailer class using the following code:
<?php
// set up Analog
Analog::handler(AnalogHandlerFile::init("mail.log"));

// create the mailer and send an email
$mailer = new EmailMailer();
$mailer->sendEmail("email@example.com");
While this will work, it is far from ideal. We’ve run into Mailer’s dependency on a specific logging implementation, which requires the class to change whenever a new logger is introduced. This makes the class less reusable and forces us to choose between being dependent on the availability of a specific logger or abandoning logging from within our class entirely.

Using PSR-3 to Avoid the Logger Dependency

As Alejandro Gervasio explained in his excellent article on the subject, the Dependency Inversion Principle tells us that we should depend upon abstractions rather than concretions. In the case of logging, our problem so far has been a lack of a decent abstraction on which to depend. This is where PSR-3 comes in. PSR-3 is designed to overcome the problem of incompatible logging implementations by providing a universal interface for loggers, aptly named LoggerInterface. By providing an interface which is not bound to any particular implementation, PSR-3 frees us from having to rely on a specific logger – we can instead type-hint against LoggerInterface to acquire a PSR-3 compliant logger. I have updated the Mailer class below to demonstrate this:
<?php
namespace Email;

class Mailer
{
    private $logger;
    
    public function __construct(PsrLogLoggerInterface $logger)
    {
        $this->logger = $logger;
    }
    
    public function sendEmail($emailAddress)
    {
        // code to send an email...
        
        // log a message
        $this->logger->info("Email sent to $emailAddress");
    }
}
The constructor has been modified to accept an implementor of LoggerInterface, and the sendEmail() method now calls the info()
method specified in PSR-3. Monolog is already PSR-3 compliant, and Analog supplies a wrapper object that implements LoggerInterface, so we can now use both loggers without modifying our Mailer class. Here’s how you would call the class with Monolog:
<?php
// create a Monolog object
$logger = new MonologLogger("Mail");
$logger->pushHandler(new MonologHandlerStreamHandler("mail.log"));

// create the mailer and send an email
$mailer = new EmailMailer($logger);
$mailer->sendEmail("email@example.com");
And with Analog:
<?php
// create a PSR-3 compatible Analog wrapper
$logger = new AnalogLogger();
$logger->handler(AnalogHandlerFile::init("mail.log"));

// create the mailer and send an email
$mailer = new EmailMailer($logger);
$mailer->sendEmail("email@example.com");
Now we’re able to use our Mailer object with either library without having to edit the Mailer class or change the way we consume it.

Using the Adapter Pattern for Loggers that Don’t Support PSR-3

So far we’ve successfully decoupled the Mailer object from any particular logging implementation by asking for an implementor of LoggerInterface. But what about loggers that have yet to add support for PSR-3? For example, the popular KLogger library has not been updated for some time and is currently not compatible with PSR-3. Luckily, it’s simple for us to map the methods exposed by KLogger to those defined by LoggerInterface by harnessing the power of the Adapter Pattern. The supporting files in the Psr/Log repository make it easy to create adapter classes by providing us with an AbstractLogger class that we can extend. The abstract class simply forwards the eight level-specific logging methods defined in LoggerInterface to a generic log() method. By extending the AbstractLogger class and defining our own log() method, we can easily create PSR-3 compliant adapters for loggers that do not natively support PSR-3. I’ll demonstrate this below by creating a simple adapter for KLogger:
<?php
namespace Logger;

class KloggerAdapter extends PsrLogAbstractLogger implements PsrLogLoggerInterface
{
    private $logger;    
    
    public function __construct($logger)
    {
        $this->logger = $logger;
    }

    public function log($level, $message, array $context = array())
    {
        // PSR-3 states that $message should be a string
        $message = (string)$message;

        // map $level to the relevant KLogger method
        switch ($level) {
            case PsrLogLogLevel::EMERGENCY:
                $this->logger->logEmerg($message, $context);
                break;
            case PsrLogLogLevel::ALERT:
                $this->logger->logAlert($message, $context);
                break;
            case PsrLogLogLevel::CRITICAL:
                $this->logger->logCrit($message, $context);
                break;
            case PsrLogLogLevel::ERROR:
                $this->logger->logError($message, $context);
                break;
            case PsrLogLogLevel::WARNING:
                $this->logger->logWarn($message, $context);
                break;
            case PsrLogLogLevel::NOTICE:
                $this->logger->logNotice($message, $context);
                break;
            case PsrLogLogLevel::INFO:
                $this->logger->logInfo($message, $context);
                break;
            case PsrLogLogLevel::DEBUG:
                // KLogger logDebug() method does not accept a second
                // argument
                $this->logger->logDebug($message);
                break;
            default:
                // PSR-3 states that we must throw a
                // PsrLogInvalidArgumentException if we don't
                // recognize the level
                throw new PsrLogInvalidArgumentException(
                    "Unknown severity level"
                );
        }
    }
}
The log() method simply maps the LoggerInterface methods to the respective KLogger methods, and KLogger handles the actual logging activity. By wrapping the KLogger class in this way, we’re able to use it without breaking the LoggerInterface contract. We can now use the KLogger adapter to work with the Mailer class:
<?php
// create a new KLogger object which will log to the "logs" directory
$klogger = KLogger::instance("logs");

// inject KLoggger to a PSR-3 compatible KloggerAdapter
$logger = new LoggerKloggerAdapter($klogger);

// send an email
$mailer = new EmailMailer($logger);
$mailer->sendEmail("email@example.com");
Using the adapter class, we’re able to use KLogger without modifying the Mailer class and still adhering to LoggerInterface. KLogger doesn’t accept a second argument for debug level messages, so it’s not technically PSR-3 compliant even with an adapter. Extending KLogger to make it fully compatible with PSR-3 would be a trivial task, but one which falls outside the scope of this article. However, it is safe to say that using our adapter class gets us very close to full PSR-3 compliance and allows us to use LoggerInterface with the KLogger class.

Conclusion

In this article we’ve seen how using PSR-3 can help us to write logger-agnostic code which does not depend on a particular logging implementation. Many major PHP projects have already added support for PSR-3, including Monolog, Symfony, and Mustache.php, and other big names such as Drupal are discussing how to best integrate it. As PSR-3 makes logging less of a barrier to code reuse, we should see more libraries and frameworks making proper use of logging to provide useful information to developers. Will PSR-3 affect how you use logging in your applications? Let us know in the comments section below. Image via Fotolia

Frequently Asked Questions (FAQs) about Logging with PSR-3

What is the PSR-3 standard and why is it important in PHP logging?

The PSR-3 standard is a common interface for logging libraries in PHP. It was established by the PHP Framework Interoperability Group (PHP-FIG) to promote reusability and interoperability of code. The importance of PSR-3 lies in its ability to provide a universal logging system, allowing developers to switch between different logging libraries without having to change the core code. This flexibility enhances code maintainability and reduces the complexity of development.

How can I implement PSR-3 in my PHP project?

To implement PSR-3 in your PHP project, you need to use a logging library that adheres to the PSR-3 standard. There are several libraries available, such as Monolog, which is widely used due to its comprehensive features and compatibility with PSR-3. Once you’ve chosen a library, you can use its methods to log messages at different severity levels, from emergency to debug.

What are the different log levels in PSR-3?

PSR-3 defines eight log levels: emergency, alert, critical, error, warning, notice, info, and debug. Each level represents a different severity of the log message. For example, ’emergency’ is used for system-level issues that require immediate attention, while ‘debug’ is used for detailed information during development and troubleshooting.

How can I log custom data with PSR-3?

PSR-3 allows you to log custom data by using placeholders in your log messages. These placeholders are denoted by curly braces and will be replaced by the corresponding values from the context data array. This feature allows you to include specific, dynamic information in your log messages, enhancing their usefulness for debugging and analysis.

Can I use multiple logging libraries in a PSR-3 compliant system?

Yes, one of the advantages of using PSR-3 is that it allows for interoperability between different logging libraries. As long as the libraries adhere to the PSR-3 standard, you can use them interchangeably in your system without having to modify your core logging code.

How does PSR-3 improve code reusability?

PSR-3 improves code reusability by providing a common interface for logging. This means that any code written to use a PSR-3 compliant logging library can be reused with any other PSR-3 compliant library. This reduces the need to rewrite logging code when switching between libraries, saving time and effort in development.

What is the role of the LoggerInterface in PSR-3?

The LoggerInterface is the core of the PSR-3 standard. It defines the methods that a PSR-3 compliant logging library must implement. These methods correspond to the eight log levels defined by PSR-3, and a log method that accepts a log level as its argument.

How can I handle exceptions with PSR-3?

PSR-3 provides a built-in mechanism for handling exceptions. You can include an ‘exception’ key in the context data array passed to the log method. The value of this key should be the Exception object that you want to log. This allows you to capture detailed information about exceptions in your log messages.

Can I use PSR-3 with any PHP framework?

Yes, PSR-3 is a framework-agnostic standard. This means it can be used with any PHP framework that supports it. Many popular PHP frameworks, such as Laravel and Symfony, come with built-in support for PSR-3 compliant logging libraries.

How does PSR-3 enhance the debugging process?

PSR-3 enhances the debugging process by providing a standardized, flexible logging system. It allows for detailed log messages at different severity levels, and the inclusion of custom data in log messages. This makes it easier to track down and understand issues in your code. Furthermore, the interoperability provided by PSR-3 means you can use the most suitable logging library for your specific debugging needs.

Patrick MulveyPatrick Mulvey
View Author

Patrick Mulvey is a freelance web developer with broad experience in both client-side and server-side development. PHP is his favorite language for creating websites, despite all its quirks.

Advanced
Share this article
Read Next
Get the freshest news and resources for developers, designers and digital creators in your inbox each week
Loading form