Download the PHP package migears/log without Composer

migears/log

Minimalist PSR-3 compliant logger for PHP. One class, zero magic.

A single Logger class that implements the full PSR-3 interface. No handler chains, no formatters, no configuration files. Just a callable handler, level threshold, and channel support — small enough to read in minutes.

Background: miGears is the open-source successor of TinyGears, a self-developed PHP framework. It was renamed and open-sourced recently because the name TinyGears is already taken in the open-source community.

Features

• Full PSR-3 compliance — all 8 log levels + log() method
• Context interpolation — {placeholder} syntax per PSR-3 spec
• Level threshold — discard messages below a minimum level
• Channel support — tag log lines with a channel name
• Three built-in handlers — file, stream, null
• Custom handlers — pass any callable
• Single class — read and understand the whole thing in minutes
• Only dependency: psr/log — the standard interface

Boundaries

In scope

• The full PSR-3 surface — all 8 levels plus log(), from Psr\Log\AbstractLogger, with {placeholder} context interpolation (scalars and Stringable; null → "null", booleans → true/false).
• One level threshold and one optional channel name, configured at construction.
• Three built-in handlers: Logger::toFile(), Logger::toStream() (any open stream, e.g. STDERR) and Logger::null().
• Custom destinations via a single callable(string $line): void passed as the handler.

Not in scope (by design)

• Handler chains, middleware, formatters and processors — the handler is one callable; a deeper pipeline is deliberately out of scope.
• Log rotation and retention — use logrotate or a similar external tool.
• Structured / JSON output, and async / buffered delivery — format or buffer inside your own handler.
• Configuration files and DI container integration — a PSR-3 LoggerInterface is wired in by the container owner (e.g. migears-manager resolves one through its Registry); this library ships no config and no container.

Installation

Requires: PHP 8.1+.

Quick Start

Stream Logger (stderr)

Null Logger (testing / production disable)

Custom Handler

Log Levels

Context Interpolation

Per PSR-3 spec, {placeholder} in the message is replaced with the corresponding context value:

Scalar values and Stringable objects are interpolated. null becomes "null" and booleans are spelled out as true/false. Non-scalar values (arrays, objects) are left as-is (placeholder stays).

Output Format

Example:

API Reference

Design Philosophy

miGears Log follows the miGears philosophy: minimal, readable, and useful.

• One class — no handler chains, no formatters, no processors
• Callable handler — flexibility without interface bloat
• PSR-3 compliant — drop-in replacement for any PSR-3 logger
• Small enough to read — read and understand it in minutes

What we don't do:

• No handler stacks / middleware chains
• No log rotation (use logrotate or similar tools)
• No structured / JSON logging out of the box (format it in your handler)
• No built-in async / buffered logging (implement in your handler)
• No configuration files or DI container integration

Integration with miGears Web

License

MIT

migears/log

极简 PSR-3 兼容 PHP 日志器。一个类，零魔法。

单个 Logger 类实现完整的 PSR-3 接口。没有处理器链，没有格式化器，没有配置文件。只有一个可调用的 handler、级别阈值和 channel 支持——小到几分钟就能读完。

特性

• 完全 PSR-3 兼容 — 全部 8 个日志级别 + log() 方法
• 上下文插值 — 按 PSR-3 规范的 {placeholder} 语法
• 级别阈值 — 丢弃低于最小级别的消息
• Channel 支持 — 给日志行打上 channel 名称标签
• 三种内置 handler — 文件、流、空操作
• 自定义 handler — 传入任意可调用函数
• 单类 — 几分钟就能读完理解
• 唯一依赖：psr/log — 标准接口

边界

范围内

• 完整的 PSR-3 日志接口 —— 全部 8 个级别加 log()，继承自 Psr\Log\AbstractLogger，支持 {placeholder} 上下文插值（标量与 Stringable；null → "null"，布尔值 → true/false）。
• 一个级别阈值和一个可选的 channel 名称，在构造时配置。
• 三种内置 handler：Logger::toFile()、Logger::toStream()（任意已打开的流，例如 STDERR）与 Logger::null()。
• 通过以 handler 形式传入的单个 callable(string $line): void 自定义输出目的地。

范围外（刻意不做）

• Handler 链、中间件、格式化器与处理器 —— handler 就是一个可调用函数，更深的管道刻意不做。
• 日志轮转与保留 —— 请使用 logrotate 或类似外部工具。
• 结构化 / JSON 输出，以及异步 / 缓冲投递 —— 在你自己的 handler 里格式化或缓冲。
• 配置文件与 DI 容器集成 —— PSR-3 的 LoggerInterface 由容器持有方装配（例如 migears-manager 通过其 Registry 解析 LoggerInterface）；本库不提供配置，也不提供容器。

安装

要求：PHP 8.1+。

快速开始

流日志（stderr）

空日志器（测试 / 生产环境禁用）

自定义 Handler

日志级别

上下文插值

按 PSR-3 规范，消息中的 {placeholder} 会被对应的上下文值替换：

标量值和 Stringable 对象会被插值。null 变为 "null"，布尔值明确输出为 true/false。非标量值（数组、对象）保持原样（占位符保留）。

输出格式

示例：

API 参考

设计哲学

miGears Log 遵循 miGears 设计哲学：极简、可读、实用。

• 一个类 — 没有 handler 链、没有格式化器、没有处理器
• 可调用 handler — 灵活但不臃肿
• PSR-3 兼容 — 可直接替换任何 PSR-3 日志器
• 小到可以读完 — 几分钟就能读完理解

我们不做的事：

• 没有 handler 栈 / 中间件链
• 没有日志轮转（使用 logrotate 或类似工具）
• 没有内置结构化 / JSON 日志（在 handler 中自己格式化）
• 没有内置异步 / 缓冲日志（在 handler 中实现）
• 没有配置文件或 DI 容器集成

与 miGears Web 集成

许可证

MIT