Logger

Overview

Phalcon\Logger\Logger is a component providing logging services for applications. It offers logging to different back-ends using different adapters. It also offers transaction logging, configuration options, and different logging formats. You can use the Phalcon\Logger\Logger for any logging need your application has, from debugging processes to tracing application flow.

The Phalcon\Logger\Logger implements methods that are in line with PSR-3 but does not implement Psr\Log\LoggerInterface directly. The phalcon/bridge-psr3 package bridges the two standards in both directions: the Phalcon logger can be consumed as a PSR-3 logger, and a PSR-3 logger can be used as a Phalcon log adapter. See the PSR-3 section below for installation and usage.

The Phalcon\Logger\Logger implements only the logging functionality and accepts one or more adapters that would be responsible for doing the work of logging. This implementation separates the responsibilities of the component and offers a way to attach more than one adapter to the logging component so that logging to multiple adapters can be achieved.

Adapters

This component makes use of adapters to store the logged messages. The use of adapters allows for a common logging interface which provides the ability to switch back-ends, or use multiple adapters if necessary. The adapters supported are:

The phalcon/debugbar package provides an additional adapter, Phalcon\DebugBar\Logger\Adapter, that forwards logged messages to the debug bar. Attach it alongside your other adapters to capture the application log in the bar’s “Logs” tab.

Stream

This adapter is used when we want to log messages to a particular file stream. Usually, this is the most used one: logging to a file in the file system.

Syslog

This adapter sends messages to the system log. The syslog behavior may vary from one operating system to another.

Noop

This is a black hole adapter. It sends messages to infinity and beyond! This adapter is used mostly for testing or if you want to joke with a colleague.

Factory

You can use the Phalcon\Logger\LoggerFactory component to create a logger. For the Phalcon\Logger\LoggerFactory to work, it needs to be instantiated with a Phalcon\Logger\AdapterFactory:

<?php

use Phalcon\Logger\LoggerFactory;
use Phalcon\Logger\AdapterFactory;

$adapterFactory = new AdapterFactory();
$loggerFactory  = new LoggerFactory($adapterFactory);

load()

Phalcon\Logger\LoggerFactory offers the load method, that constructs a logger based on supplied configuration. The configuration can be an array or a Phalcon\Config\Config object.

<?php

use Phalcon\Logger\AdapterFactory;
use Phalcon\Logger\LoggerFactory;
use Phalcon\Storage\SerializerFactory;

$config = [
    "name"    => "prod-logger",
    "options" => [
        "adapters" => [
            "main"  => [
                "adapter" => "stream",
                "name"    => "/storage/logs/main.log",
                "options" => []
            ],
            "admin" => [
                "adapter" => "stream",
                "name"    => "/storage/logs/admin.log",
                "options" => []
            ],
        ],
    ],
];

$serializerFactory = new SerializerFactory();
$adapterFactory    = new AdapterFactory();
$loggerFactory     = new LoggerFactory($adapterFactory);

$logger = $loggerFactory->load($config);

newInstance()

The Phalcon\Logger\LoggerFactory also offers the newInstance() method, which constructs a logger based on the supplied name and array of relevant adapters. Using the use case above:

<?php

use Phalcon\Logger\Adapter\Stream;
use Phalcon\Logger\AdapterFactory;
use Phalcon\Logger\LoggerFactory;
use Phalcon\Storage\SerializerFactory;

$adapters = [
    "main"  => new Stream("/storage/logs/main.log"),
    "admin" => new Stream("/storage/logs/admin.log"),
];

$serializerFactory = new SerializerFactory();
$adapterFactory    = new AdapterFactory($serializerFactory);
$loggerFactory     = new LoggerFactory($adapterFactory);

$logger = $loggerFactory->newInstance('prod-logger', $adapters);

Creating a Logger

Creating a logger is a multi-step process. First, you create the logger object, and then you attach an adapter to it. After that, you can start logging messages according to the needs of your application.

<?php

use Phalcon\Logger\Logger;
use Phalcon\Logger\Adapter\Stream;

$adapter = new Stream('/storage/logs/main.log');
$logger  = new Logger(
    'messages',
    [
        'main' => $adapter,
    ]
);

