A simple yet configurable logger for PHP
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Dustin Wilson 051d84d667 Updated README.md 4 months ago
lib Added entryTransform option to StreamHandler, removed entryFormat option 4 months ago
tests Added entryTransform option to StreamHandler, removed entryFormat option 4 months ago
.gitignore Initial commit 1 year ago
AUTHORS Added AUTHORS and LiCENSE files 1 year ago
LICENSE Added AUTHORS and LiCENSE files 1 year ago
README.md Updated README.md 4 months ago
composer.json Added psr/log to requirements in README 1 year ago
composer.lock Added psr/log to requirements in README 1 year ago
test Better checking for callable for messageTransform 1 year ago



Logger is a simple yet configurable logger for PHP. It is an opinionated implementation of PSR-3 Logger Interface. It uses classes called handlers to handle messages to log. Currently there is only one handler: StreamHandler which allows for logging to files or to streams such as php://stdout or php://stderr. Handlers can be easily written and plugged into Logger.


This library attempts what we're calling an "opinionated" implementation of PSR-3. This is because while it successfully implements Psr\Log\LoggerInterface Logger deviates from the true spirit of the specification in various ways:

  1. In section 1.1 PSR-3 states that when calling the log method with one of the log level constants (later shown to be in Psr\Log\LogLevel) it must have the same result as calling the level-specific methods. The log level constants in Psr\Log\LogLevel are strings, but the $level parameter of the log method in Psr\Log\LoggerInterface is typeless. The words of the specification suggest that the $level parameter should be a string, but the actual code implementors are to use doesn't specify a type. The same section also references RFC 5424 when mentioning the log level methods, but why use strings when there are standardized integers used to identify severity? Since the interface allows for any type for $level, Logger will prefer the actual RFC standard's integers but will accept and convert PSR-3's strings internally to the integers just so it can remain PSR-3 compatible.

  2. In section 1.2 of the specification it describes an optional feature, placeholders, and requires the implementor to write code to parse out and replace placeholders using a syntax and a method that's not present anywhere else in the entirety of PHP. Logger won't support this feature because a logging library's place is to log messages and not to interpolate template strings. A separate library or a built-in function such as sprintf should be used instead. Logger provides a way to transform messages that can be used to hook in a preferred interpolation method if desired, though.

  3. The specification in section 1.3 also specifies that if an Exception object is passed in the $context parameter it must be within an exception key. This makes sense, but curiously there's nary a mention of what to do with an Error object. They've existed since PHP 7 and can be thrown just like exceptions. Logger will accept any Throwable in the exception key, but at present does nothing with it. Theoretically future handlers could be written to take advantage of it for structured data.

  4. Also in the first item of section 1.3 it states categorically that implementors must not trigger a warning when errant data is in the $context array and treat it with "as much lenience as possible". It then states in the following item that if an exception is present in the context data it must be in the exception key and that implementors must verify the exception key. This is contradictory. You can't verify the exception key without triggering an error or exception when it's wrong. The user should be notified they've made a mistake; it's bad design otherwise. Our solution to this problem is to remove errant throwables from $context and also trigger warnings when they're encountered. However, Logger->$warnOnInvalidContextThrowables is provided to make it easy to suppress the warnings if necessary.



