[VOTE] PSR-3 Logger Interface

1,291 views
Skip to first unread message

Jordi Boggiano

unread,
Dec 13, 2012, 3:41:08 PM12/13/12
to php...@googlegroups.com
Heya,

I would like to start the vote on the Logger Interface.

- PR is at https://github.com/php-fig/fig-standards/pull/60
- Pretty HTML:
https://github.com/Seldaek/fig-standards/blob/logger-interface/proposed/logger-interface.md
- psr/log package: https://github.com/Seldaek/log/

Today is the 13th, the vote will end on the 27th of December (unless
everyone votes for once;). We have 26 members, quorum is at 9 votes.

Below is a copy of the full PSR text, to give it a sense of paper trail.

Happy holidays and thank you all for your patience and dedication.

==================================================

Logger Interface
================

This document describes a common interface for logging libraries.

The main goal is to allow libraries to receive a `Psr\Log\LoggerInterface`
object and write logs to it in a simple and universal way. Frameworks
and CMSs that have custom needs MAY extend the interface for their own
purpose, but SHOULD remain compatible with this document. This ensures
that the third-party libraries an application uses can write to the
centralized application logs.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD",
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are
to be
interpreted as described in [RFC 2119][].

The word `implementor` in this document is to be interpreted as someone
implementing the `LoggerInterface` in a log-related library or framework.
Users of loggers are refered to as `user`.

[RFC 2119]: http://tools.ietf.org/html/rfc2119

1. Specification
-----------------

### 1.1 Basics

- The `LoggerInterface` exposes eight methods to write logs to the eight
[RFC 5424][] levels (debug, info, notice, warning, error, critical, alert,
emergency).

- A ninth method, `log`, accepts a log level as first argument. Calling this
method with one of the log level constants MUST have the same result as
calling the level-specific method. Calling this method with a level not
defined by this specification MUST throw a
`Psr\Log\InvalidArgumentException`
if the implementation does not know about the level. Users SHOULD NOT
use a
custom level without knowing for sure the current implementation
supports it.

[RFC 5424]: http://tools.ietf.org/html/rfc5424

### 1.2 Message

- Every method accepts a string as the message, or an object with a
`__toString()` method. Implementors MAY have special handling for the
passed
objects. If that is not the case, implementors MUST cast it to a string.

- The message MAY contain placeholders which implementors MAY replace with
values from the context array.

Placeholder names MUST correspond to keys in the context array.

Placeholder names MUST be delimited with a single opening brace `{` and
a single closing brace `}`. There MUST NOT be any whitespace between the
delimiters and the placeholder name.

Placeholder names SHOULD be composed only of the characters `A-Z`, `a-z`,
`0-9`, underscore `_`, and period `.`. The use of other characters is
reserved for future modifications of the placeholders specification.

Implementors MAY use placeholders to implement various escaping strategies
and translate logs for display. Users SHOULD NOT pre-escape placeholder
values since they can not know in which context the data will be
displayed.

The following is an example implementation of placeholder interpolation
provided for reference purposes only:

```php
/**
* Interpolates context values into the message placeholders.
*/
function interpolate($message, array $context = array())
{
// build a replacement array with braces around the context keys
$replace = array();
foreach ($context as $key => $val) {
$replace['{' . $key . '}'] = $val;
}

// interpolate replacement values into the the message and return
return strtr($message, $replace);
}

// a message with brace-delimited placeholder names
$message = "User {username} created";

// a context array of placeholder names => replacement values
$context = array('username' => 'bolivar');

// echoes "Username bolivar created"
echo interpolate($message, $context);
```

### 1.3 Context

- Every method accepts an array as context data. This is meant to hold any
extraneous information that does not fit well in a string. The array can
contain anything. Implementors MUST ensure they treat context data with
as much lenience as possible. A given value in the context MUST NOT throw
an exception nor raise any php error, warning or notice.

- If an `Exception` object is passed in the context data, it MUST be in the
`'exception'` key. Logging exceptions is a common pattern and this allows
implementors to extract a stack trace from the exception when the log
backend supports it. Implementors MUST still verify that the `'exception'`
key is actually an `Exception` before using it as such, as it MAY contain
anything.

### 1.4 Helper classes and interfaces

- The `Psr\Log\AbstractLogger` class lets you implement the
`LoggerInterface`
very easily by extending it and implementing the generic `log` method.
The other eight methods are forwarding the message and context to it.

- Similarly, using the `Psr\Log\LoggerTrait` only requires you to
implement the generic `log` method. Note that since traits can not
implement
interfaces, in this case you still have to `implement LoggerInterface`.

- The `Psr\Log\NullLogger` is provided together with the interface. It
MAY be
used by users of the interface to provide a fall-back "black hole"
implementation if no logger is given to them. However conditional logging
may be a better approach if context data creation is expensive.

