README

Overview
Install
Quickstart

Overview

Pop Color is a helpful component to manage different types of color values and conversions. Supported color formats include:

RGB
HEX
HSL
HSV
HSB
HWB
CMYK
Grayscale
LAB
LCH
OKLAB
OKLCH

Within the Pop PHP Framework, the pop-css, pop-image and pop-pdf components use this component.

Top

Install

Install pop-color using Composer.

composer require popphp/pop-color

Or, require it in your composer.json file

"require": {
    "popphp/pop-color" : "^2.0.0"
}

Top

Quickstart

Create a color object

$rgb = Color::rgb(120, 60, 30, 0.5);
echo $rgb . PHP_EOL;

The above command will print the default CSS format:

rgba(120, 60, 30, 0.5)

Convert to another color format

$hex = $rgb->toHex();
echo $hex . PHP_EOL;

#783c1e80

$hsl = $hex->toHsl();
echo $hsl . PHP_EOL;

hsla(20, 75%, 47%, 0.502)

// Will print a string of space-separated values, common to the PDF color string format
$cmyk = $rgb->toCmyk();
echo $cmyk . PHP_EOL;

0 0.5 0.75 0.53

Not every color's default string format is CSS — Cmyk and Grayscale default to the PDF-style format above, and Hsv/Hsb (below) default to a delegated rgb(...)/rgba(...) string rather than anything HSV-shaped. Call toCss() when you need guaranteed CSS output regardless of which color class you're holding:

echo $cmyk->toCss() . PHP_EOL;

rgb(120, 60, 30)

Hex colors with alpha

Hex accepts (and round-trips) the 4-digit #RGBA and 8-digit #RRGGBBAA CSS hex-with-alpha formats, alongside the standard 3- and 6-digit forms. Alpha is exposed as the same 0-1 float used by Rgb/Hsl:

$hex = Color::hex('#ff880080');
echo $hex . PHP_EOL;
echo $hex->getA() . PHP_EOL;

#ff880080
0.502

HSV, HSB, and HWB

Hsv and Hsb are the same color model (hue/saturation/value, or hue/saturation/brightness) exposed as two separate classes with the third channel named differently:

$hsv = Color::hsv(210, 50, 75);
echo $hsv . PHP_EOL;
echo $hsv->toRgb() . PHP_EOL;

rgb(96, 143, 191)
rgb(96, 143, 191)

Hwb is a native CSS Color 4 format, so — unlike Hsv/Hsb — its default string output is real hwb(...) syntax, with a /-alpha suffix when alpha is set:

$hwb = Color::hwb(210, 20, 10, 0.5);
echo $hwb . PHP_EOL;
echo $hwb->toRgb() . PHP_EOL;

hwb(210 20% 10% / 0.5)
rgba(51, 140, 230, 0.5)

Lab, Lch, Oklab, and Oklch

Lab, Lch, Oklab, and Oklch are native CSS Color 4 formats (like Hwb), so their default string output is real lab(...)/lch(...)/oklab(...)/oklch(...) syntax. Unlike every other class in this library, alpha on these four is getAlpha()/setAlpha()/hasAlpha(), not getA()/setA() — Lab and Oklab already use a for their own axis channel, so alpha needed a different name to avoid colliding with it:

$lab = Color::lab(53.24, 80.09, 67.2, 0.5);
echo $lab . PHP_EOL;
echo $lab->getAlpha() . PHP_EOL;
echo $lab->hasAlpha() ? 'true' : 'false';
echo PHP_EOL;

lab(53.24% 80.09 67.2 / 0.5)
0.5
true

Lch and Oklab construct and convert the same way:

$lch = Color::lch(53.24, 104.55, 40);
echo $lch . PHP_EOL;
echo $lch->toRgb() . PHP_EOL;

$oklab = Color::oklab(0.628, 0.2249, 0.1258);
echo $oklab . PHP_EOL;
echo $oklab->toRgb() . PHP_EOL;

lch(53.24% 104.55 40)
rgb(255, 0, 0)
oklab(0.628 0.2249 0.1258)
rgb(255, 0, 0)

Color::parse() also recognizes lab(...), lch(...), oklab(...), and oklch(...) strings:

$oklch = Color::parse('oklch(0.628 0.2577 29)');
echo $oklch->getL() . PHP_EOL;
echo $oklch->getC() . PHP_EOL;
echo $oklch->getH() . PHP_EOL;
echo $oklch . PHP_EOL;

0.628
0.2577
29
oklch(0.628 0.2577 29)

Accessing Color Properties

$rgb = Color::rgb(120, 60, 30, 0.5);
echo $rgb->getR() . PHP_EOL;
echo $rgb->getG() . PHP_EOL;
echo $rgb->getB() . PHP_EOL;
echo $rgb->getA() . PHP_EOL;

Every channel is also readable (and settable) via ArrayAccess or magic property access, as an alternative to the getter/setter methods:

echo $rgb['r'] . PHP_EOL;
echo $rgb->r . PHP_EOL;

120
120

toArray() returns every channel (including alpha, when set) as a plain array:

print_r($rgb->toArray());

Array
(
    [r] => 120
    [g] => 60
    [b] => 30
    [a] => 0.5
)

$cmyk = Color::cmyk(60, 30, 20, 50);
echo $cmyk->getC() . PHP_EOL;
echo $cmyk->getM() . PHP_EOL;
echo $cmyk->getY() . PHP_EOL;
echo $cmyk->getK() . PHP_EOL;

$gray = Color::grayscale(50);
echo $gray->getGray() . PHP_EOL;
echo $gray . PHP_EOL;

50
0.5

Parse Color Strings

$rgb = Color::parse('rgba(120, 60, 30, 0.5)');
echo $rgb->getR() . PHP_EOL;
echo $rgb->getG() . PHP_EOL;
echo $rgb->getB() . PHP_EOL;
echo $rgb->getA() . PHP_EOL;
echo $rgb . PHP_EOL;

120
60
30
0.5
rgba(120, 60, 30, 0.5)

Color::parse() also recognizes hsv(...), hsb(...), and hwb(...) strings. hwb(...) accepts both the legacy comma-separated form and native CSS Color 4 space-separated syntax with a /-alpha suffix:

$hwb = Color::parse('hwb(210 20% 10% / 0.5)');
echo $hwb->getH() . PHP_EOL;
echo $hwb->getW() . PHP_EOL;
echo $hwb->getB() . PHP_EOL;
echo $hwb->getA() . PHP_EOL;

Color::parse() also sniffs #hex strings, space-separated CMYK strings, and bare numeric grayscale strings — it dispatches on the shape of the string rather than requiring a format hint:

$hex = Color::parse('#783c1e');
echo $hex . PHP_EOL;

$cmyk = Color::parse('0 0.5 0.75 0.53');
echo $cmyk . PHP_EOL;

$gray = Color::parse('50');
echo $gray . PHP_EOL;

#783c1e
0 0.5 0.75 0.53
0.5

Error Handling

Color::parse() throws Pop\Color\Color\Exception for any string it doesn't recognize, and every setter throws OutOfRangeException for a value outside its valid range:

try {
    Color::parse('not-a-color');
} catch (Color\Exception $e) {
    echo $e->getMessage() . PHP_EOL;
}

try {
    Color::rgb(300, 0, 0);
} catch (\OutOfRangeException $e) {
    echo $e->getMessage() . PHP_EOL;
}

Error: The string was not in the correct color format.
Error: The value of $r must be between 0 and 255.

Top

popphp / pop-color

Maintainers

Package info

Statistics

Security