README

PSR-3 compatible logger that outputs structured JSON log lines.

Requirements

PHP 8.2+
psr/log ^3.0

Installation

composer require philiprehberger/php-structured-logger

Usage

Basic logging

use PhilipRehberger\StructuredLogger\JsonLogger;

// Log to stdout (default)
$logger = new JsonLogger();
$logger->info('Application started');

// Log to a file
$logger = new JsonLogger(output: '/var/log/app.log');
$logger->info('User logged in', ['user_id' => 42]);

Logging with context

$logger = new JsonLogger(output: 'php://stderr');

$logger->error('Payment failed', [
    'order_id' => 'ORD-123',
    'amount' => 49.99,
    'currency' => 'USD',
]);

Output:

{"timestamp":"2026-03-13T10:00:00+00:00","level":"error","message":"Payment failed","channel":"app","context":{"order_id":"ORD-123","amount":49.99,"currency":"USD"}}

Sensitive data redaction

By default, the following context keys are automatically redacted: password, token, secret, api_key, authorization, credit_card. Redaction applies recursively to nested arrays.

$logger = new JsonLogger();

$logger->info('Auth attempt', [
    'username' => 'alice',
    'password' => 's3cret',
    'token' => 'abc123',
]);
// password and token values replaced with "[REDACTED]"

You can provide a custom list of keys to redact:

$logger = new JsonLogger(
    redactKeys: ['password', 'ssn', 'credit_card'],
);

Persistent context

Use withContext() to create a new logger instance with fields that are automatically included in every log entry:

$logger = new JsonLogger(output: '/var/log/app.log');

$requestLogger = $logger->withContext([
    'request_id' => 'req-abc-123',
    'service' => 'api',
]);

$requestLogger->info('Request received');
$requestLogger->info('Processing complete', ['duration_ms' => 42]);
// Both entries include request_id and service in context

Minimum log level

Use setMinLevel() to filter out log entries below a severity threshold:

use Psr\Log\LogLevel;

$logger = new JsonLogger();
$logger->setMinLevel(LogLevel::WARNING);

$logger->debug('This is skipped');
$logger->info('This is also skipped');
$logger->warning('This is logged');
$logger->error('This is logged');

Custom channel

Use the channel parameter to identify different services or application components:

$logger = new JsonLogger(
    output: '/var/log/payments.log',
    channel: 'payments',
);

$logger->info('Payment processed');
// {"timestamp":"...","level":"info","message":"Payment processed","channel":"payments"}

Log sampling

Use withSampling() to probabilistically sample log output. Messages at error level and above are always logged regardless of the sampling rate:

$logger = new JsonLogger();
$logger->withSampling(0.1); // Only 10% of debug/info/warning/notice messages are written

$logger->info('Might be skipped');
$logger->error('Always logged');

Buffered logging

Use BufferedLogger to batch log entries and flush them together:

use PhilipRehberger\StructuredLogger\BufferedLogger;
use PhilipRehberger\StructuredLogger\JsonLogger;

$logger = new BufferedLogger(new JsonLogger(), bufferSize: 50);

$logger->info('Buffered entry 1');
$logger->info('Buffered entry 2');
$logger->flush(); // Writes all buffered entries

Correlation ID

Use withCorrelationId() to automatically include a correlation ID in every log entry:

$logger = new JsonLogger();
$logger->withCorrelationId('req-abc-123');

$logger->info('Processing request');
// context includes "correlation_id": "req-abc-123"

Multiple output targets

Use MultiLogger to fan out log calls to multiple logger instances:

use PhilipRehberger\StructuredLogger\MultiLogger;
use PhilipRehberger\StructuredLogger\JsonLogger;
use PhilipRehberger\StructuredLogger\EcsLogger;

$jsonLogger = new JsonLogger(output: '/var/log/app.log');
$ecsLogger = new EcsLogger(output: '/var/log/app-ecs.log');

$multi = new MultiLogger([$jsonLogger, $ecsLogger]);
$multi->info('Logged to both targets', ['user_id' => 42]);