- The `Psr\Log\LoggerAwareInterface` only contains a
`setLogger(LoggerInterface $logger)` method and can be used by
frameworks to
auto-wire arbitrary instances with a logger.

- The `Psr\Log\LoggerAwareTrait` trait can be used to implement the
equivalent
interface easily in any class. It gives you access to `$this->logger`.

- The `Psr\Log\LogLevel` class holds constants for the eight log levels.

2. Package
----------

The interfaces and classes described as well as relevant exception classes
and a test suite to verify your implementation are provided as part of the
[php-fig/psr-log](https://packagist.org/packages/php-fig/psr-log) package.

3. `Psr\Log\LoggerInterface`
----------------------------

```php
<?php

namespace Psr\Log;

/**
* Describes a logger instance
*
* The message MUST be a string or object implementing __toString().
*
* The message MAY contain placeholders in the form: {foo} where foo
* will be replaced by the context data in key "foo".
*
* The context array can contain arbitrary data, the only assumption that
* can be made by implementors is that if an Exception instance is given
* to produce a stack trace, it MUST be in a key named "exception".
*
* See
https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-3-logger-interface.md
* for the full interface specification.
*/
interface LoggerInterface
{
/**
* System is unusable.
*
* @param string $message
* @param array $context
* @return null
*/
public function emergency($message, array $context = array());

/**
* Action must be taken immediately.
*
* Example: Entire website down, database unavailable, etc. This should
* trigger the SMS alerts and wake you up.
*
* @param string $message
* @param array $context
* @return null
*/
public function alert($message, array $context = array());

/**
* Critical conditions.
*
* Example: Application component unavailable, unexpected exception.
*
* @param string $message
* @param array $context
* @return null
*/
public function critical($message, array $context = array());

/**
* Runtime errors that do not require immediate action but should
typically
* be logged and monitored.
*
* @param string $message
* @param array $context
* @return null
*/
public function error($message, array $context = array());

/**
* Exceptional occurrences that are not errors.
*
* Example: Use of deprecated APIs, poor use of an API, undesirable
things
* that are not necessarily wrong.
*
* @param string $message
* @param array $context
* @return null
*/
public function warning($message, array $context = array());

/**
* Normal but significant events.
*
* @param string $message
* @param array $context
* @return null
*/
public function notice($message, array $context = array());

/**
* Interesting events.
*
* Example: User logs in, SQL logs.
*
* @param string $message
* @param array $context
* @return null
*/
public function info($message, array $context = array());

/**
* Detailed debug information.
*
* @param string $message
* @param array $context
* @return null
*/
public function debug($message, array $context = array());

/**
* Logs with an arbitrary level.
*
* @param mixed $level
* @param string $message
* @param array $context
* @return null
*/
public function log($level, $message, array $context = array());
}
```

4. `Psr\Log\LoggerAwareInterface`
---------------------------------

```php
<?php

namespace Psr\Log;

/**
* Describes a logger-aware instance
*/
interface LoggerAwareInterface
{
/**
* Sets a logger instance on the object
*
* @param LoggerInterface $logger
* @return null
*/
public function setLogger(LoggerInterface $logger);
}
```

5. `Psr\Log\LogLevel`
---------------------

```php
<?php

namespace Psr\Log;

/**
* Describes log levels
*/
class LogLevel
{
const EMERGENCY = 'emergency';
const ALERT = 'alert';
const CRITICAL = 'critical';
const ERROR = 'error';
const WARNING = 'warning';
const NOTICE = 'notice';
const INFO = 'info';
const DEBUG = 'debug';
}
```

==================================================

Here is an ASCII art beaver eating logs for the brave that scrolled all
the way:

| :|
| |
| .|
____| .|
.' . ). ,'
.' c '7 ) (
_.-" |.' `.
.' "8E :|
| _}"" :|
| ( | |
.' ) | :|
.odCG8o_.---.__8E | .|
`Y8MMP"" "" `-...-' cgmm

Cheers

--
Jordi Boggiano
@seldaek - http://nelm.io/jordi

Paul Jones

unread,
Dec 13, 2012, 3:57:11 PM12/13/12
to php...@googlegroups.com
+1. Yay for beavers :-)


-- pmj

Fabien Potencier

unread,
Dec 13, 2012, 3:58:19 PM12/13/12
to php...@googlegroups.com
+1

Drak

unread,
Dec 13, 2012, 4:01:52 PM12/13/12
to php...@googlegroups.com
+1


--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To post to this group, send email to php...@googlegroups.com.
To unsubscribe from this group, send email to php-fig+u...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.



Evert Pot

