README

Color

A small, framework-agnostic PHP library for color conversion, luminance, contrast and deterministic string-to-color hashing. No runtime dependencies.

🚀 Features

• Immutable Color value object with Rgb and Hsl companions
• Lossless conversion between hex, RGB and HSL
• WCAG 2.x relative luminance and contrast ratio
• optimalTextColor() — pick readable text color for any background
• Deterministic string → color hashing (SHA-256/HSL or CRC32)

🔥 Installation

composer require konradmichalik/php-color

⚡ Usage

Conversion

use KonradMichalik\Color\Color;

$color = Color::fromHex('#3366cc');

$color->toRgb();          // Rgb(51, 102, 204)
$color->toHsl();          // Hsl(220.0, 60.0, 50.0)
$color->toHex();          // "#3366cc"

Color::fromRgb(51, 102, 204)->toHex();      // "#3366cc"
Color::fromHsl(220, 60, 50)->toHex();       // "#3366cc"
$color->withLightness(85)->toHex();         // a lighter variant

Short hex (#abc), missing # and surrounding whitespace are all accepted. Invalid values throw KonradMichalik\Color\Exception\InvalidColorValue.

Contrast & readable text

$background = Color::fromHex('#222222');

$background->relativeLuminance();                  // 0.0185…
$background->contrastRatio(Color::fromHex('#fff')); // 15.9…
$background->isDark();                              // true
$background->optimalTextColor()->toHex();          // "#ffffff"

optimalTextColor() returns whichever candidate (black/white by default, or two custom colors) has the higher contrast against the background.

Deterministic colors from strings

Great for avatar backgrounds or tag colors — the same input always yields the same color:

use KonradMichalik\Color\ColorHasher;

$hasher = ColorHasher::hsl();              // balanced SHA-256 → HSL (recommended)
$hasher->hash('konrad@example.com');       // stable Color

$hasher = ColorHasher::hsl(saturation: 70, lightness: 45);
$hasher = ColorHasher::crc32();            // lightweight CRC32 → hex

Need a custom mapping? Implement KonradMichalik\Color\Hashing\HashStrategy and pass it to new ColorHasher($strategy).

🧪 Quality

composer test           # PHPUnit
composer test:coverage  # PHPUnit with code coverage
composer lint           # CS, EditorConfig and composer.json
composer sca            # PHPStan (max)
composer migration      # Rector
composer fix            # apply automatic fixes

🧑‍💻 Contributing

Please have a look at CONTRIBUTING.md.

📄 License

This project is licensed under GPL-2.0-or-later.