PHPackages                             vista-php/logger - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Logging & Monitoring](/categories/logging)
4. /
5. vista-php/logger

ActiveLibrary[Logging & Monitoring](/categories/logging)

vista-php/logger
================

PSR-3 compliant logging package for PHP 8.3+.

v1.0.0(4mo ago)10MITPHPPHP ^8.3CI passing

Since Feb 21Pushed 4mo agoCompare

[ Source](https://github.com/vista-php/logger)[ Packagist](https://packagist.org/packages/vista-php/logger)[ RSS](/packages/vista-php-logger/feed)WikiDiscussions main Synced today

READMEChangelog (1)Dependencies (5)Versions (2)Used By (0)

vista-php/logger
================

[](#vista-phplogger)

[![Latest Version](https://camo.githubusercontent.com/75c49ac2aa73d1962ee7ce8007ead5c9606255d4f93c8aeef48e5e4cfeaece91/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f76697374612d7068702f6c6f67676572)](https://camo.githubusercontent.com/75c49ac2aa73d1962ee7ce8007ead5c9606255d4f93c8aeef48e5e4cfeaece91/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f76697374612d7068702f6c6f67676572)[![PHP Version](https://camo.githubusercontent.com/0a308cd644a8a86af360d0c9734ade184bc82a6c9aeae8dd63c841d77245fa8e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f76697374612d7068702f6c6f67676572)](https://camo.githubusercontent.com/0a308cd644a8a86af360d0c9734ade184bc82a6c9aeae8dd63c841d77245fa8e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f76697374612d7068702f6c6f67676572)[![License](https://camo.githubusercontent.com/714436408b69917fcc51221a05bcec183fb4f6a5547128e2eac6c6603d97c768/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f76697374612d7068702f6c6f67676572)](https://camo.githubusercontent.com/714436408b69917fcc51221a05bcec183fb4f6a5547128e2eac6c6603d97c768/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f76697374612d7068702f6c6f67676572)[![CI](https://github.com/vista-php/logger/actions/workflows/ci.yml/badge.svg)](https://github.com/vista-php/logger/actions/workflows/ci.yml/badge.svg)

PSR-3 compliant logging package for PHP 8.3+.

Designed for clean architecture, strict correctness, and framework-quality maintainability.

No hidden state. No speculative abstractions. Explicit, configurable failure semantics.

---

Table of Contents
-----------------

[](#table-of-contents)

- [Philosophy](#philosophy)
- [Features](#features)
- [Requirements](#requirements)
- [Installation](#installation)
- [Architecture Overview](#architecture-overview)
    - [Core Principles](#core-principles)
- [Basic Usage](#basic-usage)
- [Log Levels](#log-levels)
- [LogRecord](#logrecord)
- [Multiple Handlers](#multiple-handlers)
    - [Execution Semantics](#execution-semantics)
- [Handlers](#handlers)
    - [StreamHandler](#streamhandler)
        - [Custom Formatter](#custom-formatter)
        - [Failure Strategies](#failure-strategies)
    - [NullHandler](#nullhandler)
- [Formatters](#formatters)
    - [LineFormatter](#lineformatter-default)
    - [JsonFormatter](#jsonformatter)
- [Message Interpolation](#message-interpolation)
- [Failure Semantics](#failure-semantics)
- [Design Decisions](#design-decisions)
- [Testing Philosophy](#testing-philosophy)
- [Versioning](#versioning)
- [Why not Monolog?](#why-not-monolog)
- [License](#license)
- [Contributing](#contributing)
    - [Non-Goals](#non-goals)
    - [Development Setup](#development-setup)

---

Philosophy
----------

[](#philosophy)

`vista-php/logger` is a minimal, infrastructure-level logging foundation.

It strictly implements the PSR-3 contract while enforcing clear architectural boundaries:

- Validation occurs at the API boundary.
- Log records are immutable and treated as data carriers.
- Handlers encapsulate output policy.
- Formatters encapsulate serialization.
- Failure behavior is explicit and configurable.

The package prioritizes clarity, determinism, and explicit behavior over feature breadth.

---

Features
--------

[](#features)

- Strict PSR-3 compliance
- Immutable `LogRecord` value objects
- Clean SRP-driven architecture
- Explicit log level validation
- Stream-based logging
- Pluggable formatters
- Deterministic, environment-independent behavior
- Fail-fast on programmer errors
- Configurable failure strategies
- Explicit multi-handler execution semantics
- No global state
- No hidden side effects

---

Requirements
------------

[](#requirements)

- PHP 8.3+
- psr/log ^3.0

Tested against PHP 8.3, 8.4, and 8.5.

---

Installation
------------

[](#installation)

```
composer require vista-php/logger
```

---

Architecture Overview
---------------------

[](#architecture-overview)

The logging pipeline is intentionally simple and explicit:

```
Logger
  → LogRecord (immutable)
    → HandlerInterface
        → FormatterInterface
            → Output (file / stream)

```

### Core Principles

[](#core-principles)

- Strict Single Responsibility (SRP)
- Clear API boundary validation
- Immutable value objects
- Explicit failure semantics
- Fail-fast philosophy
- No speculative extension points
- Production-ready, minimal surface area

---

Basic Usage
-----------

[](#basic-usage)

```
use Vista\Logger\Logger;
use Vista\Logger\Handlers\StreamHandler;
use Psr\Log\LogLevel;

$logger = new Logger(
    new StreamHandler(__DIR__ . '/app.log', LogLevel::INFO)
);

$logger->info('User {name} logged in', ['name' => 'John']);
```

---

Log Levels
----------

[](#log-levels)

All PSR-3 log levels are supported:

- `emergency`
- `alert`
- `critical`
- `error`
- `warning`
- `notice`
- `info`
- `debug`

Invalid levels throw `InvalidArgumentException` immediately, even if no handlers are registered.

Validation occurs at the `Logger` API boundary.

---

`LogRecord`
-----------

[](#logrecord)

Each log entry is represented by an immutable `LogRecord`:

```
final class LogRecord
{
    public readonly string $level;
    public readonly string $message;
    public readonly array $context;
    public readonly DateTimeImmutable $datetime;
}
```

Records are created exclusively by the `Logger` and passed to handlers. They are treated as immutable data carriers.

---

Multiple Handlers
-----------------

[](#multiple-handlers)

You may register multiple handlers:

```
$logger = new Logger($handlerA, $handlerB);
```

### Execution Semantics

[](#execution-semantics)

Handlers are executed sequentially.

If any handler throws an exception:

- Execution stops immediately.
- Subsequent handlers are not executed.
- The exception bubbles up to the caller.

This behavior is intentional and aligns with the fail-fast design philosophy.

---

Handlers
--------

[](#handlers)

### `StreamHandler`

[](#streamhandler)

Writes log records to a file or stream.

- Filters by minimum log level
- Delegates formatting
- Appends output using `FILE_APPEND | LOCK_EX`
- Supports any stream URI (e.g. `php://stdout`)
- Does not manage stream resources manually
- Does not buffer
- Does not rotate files ```
    use Vista\Logger\Handlers\StreamHandler;
    use Psr\Log\LogLevel;

    $handler = new StreamHandler(
        path: 'php://stdout',
        minLevel: LogLevel::WARNING
    );
    ```

> Note: File locking relies on underlying filesystem semantics Behavior may vary on certain network filesystems.

#### Custom Formatter

[](#custom-formatter)

You can provide a custom formatter implementation:

```
use Vista\Logger\Handlers\StreamHandler;
use Vista\Logger\Formatters\JsonFormatter;
use Psr\Log\LogLevel;

$handler = new StreamHandler(
    path: __DIR__ . '/app.log',
    minLevel: LogLevel::INFO,
    formatter: new JsonFormatter()
);
```

Any implementation of `FormatterInterface` can be injected.

#### Failure Strategies

[](#failure-strategies)

By default, write failures are reported via `error_log()` and do not interrupt application flow.

You can use `StrictFailureStrategy` to throw a `RuntimeException` on write failures:

```
use Vista\Logger\Failure\StrictFailureStrategy;

$handler = new StreamHandler(
    path: __DIR__ . '/app.log',
    minLevel: LogLevel::INFO,
    failureStrategy: new StrictFailureStrategy()
);
```

- Default: `ErrorLogFailureStrategy`
- Alternative: `StrictFailureStrategy`
- Custom implementations of `FailureStrategy` can be injected

Failure handling is explicit and local to each handler.

### `NullHandler`

[](#nullhandler)

Discards all log records (Null Object pattern).

Useful for testing or conditional logging.

---

Formatters
----------

[](#formatters)

### `LineFormatter` (default)

[](#lineformatter-default)

Human-readable single-line output:

```
[2026-02-17 14:32:10] info: User John logged in {"id":123}

```

Characteristics:

- Newline-terminated
- JSON context
- `JSON_THROW_ON_ERROR`
- No trailing whitespace

---

### `JsonFormatter`

[](#jsonformatter)

Machine-friendly structured logging:

```
{"timestamp":"2026-02-17T14:32:10+00:00","level":"info","message":"User John logged in","context":{"id":123}}
```

Characteristics:

- ISO 8601 timestamps
- Single-line JSON
- Newline-terminated
- `JSON_THROW_ON_ERROR`

---

Message Interpolation
---------------------

[](#message-interpolation)

PSR-3 style placeholder replacement:

```
$logger->info('Hello {name}', ['name' => 'John']);
```

- Only scalar and `Stringable` values are interpolated
- Non-interpolatable context values remain available to formatters
- Interpolation does not mutate context
- Missing placeholders are left untouched

---

Failure Semantics
-----------------

[](#failure-semantics)

- Invalid log levels throw `InvalidArgumentException` immediately
- JSON encoding failures throw `JsonException`
- `StreamHandler` reports write failures via `error_log()` by default
- Failure handling is configurable via `FailureStrategy`
    - Strict mode escalates write failures via `RuntimeException`
    - Multi-handler execution is fail-fast
    - No silent swallowing of programmer errors

---

Design Decisions
----------------

[](#design-decisions)

This package intentionally avoids:

- Async logging
- Channel systems
- Container integration
- Configuration loaders
- Event dispatchers
- Log rotation
- Buffering layers
- Implicit processors
- Speculative abstractions

The goal is a clean, extensible foundation that can be composed into larger systems without architectural debt.

---

Testing Philosophy
------------------

[](#testing-philosophy)

- PHPUnit 12
- Deterministic timestamps
- Behavior-focused tests
- No brittle raw string comparisons
- No testing of private implementation details
- Strict resource cleanup
- PHPStan level 10 clean

---

Versioning
----------

[](#versioning)

This package adheres to Semantic Versioning (SemVer).

---

Why not Monolog?
----------------

[](#why-not-monolog)

`monolog/monolog` is a powerful, feature-rich logging library and the ecosystem standard. If you need dozens of handlers, complex pipelines, buffering strategies, or broad integrations, Monolog is an excellent choice.

`vista-php/logger` is intentionally different.

It provides a strict, minimal PSR-3 implementation focused on architectural clarity, immutable log records, explicit failure semantics, and a small, predictable surface area. There are no channels, no buffering layers, no hidden processors, and no speculative abstractions.

Choose `Monolog` for ecosystem breadth. Choose `vista-php/logger` for a clean, framework-grade logging foundation with explicit behavior and minimal complexity.

---

License
-------

[](#license)

MIT

---

Contributing
------------

[](#contributing)

Contributions are welcome, but this package is intentionally minimal and opinionated.

Before opening a pull request, please ensure:

- The change aligns with the core principles (SRP, minimal surface area, explicit behavior).
- No speculative abstractions are introduced.
- The feature solves a real, demonstrated use case.
- Tests are deterministic and behavior-focused.
- PHPStan level 10 passes.
- Coding style passes php-cs-fixer.
- Commit messages follow Conventional Commits.

### Non-Goals

[](#non-goals)

The following will not be accepted:

- Async logging
- Channel systems
- Configuration loaders
- Container integrations
- Event dispatchers
- Buffering layers
- Implicit processors
- Log rotation
- Speculative extension points

If you need these features, consider composing this package or using `monolog/monolog`.

### Development Setup

[](#development-setup)

```
composer install
composer analyze
composer test
composer check-style
```

###  Health Score

35

—

LowBetter than 77% of packages

Maintenance76

Regular maintenance activity

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity49

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

132d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/24e3df1e6f1f1304c7ba83fbdbb309ee383ca3759d1d19856102e16e0d1177e3?d=identicon)[dusanrajcevic](/maintainers/dusanrajcevic)

---

Top Contributors

[![dusanrajcevic](https://avatars.githubusercontent.com/u/8985071?v=4)](https://github.com/dusanrajcevic "dusanrajcevic (40 commits)")

---

Tags

psrpsr-3phplogginglogger

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/vista-php-logger/health.svg)

```
[![Health](https://phpackages.com/badges/vista-php-logger/health.svg)](https://phpackages.com/packages/vista-php-logger)
```

###  Alternatives

[apix/log

Minimalist, thin and fast PSR-3 compliant (multi-bucket) logger.

521.1M20](/packages/apix-log)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)