README

colors is a color manipulation and conversion tool for PHP8.4+. The main purpose of this package was to dynamically define and manipulate colors for an avatar package. Originally it was part of that package, but due to increasing complexity and size, it has been removed from that one and transferred to a standalone package.

Not only Hex- and RGB-Colors are supported, also HSL-, HSV-, RAL- and named (CSS/X11) colors are implemented in the package and they can be converted from one to the other. Hex, RGB, HSL and HSV additionally carry an optional alpha (opacity) channel that is preserved across conversions. For HSL-colors it's even possible to manipulate the color. For example, you can lighten or darken it. A Color facade can also auto-detect the format of an arbitrary color string and return the matching object.

Install

composer require renfordt/colors

Requirements

• PHP >= 8.4
• renfordt/clamp (will be obsolete with PHP8.6)

Quick start

Creating Colors

use Renfordt\Colors\{HexColor, RGBColor, HSLColor, HSVColor, RALColor, NamedColor};

// Hex colors - with or without # prefix (3/4/6/8 digits, alpha optional)
$hex = HexColor::create('#FF5733');
$hex = HexColor::create('FF5733');

// RGB colors - values from 0-255
$rgb = RGBColor::create([255, 87, 51]);

// HSL colors - hue: 0-360, saturation/lightness: 0.0-1.0
$hsl = HSLColor::create([9, 1.0, 0.6]);

// HSV colors - hue: 0-360, saturation/value: 0.0-1.0
$hsv = HSVColor::create([9, 0.8, 1.0]);

// RAL colors - standard RAL codes
$ral = RALColor::create(3020);

// Named colors - standard CSS/X11 names (case-insensitive)
$named = NamedColor::create('RebeccaPurple');

Parsing Unknown Formats

When you don't know the format of a string ahead of time (user input, config, database), let the Color facade detect it. Color::parse() inspects the string and returns the matching color object, ready to convert:

use Renfordt\Colors\Color;

Color::parse('#FF3377AA');           // HexColor (with alpha)
Color::parse('rgb(255, 51, 119)');   // RGBColor
Color::parse('rgba(255 51 119 / .5)');// RGBColor - modern CSS syntax, with alpha
Color::parse('hsl(340, 100%, 60%)'); // HSLColor
Color::parse('hsv(340, 80%, 100%)'); // HSVColor
Color::parse('RebeccaPurple');       // NamedColor
Color::parse('RAL 3020');            // RALColor

// Convert straight away
$rgb = Color::parse('hsl(340, 100%, 60%)')->toRGB();

// Color::make() is an alias of parse()
$hex = Color::make('RebeccaPurple')->toHex();  // #663399

Functional notation accepts both legacy commas and modern space/slash syntax, percentages, a deg suffix on the hue, and an optional alpha. An unrecognisable string (or an unknown RAL code) throws InvalidArgumentException.

Direct Property Access

The new property hooks API makes working with colors intuitive and clean:

// RGB - direct component access
$color = RGBColor::create([255, 100, 50]);
echo $color->red;    // 255
echo $color->green;  // 100
echo $color->blue;   // 50
echo $color->alpha;  // 255 (opaque by default)

// Modify individual components (automatically clamped)
$color->red = 200;
$color->green = 300;  // Automatically clamped to 255
$color->blue = -10;   // Automatically clamped to 0
$color->alpha = 128;  // 50% opaque (0-255)

// HSL - access hue, saturation, lightness
$hsl = HSLColor::create([180, 0.5, 0.7]);
echo $hsl->hue;        // 180
echo $hsl->saturation; // 0.5
echo $hsl->lightness;  // 0.7

$hsl->lightness = 0.9;  // Adjust lightness

// HSV - access hue, saturation, value
$hsv = HSVColor::create([240, 0.8, 0.6]);
echo $hsv->hue;        // 240
echo $hsv->saturation; // 0.8
echo $hsv->value;      // 0.6

// Hex - get hex value with #
$hex = HexColor::create('FF5733');
echo $hex->hex;  // #FF5733

// RAL - access RAL code
$ral = RALColor::create(3020);
echo $ral->ral;  // 3020

Converting Between Formats

All color formats can be converted to any other format:

$hex = HexColor::create('#FF5733');

// Convert to any format
$rgb = $hex->toRGB();
$hsl = $hex->toHSL();
$hsv = $hex->toHSV();

// Chain conversions
$finalColor = HexColor::create('#FF5733')
    ->toRGB()
    ->toHSL()
    ->toHex();

// Precision control for HSL/HSV
$hsl = $rgb->toHSL(precision: 2);  // Round to 2 decimal places

Docs

Detailed documentation are in preparation.