Download the PHP package solophp/logger without Composer

Solo PSR-3 Logger

A lightweight PSR-3 compliant logger with timezone-aware log rotation, pluggable formatters (line / JSON / logfmt), context interpolation and safe, lock-based file writes.

Installation

Install via composer:

Usage

Basic usage:

With custom timezone for rotation file timestamps:

Change log file or rotation timezone at runtime:

Features

• PSR-3 LoggerInterface compliance (psr/log ^3.0)
• Pluggable formatters: Line, JSON (NDJSON), Logfmt — or your own via FormatterInterface
• Context interpolation for PSR-3 {placeholder} tokens
• Log rotation with size, time, or combined strategies
• Timezone-aware rotation timestamps
• Retention via maxFiles — oldest rotated files are auto-pruned
• Minimum level filtering via setMinLevel()
• Automatic log directory creation
• Safe append-with-lock writes (LOCK_EX)
• Throws RuntimeException on write/directory-create failures instead of silent drop
• Modular architecture with a clear separation of concerns

Requirements

• PHP 8.1 or higher
• psr/log package

Log Levels

The logger supports all PSR-3 log levels:

• emergency
• alert
• critical
• error
• warning
• notice
• info
• debug

Log Rotation

The logger supports automatic log rotation with multiple strategies to prevent disk overflow and simplify log management.

Rotation Strategies

Size-based rotation

Rotates logs when the file reaches a specified size limit:

Time-based rotation

Rotates logs at specified time intervals:

Combined rotation

Rotates logs when either size OR time condition is met:

Runtime Configuration

You can change rotation settings at runtime:

File Naming

When rotation occurs, files are created with timestamps:

Examples:

• app_2025-08-03_14-30-15.log
• error_2025-08-03_09-45-30.log

Best Practices

• Size limits: Set reasonable limits (1-10MB) to prevent disk overflow
• File count: Limit the number of files to save space
• Time intervals: Use standard intervals (1 hour, 6 hours, 1 day)
• Monitoring: Regularly check log directory size
• Archiving: Consider archiving old logs for long-term storage

Examples

Daily rotation with 30-day retention

Size-based with 50MB total limit

Combined strategy for high-traffic applications

Formatters

Every log record is rendered by a FormatterInterface implementation. The default is LineFormatter; pass a different one via the constructor or setFormatter() at runtime.

LineFormatter (default)

Plain text with a configurable template and PSR-3 {placeholder} interpolation.

Template tokens: {time}, {level}, {message}. Context keys referenced inside the message (e.g. "User {user_id}") are resolved against the $context array.

JsonFormatter

Single-line JSON (NDJSON) — fits ELK / Loki / Graylog / Datadog pipelines. Context keys are merged into the top-level record; reserved keys (time, level, message) are namespaced under context to avoid collisions. \Throwable, \DateTimeInterface and \Stringable objects are normalised.

LogfmtFormatter

Heroku/Splunk-style key=value pairs. Values with whitespace or quotes are escaped.

Writing a custom formatter

Implement Solo\Logger\Formatter\FormatterInterface — a single format() method. The returned string MUST NOT include a trailing newline (the Logger appends one).

Error Handling

If writing a log record fails (unwritable path, full disk, unable to create directory), the logger throws \RuntimeException rather than silently dropping the record. Wrap calls in a try/catch if your application must tolerate log-sink failures.

Development

License

MIT License. See LICENSE file for details.