Socarrat\Logging

Robust logging library for every application.

Features

• Simple yet reliable logging.
• Supports every type of output you like.
• You can write your own logger implementation if you need something custom.
• Multiple output streams.
• Static methods: call the logger from whichever part of your application without needing to have a reference to some logging object!
• Minimum log levels.

Installation

You can install this library through Packagist: composer require socarrat/logging.

Examples

use Socarrat\Logging\Loggers\FileLogger;
use Socarrat\Logging\LoggingManager;
use Socarrat\Logging\LogLevel;

$fileLogger = new FileLogger(
	getFilePath: function(LogLevel $level, string $msg) {
		$l = strtolower($level->toString());
		return __DIR__."/test.$l.log";
	}
);

LoggingManager::addLogger($fileLogger);
LoggingManager::setMinimumLogLevel(LogLevel::LOG_WARNING);

LoggingManager::log(LogLevel::LOG_CRITICAL, "Hello CRITICAL"); //=> logs to test.critical.log
LoggingManager::log(LogLevel::LOG_ERROR, "Hello ERROR");       //=> logs to test.debug.log
LoggingManager::log(LogLevel::LOG_WARNING, "Hello WARNING");   //=> logs to test.warning.log

LoggingManager::log(LogLevel::LOG_NOTICE, "Hello NOTICE");     //=> will not be logged due to minimum log level log
LoggingManager::log(LogLevel::LOG_INFO, "Hello INFO");         //=> will not be logged
LoggingManager::log(LogLevel::LOG_DEBUG, "Hello DEBUG");       //=> will not be logged

You can find the output of this script here. See more examples in the examples/ directory.

Built-in loggers

The following loggers are shipped with this library under the namespace Socarrat\Logging\Loggers. You could also implement your own loggers; see the Logger interface and LoggingManager::addLogger.

FileLogger

Outputs logs into a file.

new FileLogger(\Closure $getFilePath)

Constructs a new file logger. You can pass a closure into the constructor, which is called on each log and returns the filename the log should be sent to. It receives two positional arguments: the LogLevel and the string to log.

You can replace the filepath getter later on by calling FileLogger::setFilePathGetter(\Closure $getFilePath).

NullLogger

This logger does nothing with the logs.

API

class Socarrat\Logging\LoggingManager

This is the central logging manager; you should use this to log things.

static public function addLogger(Logger $logger): int

Adds a logger instance to use. Returns the index which has been assigned to the logger. If multiple loggers have been set, each of them is called.

Parameter name	Type	Default value	Description
$logger	Logger	-	The logger instance to add.

static public function log(LogLevel $level, string $message)

Logs the given message at the given log level using the logger that has been set. If multiple loggers have been set, each of them is called.

Parameter name	Type	Default value	Description
$level	LogLevel	-	The level at which to log.
$message	string	-	The log message.

static public function setMinimumLogLevel(LogLevel $level)

Sets the minimum log level. Log messages that have a lower level will not be logged.

Example: the minimum log level is LOG_NOTICE. Logs with LOG_DEBUG will not be logged, unlike LOG_ERROR logs.

Parameter name	Type	Default value	Description
$level	LogLevel	-	The minimum level at which to log.

abstract class Socarrat\Logging\Logger

This is the base class for loggers. All loggers should extend it.

abstract public function log(LogLevel $level, string $message)

Logs the given message at the given log level. You should not call this directly, use LogManager::log instead.

Parameter name	Type	Default value	Description
$level	LogLevel	-	The level at which to log.
$message	string	-	The log message.

enum Socarrat\Logging\LogLevel: int

Contains the RFC 5424 log levels.

Log level	Situation	ID
LOG_EMERGENCY	System is unusable.	2
LOG_ALERT	Action must be taken immediately.	2
LOG_CRITICAL	Critical conditions.	2
LOG_ERROR	Error conditions.	3
LOG_WARNING	Warning conditions.	4
LOG_NOTICE	Notice: normal but significant conditions.	5
LOG_INFO	Informational messages.	6
LOG_DEBUG	Debug-level messages.	7

LogLevel::toString() will return the stringified version of the log level, e.g. calling (LogLevel::LOG_ALERT)->toString() will result in ALERT.

Copyright

(c) 2023 Romein van Buren. Licensed under the MIT license.

For the full copyright and license information, please view the license.md file that was distributed with this source code.