README

PHP implementation of messagetemplates.org (GitHub).

Installation

composer require arnapou/message-templates

packagist 👉️ arnapou/message-templates

Summary

🔗 Details of specification

A language-neutral specification for 1) capturing, and 2) rendering, structured log events in a format that’s both human-friendly and machine-readable.

Example using this PHP implementation

Message template logger

This is a logger as described in the specification, which does

• capturing
• rendering

Because of the different signature of PSR-3, we use a MessageTemplateLoggerInterface inspired by the PSR-3 LoggerInterface

use Arnapou\MessageTemplates\MessageTemplateLogger;

$logger = new MessageTemplateLogger($psrLogger);
$logger->emergency('User {username} logged in from {ip_address}', 'Alice', '123.45.67.89');
$logger->alert('User {username} logged in from {ip_address}', 'Alice', '123.45.67.89');
$logger->critical('User {username} logged in from {ip_address}', 'Alice', '123.45.67.89');
$logger->error('User {username} logged in from {ip_address}', 'Alice', '123.45.67.89');
$logger->warning('User {username} logged in from {ip_address}', 'Alice', '123.45.67.89');
$logger->notice('User {username} logged in from {ip_address}', 'Alice', '123.45.67.89');
$logger->info('User {username} logged in from {ip_address}', 'Alice', '123.45.67.89');
$logger->debug('User {username} logged in from {ip_address}', 'Alice', '123.45.67.89');
$logger->log($level, 'User {username} logged in from {ip_address}', 'Alice', '123.45.67.89');

Message template PSR-3 logger

This is a pure PSR-3 LoggerInterface decorator with Message Template capabilities.

It does only the "rendering" part of the specification, using the PSR-3 context as a captured set of properties to render.

You can send MORE elements in the context than what is needed by the template, but you cannot send LESS.

