sugarcraft/candy-log

PHP port of charmbracelet/log — minimal, colorful leveled logging with structured human-readable output, text/JSON/logfmt formatters, and stdlog adapter.

v0.2.0 2026-05-07 01:29 UTC

Requires

• php: ^8.1
• sugarcraft/candy-core: @dev
• sugarcraft/candy-sprinkles: @dev

Requires (Dev)

• phpunit/phpunit: ^10.5

MIT

• Joe Huss

• log
• logging
• cli
• console
• structured
• colorful
• sugarcraft

README

CandyLog

PHP port of charmbracelet/log — a minimal, colorful leveled logging library.

Features

• Leveled logging — Debug, Info, Warn, Error, Fatal levels
• Colorful human-readable output — terminal-styled by default (TTY detection)
• Multiple formatters — TextFormatter (default), JSONFormatter, LogfmtFormatter
• Structured key/value pairs — pass arbitrary context with every log call
• Sub-loggers — With(...) creates a child logger with persistent fields
• Customizable — prefix, timestamp format, report caller, styles
• stdlog adapter — wrap in Log\StandardLogAdapter for *log.Logger interface compatibility

Install

composer require sugarcraft/candy-log

Quick Start

use SugarCraft\Log\Logger;
use SugarCraft\Log\Level;

$log = Logger::new();
$log->info('Starting oven', ['degree' => 375]);
$log->warn('Almost ready', ['batch' => 2]);
$log->error('Temperature too low', ['err' => 'underheated']);

Levels

Logger::debug('debug message');
Logger::info('info message');
Logger::warn('warn message');
Logger::error('error message');
Logger::fatal('fatal message'); // calls exit(1)
Logger::print('always prints');

Structured Fields

$log->info('Baking cookies', [
    'flour' => '2 cups',
    'butter' => true,
    'temp' => 375,
]);

// Child logger with persistent fields
$baker = $log->with(['user' => 'chef', 'session' => 'am']);
$baker->info('Batch started'); // also has user + session

Formatters

use SugarCraft\Log\Formatter\TextFormatter;
use SugarCraft\Log\Formatter\JsonFormatter;
use SugarCraft\Log\Formatter\LogfmtFormatter;

$log = Logger::new(formatter: new JsonFormatter());

Styling

Styles are applied automatically in TTY environments. Override via Logger::styles():

use SugarCraft\Sprinkles\Style;
$log = Logger::new();
$styles = $log->styles();
$styles->levels[Level::Error] = Style::new()->foreground('red')->bold();
$log->setStyles($styles);

Panic Handlers

use SugarCraft\Log\Log;

// Install a panic handler that catches uncaught exceptions and fatal errors,
// restores the terminal from altscreen mode, and prints a styled panic report.
Log::installPanicHandler();

// Restore terminal state manually (exit altscreen, show cursor).
// Called automatically by the panic handler, but safe to call directly.
Log::restoreTerminal();

The panic handler catches uncaught exceptions and fatal errors (E_ERROR, E_PARSE), restores the terminal to a usable state, and prints a colorized banner with the exception class, message, and backtrace.

License

MIT