unread,
Dec 13, 2012, 4:04:26 PM12/13/12
to php...@googlegroups.com
+1

Larry Garfield

unread,
Dec 13, 2012, 4:18:41 PM12/13/12
to php...@googlegroups.com
Beaver +1

--Larry Garfield, Drupal

(Yes, that's an approval vote.)

Lukas Kahwe Smith

unread,
Dec 13, 2012, 4:22:30 PM12/13/12
to php...@googlegroups.com

On Dec 13, 2012, at 21:41 , Jordi Boggiano <j.bog...@seld.be> wrote:

> Heya,
>
> I would like to start the vote on the Logger Interface.
>
> - PR is at https://github.com/php-fig/fig-standards/pull/60
> - Pretty HTML:
> https://github.com/Seldaek/fig-standards/blob/logger-interface/proposed/logger-interface.md
> - psr/log package: https://github.com/Seldaek/log/
>
> Today is the 13th, the vote will end on the 27th of December (unless
> everyone votes for once;). We have 26 members, quorum is at 9 votes.
>
> Below is a copy of the full PSR text, to give it a sense of paper trail.
>
> Happy holidays and thank you all for your patience and dedication.


+1

regards,
Lukas Kahwe Smith
m...@pooteeweet.org



William DURAND

unread,
Dec 13, 2012, 4:44:35 PM12/13/12
to php...@googlegroups.com
In love with the ASCII art, so +1.
Glad to see we found a consensus for the placeholders :)

Ryan Parman

unread,
Dec 13, 2012, 7:02:30 PM12/13/12
to php...@googlegroups.com
AWS votes +1.


--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To post to this group, send email to php...@googlegroups.com.
To unsubscribe from this group, send email to php-fig+u...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msg/php-fig/-/Bq9RpLRi4oAJ.

Brett Bieber

unread,
Dec 13, 2012, 8:27:57 PM12/13/12
to php...@googlegroups.com


On Thu, Dec 13, 2012 at 2:41 PM, Jordi Boggiano <j.bog...@seld.be> wrote:
Heya,

I would like to start the vote on the Logger Interface.

- PR is at https://github.com/php-fig/fig-standards/pull/60
- Pretty HTML:
https://github.com/Seldaek/fig-standards/blob/logger-interface/proposed/logger-interface.md
- psr/log package: https://github.com/Seldaek/log/

Today is the 13th, the vote will end on the 27th of December (unless
everyone votes for once;). We have 26 members, quorum is at 9 votes.

Below is a copy of the full PSR text, to give it a sense of paper trail.

Happy holidays and thank you all for your patience and dedication.

+1

Thank you very much to Jordi & Paul.

--
Brett Bieber

William Durand

unread,
Dec 13, 2012, 3:47:43 PM12/13/12
to php...@googlegroups.com
In love with the ASCII art, so +1.
Glad to see we found a consensus for the placeholders :)

--
William Durand | http://www.williamdurand.fr



--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To post to this group, send email to php...@googlegroups.com.
To unsubscribe from this group, send email to php-fig+u...@googlegroups.com.

Paul Dragoonis

unread,
Dec 13, 2012, 9:34:50 PM12/13/12
to php...@googlegroups.com
+1


--

Paul Scott

unread,
Dec 13, 2012, 11:18:09 PM12/13/12
to php...@googlegroups.com
On 13/12/2012 22:41, Jordi Boggiano wrote:
> Heya,
>
> I would like to start the vote on the Logger Interface.
>
>

Haven't been very active in these discussions, due to reasons, but I
agree on *most* of the RFC/proposal. The beaver, however, sealed it
though, because if there is a fuzzy buck tooth animal involved, it must
be OK.

+1 from me then...

-- Paul

André R.

unread,
Dec 16, 2012, 7:53:54 AM12/16/12
to php...@googlegroups.com
eZ votes +1



Cache next? :)


On Thursday, December 13, 2012 9:41:08 PM UTC+1, Jordi Boggiano wrote:

Larry E. Masters

unread,
Dec 16, 2012, 12:22:39 PM12/16/12
to php...@googlegroups.com
CakePHP votes +1

--
Larry E. Masters

CalEvans

unread,
Dec 16, 2012, 12:43:10 PM12/16/12
to php...@googlegroups.com
+1

=C=

Phil Sturgeon

unread,
Dec 16, 2012, 3:07:21 PM12/16/12
to php...@googlegroups.com
PyroCMS votes +1
Message has been deleted

FGM at GMail

unread,
Dec 16, 2012, 6:09:52 PM12/16/12
to php...@googlegroups.com
AIUI the quorum and absolute majority are already reached, aren't they
? (not voting)