Each logger in the array respects its own minimum level and configuration independently.

ECS (Elastic Common Schema) format

Use EcsLogger to output logs in Elastic Common Schema format:

use PhilipRehberger\StructuredLogger\EcsLogger;

$logger = new EcsLogger(output: '/var/log/app-ecs.log', channel: 'api');
$logger->info('Request processed', ['http.method' => 'GET', 'url.path' => '/users']);

Output:

{"@timestamp":"2026-04-01T10:00:00+00:00","log.level":"info","message":"Request processed","ecs.version":"8.11","service.name":"api","http.method":"GET","url.path":"/users"}

Structured exception formatting

When an exception key containing a Throwable is passed in context, both JsonLogger and EcsLogger automatically serialize it into structured fields:

try {
    riskyOperation();
} catch (\Throwable $e) {
    $logger->error('Operation failed', ['exception' => $e]);
}

The exception is serialized into error.type, error.message, error.code, and error.stack_trace fields. You can also use ExceptionSerializer directly:

use PhilipRehberger\StructuredLogger\ExceptionSerializer;

$data = ExceptionSerializer::serialize($exception, traceDepth: 5);
// ['error.type' => 'RuntimeException', 'error.message' => '...', 'error.code' => 0, 'error.stack_trace' => [...]]

Output Format

Each log line is a single JSON object with the following fields:

Field	Type	Description
`timestamp`	string	ISO 8601 timestamp
`level`	string	PSR-3 log level
`message`	string	Log message
`channel`	string	Application/service name (default: `app`)
`context`	object	Additional data (omitted when empty)

API

`JsonLogger`

Parameter	Type	Default	Description
`output`	`string`	`'php://stdout'`	File path or PHP stream wrapper
`channel`	`string`	`'app'`	Application/service identifier
`redactKeys`	`string[]`	`['password', 'token', 'secret', 'api_key', 'authorization', 'credit_card']`	Context keys to redact

Method	Returns	Description
`withContext(array $context)`	`self`	New logger instance with persistent context fields
`setMinLevel(string $level)`	`void`	Set minimum log level threshold
`withSampling(float $rate)`	`self`	Enable probabilistic log sampling (0.0-1.0)
`withCorrelationId(string $id)`	`self`	Set correlation ID for all log entries

All PSR-3 log methods are available: emergency(), alert(), critical(), error(), warning(), notice(), info(), debug(), log().

`BufferedLogger`

Parameter	Type	Default	Description
`logger`	`JsonLogger`		Wrapped logger to flush entries to
`bufferSize`	`int`	`100`	Flush when buffer reaches this size

Method	Returns	Description
`flush()`	`void`	Write all buffered entries to the wrapped logger
`count()`	`int`	Number of entries currently buffered

`MultiLogger`

Parameter	Type	Default	Description
`loggers`	`LoggerInterface[]`	`[]`	Logger instances to fan out calls to

All PSR-3 log methods are available. Each call is forwarded to every logger in the array.

`EcsLogger`

Parameter	Type	Default	Description
`output`	`string`	`'php://stdout'`	File path or PHP stream wrapper
`channel`	`string`	`'app'`	Service name (`service.name`)

Method	Returns	Description
`setMinLevel(string $level)`	`void`	Set minimum log level threshold

All PSR-3 log methods are available. Output follows the Elastic Common Schema (ECS 8.11) format.

`ExceptionSerializer`

Method	Returns	Description
`serialize(Throwable $exception, int $traceDepth = 10)`	`array`	Serialize exception into structured fields

Returns an array with keys: error.type, error.message, error.code, error.stack_trace.

`LogEntry`

Immutable value object representing a single log entry. Implements JsonSerializable.

Method	Returns	Description
`toArray()`	`array`	Entry as associative array
`toJson()`	`string`	Entry as JSON string
`jsonSerialize()`	`array`	For `json_encode()` support

Development

composer install
vendor/bin/phpunit
vendor/bin/pint --test

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT

philiprehberger / php-structured-logger

Maintainers

Package info

Fund package maintenance!

Statistics

Security