$logger->error('Something went wrong');

The above example creates a Stream adapter. We then create a logger object and attach this adapter to it. Each adapter attached to a logger needs to have a unique name, for the logger to be able to know where to log the messages. When calling the error() method on the logger object, the message is going to be stored in the /storage/logs/main.log.

Since the logger component implements PSR-3, the following methods are available:

<?php

use Phalcon\Logger\Logger;
use Phalcon\Logger\Adapter\Stream;

$adapter = new Stream('/storage/logs/main.log');
$logger  = new Logger(
    'messages',
    [
        'main' => $adapter,
    ]
);

$logger->alert("This is an alert message");
$logger->critical("This is a critical message");
$logger->debug("This is a debug message");
$logger->error("This is an error message");
$logger->emergency("This is an emergency message");
$logger->info("This is an info message");
$logger->log(Logger::CRITICAL, "This is a log message");
$logger->notice("This is a notice message");
$logger->warning("This is a warning message");

The log generated is as follows:

[Tue, 25 Dec 18 12:13:14 -0400][alert] This is an alert message
[Tue, 25 Dec 18 12:13:14 -0400][critical] This is a critical message
[Tue, 25 Dec 18 12:13:14 -0400][debug] This is a debug message
[Tue, 25 Dec 18 12:13:14 -0400][error] This is an error message
[Tue, 25 Dec 18 12:13:14 -0400][emergency] This is an emergency message
[Tue, 25 Dec 18 12:13:14 -0400][info] This is an info message
[Tue, 25 Dec 18 12:13:14 -0400][critical] This is a log message
[Tue, 25 Dec 18 12:13:14 -0400][notice] This is a notice message
[Tue, 25 Dec 18 12:13:14 -0400][warning] This is a warning message

Multiple Adapters

Phalcon\Logger\Logger can send messages to multiple adapters with a single call:

<?php

use Phalcon\Logger\Logger;
use Phalcon\Logger\Adapter\Stream;

$adapter1 = new Stream('/logs/first-log.log');
$adapter2 = new Stream('/remote/second-log.log');
$adapter3 = new Stream('/manager/third-log.log');

$logger = new Logger(
    'messages',
    [
        'local'   => $adapter1,
        'remote'  => $adapter2,
        'manager' => $adapter3,
    ]
);

$logger->error('Something went wrong');

The messages are sent to the handlers in the order they were registered using the first in first out principle.

Excluding Adapters

Phalcon\Logger\Logger also offers the ability to exclude logging to one or more adapters when logging a message. This is particularly useful when in need of logging a manager related message in the manager log but not in the local log without having to instantiate a new logger.

With the following setup:

<?php

use Phalcon\Logger\Logger;
use Phalcon\Logger\Adapter\Stream;

$adapter1 = new Stream('/logs/first-log.log');
$adapter2 = new Stream('/remote/second-log.log');
$adapter3 = new Stream('/manager/third-log.log');

$logger = new Logger(
    'messages',
    [
        'local'   => $adapter1,
        'remote'  => $adapter2,
        'manager' => $adapter3,
    ]
);

we have the following:

<?php

$logger->error('Something went wrong');

Log to all adapters

<?php

$logger
    ->excludeAdapters(['local'])
    ->info('This does not go to the "local" logger');

Log only to remote and manager

Constants

The class offers a number of constants that can be used to distinguish between log levels. These constants can also be used as the first parameter in the log() method.

Log Levels

Phalcon\Logger\Logger allows you to set the minimum log level for the logger(s) to log. If you set this integer value, any level higher than the one set will not be logged. Check the values of the constants in the previous section for the order in which the levels are being set.

In the following example, we set the log level to ALERT. We will only see EMERGENCY, CRITICAL, and ALERT messages.

<?php

use Phalcon\Logger\Logger;
use Phalcon\Logger\Adapter\Stream;

$adapter = new Stream('/storage/logs/main.log');
$logger  = new Logger(
    'messages',
    [
        'main' => $adapter,
    ]
);

$logger->setLogLevel(Logger::ALERT);