This is like a message validation phase (even if you don't want to render the template).

This logger has an injected HoleRenderingInterface allowing you to customize the rendering of objects into the message BEFORE being rendered in another way by the PSR-3 decorated logger implementation.

use Arnapou\MessageTemplates\MessageTemplatePsrLogger;

$logger = new MessageTemplatePsrLogger($psrLogger);
$logger->emergency('User {username} logged in from {ip_address}', ['username'=> 'Alice', 'ip_address' => '123.45.67.89']);
$logger->alert('User {username} logged in from {ip_address}', ['username'=> 'Alice', 'ip_address' => '123.45.67.89']);
$logger->critical('User {username} logged in from {ip_address}', ['username'=> 'Alice', 'ip_address' => '123.45.67.89']);
$logger->error('User {username} logged in from {ip_address}', ['username'=> 'Alice', 'ip_address' => '123.45.67.89']);
$logger->warning('User {username} logged in from {ip_address}', ['username'=> 'Alice', 'ip_address' => '123.45.67.89']);
$logger->notice('User {username} logged in from {ip_address}', ['username'=> 'Alice', 'ip_address' => '123.45.67.89']);
$logger->info('User {username} logged in from {ip_address}', ['username'=> 'Alice', 'ip_address' => '123.45.67.89']);
$logger->debug('User {username} logged in from {ip_address}', ['username'=> 'Alice', 'ip_address' => '123.45.67.89']);
$logger->log($level, 'User {username} logged in from {ip_address}', ['username'=> 'Alice', 'ip_address' => '123.45.67.89']);

Direct usage

All is properly decoupled in the lib.

Thus, you can manipulate a template message as you want.

use Arnapou\MessageTemplates\MessageTemplate;
use Arnapou\MessageTemplates\Hole\DefaultImplementation;

$template = new MessageTemplate('User {username} logged in from {$ip_address:[%s]}');

$template->simplifiedTemplate();
// "User {username} logged in from {ip_address}"

foreach($template->combine('Alice', '123.45.67.89') as [$segment, $value]) {
    // ["User ", null]
    // [<Hole Object, name: username>, 'Alice']
    // [" logged in from ", null]
    // [<Hole Object, name: ip_address>, '123.45.67.89']
}

$holeCapturing = new DefaultImplementation();
$template->capture($holeCapturing, 'Alice', '123.45.67.89');
// ['username' => 'Alice', 'ip_address' => '123.45.67.89']

$holeRendering = new DefaultImplementation();
$template->render($holeRendering, ['username' => 'Alice', 'ip_address' => '123.45.67.89']);
// "User Alice logged in from [123.45.67.89]"

$template->captureAndRender($holeCapturing, $holeRendering, 'Alice', '123.45.67.89');
// "User Alice logged in from [123.45.67.89]"

Alignment

Syntax: {variable,alignment} with alignment being a pure integer (ex: 123 or -123).

The rendering has the same behaviour as sprintf:

• positive (ex: 10) adds spaces on the left (text align right)
• negative (ex: -10) adds spaces on the right (text align left)

┌──────────────────┬───────────────┬───────────────────────────────────┐
│ examples         │ value         │ result                            │
├──────────────────┼───────────────┼───────────────────────────────────┤
│ {value,10}       │ "Hello"       │ "     Hello"                      │
│ {value,-10}      │ "Hello"       │ "Hello     "                      │
└──────────────────┴───────────────┴───────────────────────────────────┘

Format

Syntax: {variable:format} with format being a string used by the renderer.

┌─────────────┬──────────────────┬───────────────┬─────────────────────────────┐
│ type        │ examples         │ value         │ result                      │
├─────────────┼──────────────────┼───────────────┼─────────────────────────────┤
│ string      │ {value:%10}      │ "Hello"       │ '     Hello'                │
│ (= sprintf) │ {value:%-10}     │ "Hello"       │ 'Hello     '                │
│             │ {value:__%s__}   │ "Hello"       │ '__Hello__'                 │
├─────────────┼──────────────────┼───────────────┼─────────────────────────────┤
│ int         │ {value:%05d}     │ 123           │ '00123'                     │
│ (= sprintf) │ {value:%+'_10d}  │ 123           │ '______+123'                │
│             │ {value:foo %s}   │ 123           │ 'foo 123'                   │
├─────────────┼──────────────────┼───────────────┼─────────────────────────────┤
│ float       │ {value:%05f}     │ 3.1           │ '00003'                     │
│ (= sprintf) │ {value:%.3f}     │ 3.1           │ '3.100'                     │
│             │ {value:foo %s}   │ 3.1           │ 'foo 3.1'                   │
├─────────────┼──────────────────┼───────────────┼─────────────────────────────┤
│ bool        │ {value}          │ true / false  │ 'TRUE' / 'FALSE'            │
│             │ {value:TF}       │ true / false  │ 'TRUE' / 'FALSE'            │
│             │ {value:tf}       │ true / false  │ 'true' / 'false'            │
│             │ {value:YN}       │ true / false  │ 'YES' / 'NO'                │
│             │ {value:yn}       │ true / false  │ 'yes' / 'no'                │
│             │ {value:OO}       │ true / false  │ 'ON' / 'OFF'                │
│             │ {value:oo}       │ true / false  │ 'on' / 'off'                │
│             │ {value:01}       │ true / false  │ '1' / '0'                   │
├─────────────┼──────────────────┼───────────────┼─────────────────────────────┤
│ array       │ {value}          │ ['foo' => 1]  │ 'foo: 1'                    │
│             │ {value:json}     │ ['foo' => 1]  │ '{"foo":1}'                 │
│             │ {value:length}   │ [1, 2, 3]     │ '3'                         │
│             │ {value:.foo}     │ ['foo' => 1]  │ '1'                         │
├─────────────┼──────────────────┼───────────────┼─────────────────────────────┤
│ datetime    │ {value}          │ PHP object    │ '2024-09-11T12:15:10+02:00' │
│ (= method   │ {value:Y-m-d}    │ PHP object    │ '2024-09-11'                │
│ 'format')   │ {value:H:i:s}    │ PHP object    │ '12:15:10'                  │
└─────────────┴──────────────────┴───────────────┴─────────────────────────────┘

Custom capturing & rendering

Create you own implementations of

• capturing: HoleCapturingInterface
• rendering: HoleRenderingInterface

You can

• inject them into a MessageTemplateLogger
• use capturing implementation directly into MessageTemplate::capture()
• use rendering implementation directly into MessageTemplate::render()
• use both implementations directly into MessageTemplate::captureAndRender()

This lib has a DefaultImplementation which should be enough for most of your common needs.

Php versions