2012/12/16 Joshua Pekera <jos...@pyrocms.com>:
> +1
>
>
> On Thursday, December 13, 2012 2:41:08 PM UTC-6, Jordi Boggiano wrote:
>>
> --
> You received this message because you are subscribed to the Google Groups
> "PHP Framework Interoperability Group" group.
> To post to this group, send email to php...@googlegroups.com.
> To unsubscribe from this group, send email to
> php-fig+u...@googlegroups.com.
> To view this discussion on the web visit
> https://groups.google.com/d/msg/php-fig/-/qpU7FM3HT9UJ.

Tom Hudson

unread,
Dec 16, 2012, 6:35:35 PM12/16/12
to php...@googlegroups.com
Nice work :)

May I suggest setting the LogLevel constants to the numeric codes for each severity as defined in RFC 5424 (e.g. DEBUG = 7) instead of strings?
I think it would make it a lot easier to implement the setting of a log level to write at (e.g. "Log everything more severe than info level") without making anything else more difficult.

TomH

Matthieu Napoli

unread,
Dec 17, 2012, 3:52:16 AM12/17/12
to php...@googlegroups.com
Regarding the Psr namespace and the "psr/*" name for composer package, psr is already taken on github (https://github.com/psr), is that a problem? That shouldn't be for the PHP namespace but for the composer package maybe?

Drak

unread,
Dec 17, 2012, 4:24:23 AM12/17/12
to php...@googlegroups.com
Please do not discuss anything in this thread. This thread is for voting only. If you want to discuss something, please choose one of the existing threads or start a new one.


--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To post to this group, send email to php...@googlegroups.com.
To unsubscribe from this group, send email to php-fig+u...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msg/php-fig/-/N-jQVBBq208J.

Robert Lemke

unread,
Dec 21, 2012, 4:28:13 AM12/21/12
to php...@googlegroups.com
Hi Jordi,

+1 from TYPO3.

Cheers,
Robert

Jordi Boggiano

unread,
Dec 24, 2012, 8:02:33 AM12/24/12
to php...@googlegroups.com
Heya,

Just thought I'd do a tally because I doubt much is going to happen in
the next few days, and anyway it's already technically passed.

And +1 from myself by the way.

+1 (17): Paul M. Jones, Fabien Potencier, Karma Dordrak, Evert Pot,
Larry Garfield, Lukas Smith, William Durand, Ryan Parman, Brett Bieber,
Paul Dragoonis, Paul Scott, Andre Romcke, Larry Masters, Cal Evans, Phil
Sturgeon, Robert Lemke

-1 (0): ~

26 members, quorum is established and we have an absolute majority.

For the record, the vote ends on the 27th, if anyone still wants their
vote counted.

Mike van Riel

unread,
Dec 27, 2012, 5:00:53 PM12/27/12
to php...@googlegroups.com
+1


--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To post to this group, send email to php...@googlegroups.com.
To unsubscribe from this group, send email to php-fig+u...@googlegroups.com.

Jordi Boggiano

unread,
Jan 4, 2013, 2:52:01 PM1/4/13
to php...@googlegroups.com
> +1 (17): Paul M. Jones, Fabien Potencier, Karma Dordrak, Evert Pot,
> Larry Garfield, Lukas Smith, William Durand, Ryan Parman, Brett Bieber,
> Paul Dragoonis, Paul Scott, Andre Romcke, Larry Masters, Cal Evans, Phil
> Sturgeon, Robert Lemke
>
> -1 (0): ~

Mike van Riel voted as well before the end of the vote on the 27th, so
now that I am back online here is the final tally:

18 out of 26 members voted +1. Nobody else voted. PSR-3 is now
officially in. Thanks everyone!

Whoever has access please merge the PR and rename the file to
accepted/PSR-3-logger-interface.md (please use this filename so the
links I already put in the psr/log package will start working).

Paul Jones

unread,
Jan 4, 2013, 5:04:26 PM1/4/13
to php...@googlegroups.com

On Jan 4, 2013, at 1:52 PM, Jordi Boggiano wrote:

>> +1 (17): Paul M. Jones, Fabien Potencier, Karma Dordrak, Evert Pot,
>> Larry Garfield, Lukas Smith, William Durand, Ryan Parman, Brett Bieber,
>> Paul Dragoonis, Paul Scott, Andre Romcke, Larry Masters, Cal Evans, Phil
>> Sturgeon, Robert Lemke
>>
>> -1 (0): ~
>
> Mike van Riel voted as well before the end of the vote on the 27th, so
> now that I am back online here is the final tally:
>
> 18 out of 26 members voted +1. Nobody else voted. PSR-3 is now
> officially in. Thanks everyone!

Congratulations, and well done to everyone who contributed to the discussion. :-)


-- pmj
Reply all
Reply to author
Forward
0 new messages