$logger->alert("This is an alert message");
$logger->critical("This is a critical message");
$logger->debug("This is a debug message");
$logger->error("This is an error message");
$logger->emergency("This is an emergency message");
$logger->info("This is an info message");
$logger->log(Logger::CRITICAL, "This is a log message");
$logger->notice("This is a notice message");
$logger->warning("This is a warning message");

The log generated is as follows:

[Tue, 25 Dec 18 12:13:14 -0400][alert] This is an alert message
[Tue, 25 Dec 18 12:13:14 -0400][critical] This is a critical message
[Tue, 25 Dec 18 12:13:14 -0400][emergency] This is an emergency message
[Tue, 25 Dec 18 12:13:14 -0400][critical] This is a log message

The above can be used in situations where you want to log messages above a certain severity based on conditions in your application such as development mode vs. production.

Unknown Levels

CUSTOM (8) doubles as the sink for any level the logger does not recognize. When log() receives a level it cannot map - a misspelled level name or an integer outside the defined constants - the message is recorded at the CUSTOM level instead of raising an exception. The level name is emitted as custom.

<?php

use Phalcon\Logger\Logger;
use Phalcon\Logger\Adapter\Stream;

$adapter = new Stream('/storage/logs/main.log');
$logger  = new Logger(
    'messages',
    [
        'main' => $adapter,
    ]
);

// "warnning" is a typo and is not a known level; it is logged as CUSTOM
$logger->log('warnning', 'Disk space is low');

The log generated is as follows:

[Tue, 25 Dec 18 12:13:14 -0400][custom] Disk space is low

setLogLevel() follows the same rule: an unrecognized integer is stored as CUSTOM rather than throwing. Because CUSTOM (8) sits between DEBUG (7) and TRACE (9), the resulting threshold emits every level except TRACE.

Trace Level

trace() records extra-verbose, fine-grained diagnostic output. Use it for high-frequency events such as raw socket frames, full HTTP response bodies, or internal state transitions that are too noisy for debug().

TRACE has the value 9. It is more verbose than DEBUG (7) and CUSTOM (8), making it the most verbose level the logger emits. TRACE is an additional level; the existing CUSTOM level and its custom label are unchanged.

trace() is opt-in. The default minimum log level is CUSTOM (8), and the logger only emits a message when its level is at or below the configured minimum. Because TRACE (9) is higher than the default, trace messages are suppressed until you lower the threshold with setLogLevel().

<?php

use Phalcon\Logger\Logger;
use Phalcon\Logger\Adapter\Stream;

$adapter = new Stream('/storage/logs/main.log');
$logger  = new Logger(
    'messages',
    [
        'main' => $adapter,
    ]
);

// Suppressed: the default minimum level is CUSTOM (8), TRACE (9) is higher
$logger->trace('This message is not logged at the default level');

$logger->setLogLevel(Logger::TRACE);

// Emitted: the minimum level now includes TRACE
$logger->trace('Raw response body: {"status":"ok"}');

The log generated is as follows:

[Tue, 25 Dec 18 12:13:14 -0400][trace] Raw response body: {"status":"ok"}

The level name is emitted in lowercase as trace. When the Syslog adapter receives a trace message, it maps the level to LOG_DEBUG.

Transactions

Phalcon\Logger\Logger also offers the ability to queue the messages in your logger, and then commit them all together in the log file. This is similar to a database transaction with begin and commit. Each adapter exposes the following methods:

Since the functionality is available at the adapter level, you can program your logger to use transactions on a per-adapter basis.

<?php

use Phalcon\Logger\Logger;
use Phalcon\Logger\Adapter\Stream;

$adapter1 = new Stream('/logs/first-log.log');
$adapter2 = new Stream('/remote/second-log.log');
$adapter3 = new Stream('/manager/third-log.log');

$logger = new Logger(
    'messages',
    [
        'local'   => $adapter1,
        'remote'  => $adapter2,
        'manager' => $adapter3,
    ]
);

$logger->getAdapter('manager')->begin();

$logger->error('Something happened');

$logger->getAdapter('manager')->commit();

In the example above, we register three adapters. We set the manager logger to be in transaction mode. As soon as we call:

$logger->error('Something happened');

