arnapou/message-templates

Library - PHP implementation of messagetemplates.org

v1.0.1 2024-09-12 21:29 UTC

This package is auto-updated.

Last update: 2024-10-13 08:21:00 UTC


README

pipeline coverage

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.

Message Templates

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($holeCapturing, ['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]"

Custom capturing & rendering

Create you own implementations of

You can

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

Php versions

DateRef8.38.2
10/09/20241.x, mainร—ร—