This library uses mensbeam/filesystem which provides polyfills for ext-ctype and ext-mbstring. If you have these extensions installed the polyfills won't be used. However, they are still installed. If you don't want the polyfills needlessly installed you can add this to your project's composer.json:

    "require": {
        "ext-ctype": "*",
        "ext-mbstring": "*"
    "provide": {
        "symfony/polyfill-ctype": "*",
        "symfony/polyfill-mbstring": "*"


composer require mensbeam/logger


This library works without any configuration, but it might not be quite how you think it would work by default:

use MensBeam\Logger;

$logger = new Logger();

This will create a logger that outputs all debug, info, notice, and warning entries to STDOUT while any error, critical, alert, and emergency entries are output to STDERR. This seems like it would be a bizarre default since it causes duplicate output to the shell on errors. However, if you accompany it with an error handler like Catcher it suddenly makes sense:

use MensBeam\{
use MensBeam\Catcher\PlainTextHandler;

$catcher = new Catcher(new PlainTextHandler([
    'logger' => new Logger('log'),
    'silent' => true

Now, Logger will take care of the printing. But, Logger can do far more.



namespace MensBeam;
use MensBeam\Logger\{

class Logger implements Psr\Log\LoggerInterface {
    public bool $warnOnInvalidContextThrowables = true;

    public function __construct(?string $channel = null, Handler ...$handlers);

    public function getChannel(): ?string;
    public function getHandlers(): array;
    public function popHandler(): Handler;
    public function pushHandler(Handler ...$handlers): void;
    public function setChannel(?string $value): void;
    public function setHandlers(Handler ...$handlers): void;
    public function shiftHandler(): Handler;
    public function unshiftHandler(Handler ...$handlers): void;

    public function emergency(string|\Stringable $message, array $context = []): void;
    public function alert(string|\Stringable $message, array $context = []): void;
    public function critical(string|\Stringable $message, array $context = []): void;
    public function error(string|\Stringable $message, array $context = []): void;
    public function warning(string|\Stringable $message, array $context = []): void;
    public function notice(string|\Stringable $message, array $context = []): void;
    public function info(string|\Stringable $message, array $context = []): void;
    public function debug(string|\Stringable $message, array $context = []): void;
    public function log(int|string|Level $level, string|\Stringable $message, array $context = []): void;


warnOnInvalidContextThrowables: When set to true Logger will trigger warnings when invalid Throwables are in the $context array in the logging methods.


Returns the channel name for the instance of Logger.


Returns an array of the handlers defined for use in the Logger instance.


Pops the last handler off the stack and returns it


Pushes the specified handler(s) onto the stack


Sets the channel to the specified string


Replaces the stack of handlers with those specified as parameters


Shifts the first handler off the stack of handlers and returns it


Unshifts the specified handler(s) onto the beginning of the stack


Adds an emergency entry to the log


Adds an alert entry to the log


Adds a critical entry to the log


Adds an error entry to the log


Adds a warning entry to the log


Adds a notice entry to the log


Adds an info entry to the log


Adds a debug entry to the log


Adds an entry to the log in the specified level


This is an enum of the RFC 5424 integer values for each of the log levels; also provides methods for converting to and from PSR-3 string values.

namespace MensBeam;

enum Level: int {
    case Emergency = 0;
    case Alert = 1;
    case Critical = 2;
    case Error = 3;
    case Warning = 4;
    case Notice = 5;
    case Info = 6;
    case Debug = 7;

    public static function fromPSR3(string $level): self;
    public function toPSR3(): string;


Takes a provided PSR-3 string level and returns a Level enum.


Returns a PSR-3 string level representation of the enum.


Handlers inherit from this abstract class. Since it is an abstract class meant for constructing handlers protected methods and properties will be documented here as well.

namespace MensBeam\Logger;

abstract class Handler {
    protected array $levels;

    protected bool $_bubbles = true;
    protected callable $_messageTransform = null;
    protected string $_timeFormat = 'M d H:i:s';

    public function __construct(array $levels = [ 0, 1, 2, 3, 4, 5, 6, 7 ], array $options = []);

    public function getLevels();
    public function getOption(string $name): mixed;
    public function setLevels(int ...$levels): void;
    public function setOption(string $name, mixed $value): void;
    public function __invoke(int $level, ?string $channel, string $message, array $context = []): void;

    abstract protected function invokeCallback(string $time, int $level, string $channel, string $message, array $context = []): void;

Properties (Protected)

levels: This is where the levels the handler is configured to support are stored


Properties which begin with an underscore are all options. They can be set either through the constructor or via setHandler by name, removing the underscore (_) at the beginning. All handlers inherit these options. Options in inherited classes should also begin with an underscore (_).

bubbles: When set to true the stack loop will continue onto the next handler; if false it won't. Defaults to true
messageTransform: A callable to use to transform messages before outputting. Defaults to null
timeFormat: The PHP-standard date format which to use for times in output. Defaults to "M d H:i:s"

Message Transform

The messageTransform option allows for manipulation of log messages. It accepts any callable with the following structure:

function (string $message, array $context): string;

One common use of this feature would be to do string interpolation which isn't handled by the library. By providing a message transform it's possible to use any preferred method of interpolation:

$handler = new StreamHandler(options: [
    'messageTransform' => function (string $message, array $context): string {
        return vsprintf($message, $context);

Of course this is a simplistic example. One would want to convert the $context array to numerical keys (or just use numerical keys) before usage in vsprintf, but as can be seen it's very possible.


Returns the levels the handler is configured to support


Returns the value of the provided option name


Sets the levels the handler will then support


Sets the provided option with the provided value


Outputs/dispatches the log entry

MensBeam\Logger\Handler::invokeCallback (protected)

A callback method meant to be extended by inherited classes to output/dispatch the log entry


namespace MensBeam\Logger;

class StreamHandler extends Handler {
    public function __construct(resource|string $stream = 'php://stdout', array $levels = [ 0, 1, 2, 3, 4, 5, 6, 7 ], array $options = []);

    public function getStream(): ?resource;
    public function getURI(): ?string;
    public function setStream(resource|string $value): void;


entryTransform: A callable where the log entry can be manipulated. Defaults to null

Entry Transform
function (string $time, int $level, string $levelName, string $channel, string $message, array $context): string;
The timestamp the log entry was dispatched at; can be altered with the timeFormat option
The RFC 5424 level integer for the entry
The RFC 5424 level name for the entry
The channel defined when creating the logger
The message string; can be manipulated with the messageTransform option
The context array used when dispatching the entry

Here is an example of how to use the entryTransform option to output entries to php://stdout as JSONLines/NDJSON/whatever (ugh):

use MensBeam\Logger,

$handler = new StreamHandler(options: [
    'entryTransform' => function (string $time, int $level, string $levelName, string $channel, string $message, array $context): string {
        $entry = [
            'time' => $time,
            'level' => $level,
            'levelName' => $levelName,
            'channel' => $channel,
            'message' => $message


$logger = new Logger('ook', $handler);
// {"time":"Feb 03 22:45:17","level":6,"levelName":"Info","channel":"ook","message":"ook\neek"}


Returns the resource where the handler will output to


Returns the URI where the handler will output to


Sets where the handler will output to