the message will be logged in both local and remote adapters. It will be queued for the manager adapter and not logged until we call the commit method in the manager adapter.

Logger-Level Transactions

Phalcon\Logger\Logger also exposes begin(), commit(), and rollback() directly. Each method fans the call out to every registered adapter that has not been excluded, so a single transaction can span the whole adapter stack without reaching into each adapter individually.

<?php

use Phalcon\Logger\Logger;
use Phalcon\Logger\Adapter\Stream;

$adapter1 = new Stream('/logs/first-log.log');
$adapter2 = new Stream('/remote/second-log.log');

$logger = new Logger(
    'messages',
    [
        'local'  => $adapter1,
        'remote' => $adapter2,
    ]
);

$logger->begin();

$logger->error('Something happened');
$logger->info('Processing complete');

$logger->commit();

Both messages are queued on the local and remote adapters while the transaction is open, then written to both log files when commit() is called. Call rollback() in place of commit() to discard the queued messages instead of writing them. Each method returns the logger instance, so the calls can be chained.

Calling begin() while a transaction is already open throws Phalcon\Logger\Exceptions\TransactionAlreadyActive.

Capping the Transaction Queue

By default the transaction queue holds every message between begin() and commit(). In long-running processes that batch many messages per transaction this grows without bound. Call setQueueLimit() on the adapter to keep only the most recent N items; the oldest is dropped FIFO before each new add() call.

<?php

use Phalcon\Logger\Logger;
use Phalcon\Logger\Adapter\Stream;

$adapter = new Stream('/var/log/application.log');
$adapter->setQueueLimit(1000);

$logger = new Logger('messages', ['file' => $adapter]);

$adapter->begin();

for ($i = 0; $i < 5000; $i++) {
    $logger->info('record ' . $i);
}

$adapter->commit();
// At commit() the queue holds the most recent 1000 messages;
// the older 4000 were evicted FIFO during add().

The default value 0 preserves the original unbounded behavior. getQueueLimit() returns the current cap. rollback() continues to drop the queue regardless of the cap.

Message Formatting

This component makes use of formatters to format messages before sending them to the backend. The formatters available are:

Line Formatter

Formats the messages using a one-line string. The default logging format is:

[%date%][%level%] %message%

Message Format

If the default format of the message does not fit the needs of your application you can change it using the setFormat() method. The log format variables allowed are:

The following example demonstrates how to change the message format:

<?php

use Phalcon\Logger\Logger;
use Phalcon\Logger\Adapter\Stream;
use Phalcon\Logger\Formatter\Line;

$formatter = new Line('[%level%] - [%date%] - %message%');
$adapter   = new Stream('/storage/logs/main.log');

$adapter->setFormatter($formatter);

$logger  = new Logger(
    'messages',
    [
        'main' => $adapter,
    ]
);

$logger->error('Something went wrong');

which produces:

[alert] - [Tue, 25 Dec 18 12:13:14 -0400] - Something went wrong

If you do not want to use the constructor to change the message, you can always use the setFormat() on the formatter:

<?php

use Phalcon\Logger\Logger;
use Phalcon\Logger\Adapter\Stream;
use Phalcon\Logger\Formatter\Line;

$formatter = new Line();
$formatter->setFormat('[%level%] - [%date%] - %message%');

$adapter = new Stream('/storage/logs/main.log');

$adapter->setFormatter($formatter);

$logger  = new Logger(
    'messages',
    [
        'main' => $adapter,
    ]
);

$logger->error('Something went wrong');

Date Format

The default date format is:

"D, d M y H:i:s O"

If the default format of the message does not fit the needs of your application you can change it using the setDateFormat() method. The method accepts a string with characters that correspond to date formats. For all available formats, please consult this page.

<?php

use Phalcon\Logger\Logger;
use Phalcon\Logger\Adapter\Stream;
use Phalcon\Logger\Formatter\Line;

$formatter = new Line();
$formatter->setDateFormat('Ymd-His');

$adapter = new Stream('/storage/logs/main.log');

$adapter->setFormatter($formatter);

$logger  = new Logger(
    'messages',
    [
        'main' => $adapter,
    ]
);

$logger->error('Something went wrong'); 

