README

lsr/logging provides a PSR-3 logger with file storage, configurable formatting, exception/database-event helpers and log archiving. Its namespace is Lsr\Logging; the repository directory is named lsr-logger, but the Composer package is lsr/logging.

Requirements

PHP >=8.4 and the zip extension.
PSR Log (*), LSR helpers ^0.3 and Dibi ^5; see composer.json.
A writable log directory when using the supplied file storage implementations. Storage creates missing directories and raises filesystem exceptions when it cannot write.
Optional Nette DI integration for services.neon; direct logger construction does not require a DI container.

Installation

composer require lsr/logging

Daily file logging

require __DIR__ . '/vendor/autoload.php';

use Lsr\Logging\Logger;

$logger = new Logger(__DIR__ . '/var/log', 'application');
$logger->info('Application started', ['environment' => 'development']);

The default storage uses the legacy text formatter and writes files named application-YYYY-MM-DD.log. The date is resolved when writing, so a long-lived logger moves to the next day's file. PSR-3 level methods such as info(), warning() and error() are available through Logger.

Logger::exception($throwable) writes an error message and a debug trace. logDb($event) accepts a Dibi event. These helpers can include sensitive error/query details, so choose access controls and retention suitable for your application.

Choosing storage and format

Use LoggerFactory to select a formatter without assembling the storage pipeline yourself:

use Lsr\Logging\Formatter\JsonLogFormatter;
use Lsr\Logging\LoggerFactory;

$logger = (new LoggerFactory())->createDaily(
    __DIR__ . '/var/log',
    'application-json',
    new JsonLogFormatter(),
);
$logger->warning('Import rejected', ['recordId' => 42]);

JsonLogFormatter emits JSON with a timestamp, severity, message and optional context. Other supplied formatters include legacy text, LSR and syslog formats. A syslog formatter formats a record; it is not a network syslog transport.

Storage choices include SimpleFileStorage, DailyLogStorage and RotatingFileStorage. LoggerFactory::createRotating() creates size-based rotating file storage; its maxFileSize argument is in bytes. Custom implementations can use StorageInterface and LogFormatterInterface.

Framework configuration

services.neon registers the logger, clock, context normalization, formatters, factory and LogArchiver. It expects an application constants.appDir parameter and exposes logger.dir, logger.name and logger.logLife. Include this file in an existing Nette DI application and override those parameters as appropriate.

Log archiving is a separate service; constructing or writing through a logger does not schedule retention work. Consult LogArchiver before wiring its operations into the application's scheduler.

Development

CI runs the complete suite on PHP 8.4 and 8.5 without external services. Install the PHP extensions listed in .github/workflows/ci.yml, including zip, then run:

composer install --prefer-dist --no-interaction --no-progress
composer cs
vendor/bin/phpstan analyse --no-progress
vendor/bin/phpunit --no-coverage

Keep proc_open enabled for concurrent-writer tests and run as a non-root user so filesystem permission checks are meaningful. The checkout must be writable; the bootstrap creates tests/logs/ and a read-only test directory within it. CI sets PHP's memory limit to 1 GB, matching composer test; use the same limit locally. composer test additionally enables Xdebug coverage mode, which needs a compatible coverage driver. See phpunit.xml and phpstan.neon.

Run composer cs to check PHP coding style and composer cs:fix (or composer cbf) to apply fixes with PHP CS Fixer. The rules and source paths are defined in .php-cs-fixer.php.

AI coding assistance

See LSR Skills for AI agent skills for working with the LSR framework.

License

Licensed under the MIT License.

lsr / logging

Package info

Security

Statistics