xp-framework/logging

Logging for the XP Framework

v11.2.0 2024-03-28 22:23 UTC

README

Build status on GitHub XP Framework Module BSD Licence Requires PHP 7.0+ Supports PHP 8.0+ Latest Stable Version

Logging for the XP Framework.

Example

use util\log\Logging;
use lang\Throwable;
use peer\ConnectException;

$logger= Logging::named('service')->toConsole();
$logger->info('Starting application');

try {
  $service->operation();
} catch (ConnectException $e) {
  $logger->warn('Service not available', $e);
} catch (Throwable $t) {
  $logger->error('Error during service invocation', $t);
}

Levels

This library supports the following levels: DEBUG, INFO, WARN and ERROR. As seen above, messages can be logged using methods named after these levels. All methods have a printf-style variant:

  • debug(var... $args) and debugf(string $format, var... $args).
  • info(var... $args) and infof(string $format, var... $args).
  • warn(var... $args) and warnf(string $format, var... $args).
  • error(var... $args) and errorf(string $format, var... $args).

Appenders

The following appenders are available:

  • util.log.FileAppender(string $filename) - Logs to a local file
  • util.log.ConsoleAppender() - Logs to console
  • util.log.ColoredConsoleAppender() - Logs to console using colors depending on log level
  • util.log.SmtpAppender(string $email, string $prefix= "", bool $sync= true) - Logs by email to a given email address
  • util.log.StreamAppender(io.streams.OutputStream $out) - Logs to any output stream from io.streams.
  • util.log.SyslogAppender(string $identifier, int $facility= LOG_USER) - Logs using syslog facility
  • util.log.SyslogUdpAppender(string $ip= '127.0.0.1', int $port= 514, string $identifier= null, int $facility= LOG_USER, string $hostname= null) - Logs using syslog protocol over UDP
  • util.log.BufferedAppender() - Logs to a memory buffer

Layout

The default log layout includes time, pid, level and message implemented by the util.log.layout.DefaultLayout class. It renders as follows:

[13:43:39  4368  info] Starting application

The log layout can be changed by instantiating the util.log.layout.PatternLayout, passing a format string and using the appenders setLayout() method to use it. The format string consists of format tokens preceded by a percent sign (%) and any other character. The following format tokens are supported:

  • %m - Message
  • %c - Category name
  • %l - Log level - lowercase
  • %L - Log level - uppercase
  • %d - Date in YYYY-MM-DD
  • %t - Time in HH:MM:SS
  • %p - Process ID
  • %% - A literal percent sign (%)
  • %n - A line break
  • %x - Context information, if available

Configuration

Instead of using the Logging DSL to create your log setup programmatically, you can use the configuration API, which works with INI files:

[default]
uses=console|syslog|files

[console]
class=util.log.ConsoleAppender
level=ALL

[files]
class=util.log.FileAppender
args="/var/log/server.log"
level=ALL

[syslog]
class=util.log.SyslogUdpAppender
args=127.0.0.1|514|server
level=WARN|ERROR

Further reading