CandyLog
Colorful leveled logger
Minimal, colorful leveled logging. Debug / Info / Warn / Error / Fatal with structured key/value context, Text / JSON / Logfmt formatters, and sub-loggers with persistent fields.
Install
composer require sugarcraft/candy-logQuickstart
use SugarCraft\Log\Logger;
$log = Logger::new();
$log->info('Starting oven', ['degree' => 375]);
$log->warn('Almost ready', ['batch' => 2]);
$log->error('Temperature too low', ['err' => 'underheated']);
$child = $log->with('service', 'bakery');
$child->info('Batch complete');What's in the box
Leveled loggingDebug, Info, Warn, Error, Fatal. TTY detection enables color automatically.
Three formattersTextFormatter (default), JSONFormatter, LogfmtFormatter — swap via `withFormatter()`.
Structured contextArbitrary key/value pairs attached to every log call.
Sub-loggers`with(...)` creates a child logger that inherits all context.
StandardLogAdapterWrap any PSR-3 logger for `*log.Logger` compatibility.
PSR-3 bridge`PsrBridge` wraps a Logger and exposes the full PSR-3 LoggerInterface API.
Hook systemRegister per-level callbacks via `HookRegistry::onLevel()` for middleware-style interceptors.
Caller info`reportCaller` on Logger adds `file:line` of the true call site to every entry.
PartsOrder DTOConfigure which log-parts appear and in what order — default, syslog, or custom.
Source & demos
- Source on GitHub
- Full README
- Runnable examples
- Port of charmbracelet/log (Go upstream)
API
| Class | Method | Description |
|---|---|---|
| Logger | new() | Create a new logger |
| Logger | debug(msg, context) | Log debug message |
| Logger | info(msg, context) | Log info message |
| Logger | warn(msg, context) | Log warning message |
| Logger | error(msg, context) | Log error message |
| Logger | fatal(msg, context) | Log fatal message |
| Logger | with(array) | Create child logger with persistent context |
| Logger | withFormatter(Formatter) | Set output formatter |
| Logger | withMinLevel(Level) | Set minimum output level |
| Logger | withPrefix(string) | Set per-line prefix |
| Logger | setReportCaller(bool) | Enable/disable caller file:line reporting |
| Logger | setReportTimestamp(bool) | Enable/disable timestamp |
| Logger | styles() | Get Styles object for level/field styling |
| Logger | styles()->keys[name] | Per-field ANSI style override (time, level, caller, message, key, value) |
| PsrBridge | new(Logger, ?HookRegistry) | Wrap a Logger with full PSR-3 API |
| PsrBridge | emergency(msg, ctx) | PSR-3 emergency — maps to Level::Fatal |
| PsrBridge | alert(msg, ctx) | PSR-3 alert — maps to Level::Fatal |
| PsrBridge | critical(msg, ctx) | PSR-3 critical — maps to Level::Fatal |
| PsrBridge | error(msg, ctx) | PSR-3 error — maps to Level::Error |
| PsrBridge | warning(msg, ctx) | PSR-3 warning — maps to Level::Warn |
| PsrBridge | notice(msg, ctx) | PSR-3 notice — maps to Level::Info |
| PsrBridge | info(msg, ctx) | PSR-3 info — maps to Level::Info |
| PsrBridge | debug(msg, ctx) | PSR-3 debug — maps to Level::Debug |
| PsrBridge | log(level, msg, ctx) | Generic PSR-3 log dispatch |
| HookRegistry | onLevel(Level, callable): int | Register a callback for all events at/above Level |
| HookRegistry | fire(Level, psrLevel, msg, ctx) | Dispatch to all matching handlers |
| Hook | onLevel(Level, string, string, array) | Interface for structured hook implementations |
| PartsOrder | new(?list) | Config DTO for log-part ordering |
| PartsOrder | default(): self | Preset: timestamp, level, prefix, caller, message, fields |
| PartsOrder | syslog(): self | Preset: timestamp, level, message, fields (no prefix/caller) |
| PartsOrder | messageFirst(): self | Preset: message, level, timestamp, fields |
| PartsOrder | has(PART_*): bool | Check whether a part is included in the order |
| PartsOrder | PART_TIMESTAMP, PART_LEVEL, PART_PREFIX, PART_CALLER, PART_MESSAGE, PART_FIELDS | Part name constants |
| CallerFormatter | find(): ?string | Walk call stack, return "file:line" of first external caller |
| Level | Debug, Info, Warn, Error, Fatal | Enum: syslog-aligned int values (-4, 0, 4, 8, 12) |
| TextFormatter | new(bool, ?string, bool, bool) | Human-readable formatter with ANSI color |
| JsonFormatter | new(bool) | JSON object per log line |
| LogfmtFormatter | new() | Logfmt key=value format |
| Log | installPanicHandler() | Install global panic handler (catches fatal errors + uncaught exceptions) |
| Log | restoreTerminal() | Restore terminal from altscreen mode |
| Log | setLogger(Logger) | Set the global logger instance |
| Log | info(msg, ctx) | Static shorthand — delegates to global logger |
| Log | debug/warn/error/fatal(msg, ctx) | Static shorthands for each level |
