sugarcraft/candy-palette

PHP port of charmbracelet/colorprofile — magical terminal color profile detection and color degradation (TrueColor → ANSI256 → ANSI → ASCII).

Maintainers

Package info

github.com/sugarcraft/candy-palette

pkg:composer/sugarcraft/candy-palette

Statistics

Installs: 0

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

Security

Advisories: 0

Aikido package health analysis

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

Requires

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

Requires (Dev)

MIT ed5d15aeb35b653e6aede7ad1207e922d379d37d

  • Joe Huss <detain.woop@interserver.net>

colorterminalansitruecolortuisugarcraftcolorprofile

This package is not auto-updated.

Last update: 2026-05-07 14:55:32 UTC

README

candy-palette

CI codecov Packagist Version License PHP

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

Profile Colors Description
TrueColor 16.7M Full 24-bit RGB (24-bit ANSI)
ANSI256 256 216 cube + 24 grey + 16 standard
ANSI 16 Standard terminal colors
Ascii 2 Black & white
NoTTY 0 No color (ANSI stripped)

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