arnapou / message-templates
Library - PHP implementation of messagetemplates.org
Requires
- php: ~8.2.0 || ~8.3.0
- psr/log: ^2.0 || ^3.0
Requires (Dev)
- ext-intl: *
- friendsofphp/php-cs-fixer: ^3.52
- phpstan/extension-installer: ^1.3
- phpstan/phpstan: ^1.10
- phpstan/phpstan-deprecation-rules: ^1.1
- phpstan/phpstan-phpunit: ^1.3
- phpstan/phpstan-strict-rules: ^1.5
- phpunit/php-code-coverage: ^11.0
- phpunit/phpunit: ^11.0
README
PHP implementation of messagetemplates.org (GitHub).
Installation
composer require arnapou/message-templates
packagist ๐๏ธ arnapou/message-templates
Summary
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($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
- 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
Date | Ref | 8.3 | 8.2 |
---|---|---|---|
10/09/2024 | 1.x, main | ร | ร |