which produces:

[error] - [20181225-121314] - Something went wrong

JSON Formatter

Formats the messages returning a JSON string:

{
    "level"     : "Level of the message",
    "message"   : "The message",
    "timestamp" : "The date as defined in the date format"
}

Date Format

The default date format is:

"D, d M y H:i:s O"

If the default format of the message does not fit the needs of your application you can change it using the setDateFormat() method. The method accepts a string with characters that correspond to date formats. For all available formats, please consult this page.

<?php

use Phalcon\Logger\Logger;
use Phalcon\Logger\Adapter\Stream;
use Phalcon\Logger\Formatter\Line;

$formatter = new Line();
$formatter->setDateFormat('Ymd-His');

$adapter = new Stream('/storage/logs/main.log');
$adapter->setFormatter($formatter);

$logger  = new Logger(
    'messages',
    [
        'main' => $adapter,
    ]
);

$logger->error('Something went wrong');

which produces:

{
    "level"     : "error",
    "message"   : "Something went wrong",
    "timestamp" : "20181225-121314"
}

Custom Formatter

The Phalcon\Logger\Formatter\FormatterInterface interface must be implemented in order to create your own formatter or extend the existing ones. Additionally, you can reuse the Phalcon\Logger\Formatter\AbstractFormatter abstract class.

Interpolation

The logger also supports interpolation. There are times that you might need to inject additional text in your logging messages; text that is dynamically created by your application. This can be achieved by sending an array as the second parameter of the logging method (i.e. error, info, alert etc.). The array holds keys and values, where the key is the placeholder in the message and the value is what will be injected in the message.

The following example demonstrates interpolation by injecting into the message the parameter “framework” and “secs”.

<?php

use Phalcon\Logger\Logger;
use Phalcon\Logger\Adapter\Stream;

$adapter = new Stream('/storage/logs/main.log');
$logger  = new Logger(
    'messages',
    [
        'main' => $adapter,
    ]
);

$message = '%framework% executed the "Hello World" test in %secs% second(s)';
$context = [
    'framework' => 'Phalcon',
    'secs'      => 1,
];

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

Item

The formatter classes above accept a Phalcon\Logger\Item object. The object contains all the necessary data required for the logging process. It is used as a transport of data from the logger to the formatter.

Examples

Stream

Logging to a file:

<?php

use Phalcon\Logger\Logger;
use Phalcon\Logger\Adapter\Stream;

$adapter = new Stream('/storage/logs/main.log');
$logger  = new Logger(
    'messages',
    [
        'main' => $adapter,
    ]
);

// Log to all adapters
$logger->error('Something went wrong');

The stream logger writes messages to a valid registered stream in PHP. A list of streams is available here. Logging to a stream

<?php

use Phalcon\Logger\Logger;
use Phalcon\Logger\Adapter\Stream;

$adapter = new Stream('php://stderr');
$logger  = new Logger(
    'messages',
    [
        'main' => $adapter,
    ]
);

$logger->error('Something went wrong');

Syslog

<?php

use Phalcon\Logger\Logger;
use Phalcon\Logger\Adapter\Syslog;

// Setting identity/mode/facility
$adapter = new Syslog(
    'ident-name',
    [
        'option'   => LOG_NDELAY,
        'facility' => LOG_MAIL,
    ]
);

$logger  = new Logger(
    'messages',
    [
        'main' => $adapter,
    ]
);

$logger->error('Something went wrong');

Noop

<?php

use Phalcon\Logger\Logger;
use Phalcon\Logger\Adapter\Noop;

$adapter = new Noop('nothing');
$logger  = new Logger(
    'messages',
    [
        'main' => $adapter,
    ]
);

$logger->error('Something went wrong');

Custom Adapters

The Phalcon\Logger\AdapterInterface interface must be implemented in order to create your own logger adapters or extend the existing ones. You can also take advantage of the functionality in Phalcon\Logger\Adapter\AbstractAdapter abstract class.

Abstract Classes

There are three abstract classes that offer useful functionality when creating custom objects:

• Phalcon\Logger\AbstractLogger
• Phalcon\Logger\Adapter\AbstractAdapter
• Phalcon\Logger\Formatter\AbstractFormatter.

