README

CandyPalette

PHP port of charmbracelet/colorprofile — magical terminal color profile detection and color degradation.

Features

• Detect terminal color profile from environment variables and TTY info
• Profile enum: TrueColor (24-bit) → ANSI256 (255-color) → ANSI (16-color) → Ascii (no color) → NoTTY
• Color conversion: downsample RGBA colors to any target profile
• ProfileWriter: wrap a stream and automatically degrade color codes to match the terminal
• ANSI stripping: NoTTY strips all ANSI sequences from output
• Environment-aware: reads TERM, COLORTERM, FORCE_COLOR, NO_COLOR, TERM_PROGRAM

Install

composer require sugarcraft/candy-palette

Quick Start

use SugarCraft\Palette\Palette;
use SugarCraft\Palette\Profile;
use SugarCraft\Palette\Color;

// Detect the terminal's color profile
$profile = Palette::detect();

echo "Your terminal supports: " . $profile->name . "\n";

// Convert a TrueColor color to the detected profile
$color = new Color(0x6b, 0x50, 0xff, 0xff); // #6b50ff
$converted = Palette::convert($color, $profile);
echo "Converted: " . $converted->toAnsi() . "\n";

// Wrap stdout for automatic color degradation
$writer = ProfileWriter::wrap(STDOUT, [
    'TERM' => getenv('TERM'),
    'COLORTERM' => getenv('COLORTERM'),
]);
fwrite($writer, "\x1b[38;2;107;80;255mFancy text\x1b[0m\n");

Profiles

Color Degradation

use SugarCraft\Palette\Palette;
use SugarCraft\Palette\Profile;
use SugarCraft\Palette\Color;

$color = new Color(100, 50, 255, 255);

// Auto-detect
$converted = Palette::convert($color, Palette::detect());

// Manual downgrade
$ansi256 = Palette::convert($color, Profile::ANSI256);
$ansi    = Palette::convert($color, Profile::ANSI);

License

MIT