Skip to main content

Getting Started

Every color class exposes two static factory methods, create() and make(). They are equivalent; make() is an alias for create().

Creating colors​

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

// Hex - accepts 3-, 4-, 6-, or 8-digit strings, with or without a leading #
$hex = HexColor::create('#FF5733');
$hex = HexColor::create('F53');

// RGB - integers 0-255 as [red, green, blue]
$rgb = RGBColor::create([255, 87, 51]);

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

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

// RAL - a RAL classic code, as int or string
$ral = RALColor::create(3020);

// Named - a standard CSS/X11 color name (case-insensitive)
$named = NamedColor::create('RebeccaPurple');

Parsing an unknown format​

When you do not know the format of a string ahead of time, let the Color facade detect it. Color::parse() returns whichever class matches the input.

use Renfordt\Colors\Color;

Color::parse('#FF3377AA');          // HexColor
Color::parse('rgb(255, 51, 119)');  // RGBColor
Color::parse('hsl(340, 100%, 60%)');// HSLColor
Color::parse('RebeccaPurple');      // NamedColor
Color::parse('RAL 3020');           // RALColor

See Parsing unknown color strings for the full set of accepted inputs.

Adding an alpha channel​

Hex, RGB, HSL, and HSV accept an optional alpha (opacity) component. It defaults to fully opaque, so it can always be omitted. Each format uses its own native representation:

// Hex - a 4th/8th digit pair (#RRGGBBAA or #RGBA)
$hex = HexColor::create('#FF5733CC');

// RGB - a 4th element, 0-255 (255 = opaque)
$rgb = RGBColor::create([255, 87, 51, 204]);

// HSL / HSV - a 4th element, 0.0-1.0 (1.0 = opaque)
$hsl = HSLColor::create([9, 1.0, 0.6, 0.8]);
$hsv = HSVColor::create([9, 0.8, 1.0, 0.8]);

See Concepts → Alpha channel for details on how alpha is preserved across conversions.

Reading components​

Components are exposed as public properties through property hooks:

$rgb = RGBColor::create([255, 100, 50]);
echo $rgb->red;    // 255
echo $rgb->green;  // 100
echo $rgb->blue;   // 50

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

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

Each class also offers an array getter for destructuring, plus an alpha-aware variant that appends the opacity component:

[$r, $g, $b] = RGBColor::create([255, 100, 50])->getRGB();
[$h, $s, $l] = HSLColor::create([180, 0.5, 0.7])->getHSL();
[$h, $s, $v] = HSVColor::create([240, 0.8, 0.6])->getHSV();

[$r, $g, $b, $a] = RGBColor::create([255, 100, 50, 128])->getRGBA();
[$h, $s, $l, $a] = HSLColor::create([180, 0.5, 0.7, 0.5])->getHSLA();
[$h, $s, $v, $a] = HSVColor::create([240, 0.8, 0.6, 0.5])->getHSVA();

Resolving named colors​

A NamedColor resolves to any other format, and you can look a color up by its standard name:

$named = NamedColor::create('tomato');
$hex   = $named->toHex();   // #ff6347
$rgb   = $named->toRGB();   // RGBColor

// Reverse lookup: the exact name for a color, or null when there is none
RGBColor::create([255, 99, 71])->getName();   // "tomato"
HexColor::create('#ff6347')->getName();        // "tomato"

Converting​

Any color can be converted to any other format. See Converting between formats for the full matrix.

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

$rgb = $hex->toRGB();
$hsl = $hex->toHSL();
$hsv = $hex->toHSV();

Conversion methods return new instances, so calls can be chained:

$result = HexColor::create('#FF5733')
    ->toRGB()
    ->toHSL()
    ->toHex();