Dependency Injection

You can register as many loggers as you want in the Phalcon\Di\FactoryDefault container. An example of the registration of the service as well as accessing it is below:

<?php

use Phalcon\Di\Di;
use Phalcon\Logger\Logger;
use Phalcon\Logger\Adapter\Stream;

$container = new Di();

$container->set(
    'logger',
    function () {
        $adapter = new Stream('/storage/logs/main.log');
        $logger  = new Logger(
            'messages',
            [
                'main' => $adapter,
            ]
        );

        return $logger;
    }
);

// accessing it later:
$logger = $container->getShared('logger');

PSR-3

Phalcon\Logger\Logger implements methods that are in line with PSR-3 but does not implement Psr\Log\LoggerInterface directly. The phalcon/bridge-psr3 package bridges the two standards in both directions.

• Requires PHP 8.1 or later
• Works with the Phalcon C extension or the phalcon/phalcon package
• Targets psr/log (PSR-3) version 3

Install the package with composer:

composer require phalcon/bridge-psr3

The package provides two classes, one for each direction.

Phalcon Logger as a PSR-3 Logger

Phalcon\Bridge\Psr3\Logger is a Psr\Log\LoggerInterface backed by Phalcon logging adapters. Use it when a component requires a PSR-3 logger and the output needs to pass through Phalcon. The constructor matches Phalcon\Logger\Logger: a name and an array of named adapters.

<?php

use Phalcon\Bridge\Psr3\Logger;
use Phalcon\Logger\Adapter\Stream;

$logger = new Logger(
    'application',
    [
        'main' => new Stream('/storage/logs/application.log'),
    ]
);

// $logger is a Psr\Log\LoggerInterface
$logger->info('Order placed');
$logger->error('Payment gateway timed out');

The returned object can be passed to any consumer that type-hints Psr\Log\LoggerInterface.

PSR-3 Logger as a Phalcon Adapter

Phalcon\Bridge\Psr3\Adapter is a Phalcon log adapter that forwards every message to a wrapped Psr\Log\LoggerInterface. Use it when a PSR-3 logger already exists, such as Monolog, and it needs to act as a Phalcon logging back-end. Register it on a Phalcon\Logger\Logger like any other adapter.

<?php

use Monolog\Logger as Monolog;
use Phalcon\Bridge\Psr3\Adapter;
use Phalcon\Logger\Logger;

$psr = new Monolog('application');

$logger = new Logger(
    'application',
    [
        'psr' => new Adapter($psr),
    ]
);

// The message is forwarded to the PSR-3 logger
$logger->warning('Disk space is low');

The result is a Phalcon\Logger\Logger, so it can be injected wherever Phalcon expects a logger, such as the DataMapper profiler.

Phalcon level names map to the matching PSR-3 levels. The two Phalcon-only levels, CUSTOM (8) and TRACE (9), are forwarded to the PSR-3 debug level, because PSR-3 defines no equivalent.

Contracts

The canonical interfaces for this component live in the Phalcon\Contracts\Logger namespace, with the Interface suffix dropped. Phalcon\Logger\LoggerInterface, Phalcon\Logger\Adapter\AdapterInterface, and Phalcon\Logger\Formatter\FormatterInterface remain available: each now extends its contract and is deprecated. Existing implementations and type hints keep working unchanged; new code should target the contracts.

Exceptions

Any exceptions thrown in the Logger component will be of type Phalcon\Logger\Exception. You can use this exception to selectively catch exceptions thrown only from this component.

<?php

use Phalcon\Logger\Logger;
use Phalcon\Logger\Adapter\Stream;
use Phalcon\Logger\Exception;

try {
    $adapter = new Stream('/storage/logs/main.log');
    $logger  = new Logger(
        'messages',
        [
            'main' => $adapter,
        ]
    );

    $logger->error('Something went wrong');
} catch (Exception $ex) {
    echo $ex->getMessage();
}

Granular Exceptions

The component raises granular subclasses of Phalcon\Logger\Exception so callers can catch a specific failure mode. Existing catch (Phalcon\Logger\Exception $e) blocks continue to work unchanged.