tc-lib-color

PHP library to manipulate various color representations.

💖 Part of the tc-lib-pdf / TCPDF ecosystem (100M+ installs). Sponsor its maintenance →

tc-lib-color parses, converts and formats the color values used in web and PDF output.

• Grayscale (GRAY)
• RGB/RGBA, including hexadecimal notations (RGB)
• HSL/HSLA (HSL)
• CMYK/CMYKA (CMYK)
• CIE Lab (LAB)
• Spot colors (Separation), with DeviceCMYK and Lab alternate color spaces for PDF output

• CSS output that parses back to the same color
• PDF and Acrobat JavaScript color output
• Cross-model conversion on all color models
• Named web color lookup (CSS Color Module Level 4 names)
• ColorModelType enum and Model::create() factory

• PHP 8.2 or later
• Composer

composer require tecnickcom/tc-lib-color

<?php

require_once __DIR__ . '/vendor/autoload.php';

$web = new \Com\Tecnick\Color\Web();
$rgb = $web->getRgbObjFromHex('#336699');

echo $rgb->getCssColor();      // rgb(51,102,153)
echo $rgb->getRgbHexColor();   // #336699
echo $rgb->getPdfColor();      // "0.200000 0.400000 0.600000 rg\n"

Any supported notation can be parsed through the same entry point:

$web->getColorObj('rgb(51 102 153)');
$web->getColorObj('hsl(210,50%,40%)');
$web->getColorObj('cmyk(67%,33%,0%,40%)');
$web->getColorObj('lab(41% -2 -25)');
$web->getColorObj('steelblue');

getCssColor() emits a value that getColorObj() parses back to the same color.

Components are separated either by commas or by spaces, not by a mixture of the two, and the alpha channel by a comma in the first form or by a slash in the second. A hue accepts the CSS angle units (deg, grad, rad, turn). Out-of-range values are clamped and a hue wraps, as CSS Color Level 4 requires, so rgb(-10,0,0) is black and hsl(-150,50%,50%) is the same as hsl(210,50%,50%). Anything else is rejected with a Com\Tecnick\Color\Exception.

g(), cmyk() and cmyka() are notations of this library, not CSS functions, and round-trip through getCssColor() and getColorObj() like the others.

Models can also be built directly by type:

use Com\Tecnick\Color\ColorModelType;
use Com\Tecnick\Color\Model;

$cmyk = Model::create(ColorModelType::Cmyk, [
    'cyan' => 0.67,
    'magenta' => 0.33,
    'yellow' => 0.0,
    'key' => 0.4,
    'alpha' => 1.0,
]);

$web = new \Com\Tecnick\Color\Web();

$web->getClosestWebColorFromString('#9577a6');          // 'lightslategray'
$web->getClosestWebColorByDeltaEFromString('#9577a6');  // 'plum'

getClosestWebColor() measures the Euclidean distance in sRGB, which is not perceptually uniform. getClosestWebColorByDeltaE() measures the CIE76 difference in CIE Lab, which tracks perceived difference.

$pdf = new \Com\Tecnick\Color\Pdf();

$pdf->getPdfFillColor('steelblue');       // "0.274510 0.509804 0.705882 rg\n"
$pdf->addSpotColorFromArray('My Spot', ['cyan' => 1]);
$pon = 0;
$objects = $pdf->getPdfSpotObjects($pon); // write these first
$resources = $pdf->getPdfSpotResources(); // then reference them

Eight of the eleven default spot color names are also CSS color names (red, green, blue, cyan, magenta, yellow, black, white) and resolve to the spot color. They agree with their CSS namesake except green: the spot Green is #00ff00 while CSS green is #008000. Pass $allowSpot = false to getPdfColor(), getPdfFillColor(), getPdfStrokeColor(), getColorObject(), getPdfRgbComponents() or getPdfCmykComponents() to force the device color.

The remaining three, key, all and none, are spot-only names. With $allowSpot = false they do not resolve: getPdfColor() and the component accessors return an empty string and getColorObject() returns null.

Every registered spot color must be emitted by getPdfSpotObjects() before getPdfSpotResources() is called; otherwise the resource writers raise a Com\Tecnick\Color\Exception.

Com\Tecnick\Color\Exception (a \Exception) signals an invalid input. Com\Tecnick\Color\UnknownComponentException (a \LogicException) signals a component name a model does not define, and is not swallowed by the lenient accessors tryGetColorObj() and getColorObject(). Both implement Com\Tecnick\Color\ExceptionInterface, so a single catch covers them.

See example/index.php for a web-color conversion table covering RGB, HSL, the Acrobat JavaScript form and the nearest-color inversion.

Pdf extends Spot extends Web extends Css, so one object offers the parser, the spot registry and the PDF writer. Each role also has its own interface to type against: ColorParserInterface, SpotRegistryInterface and PdfColorWriterInterface.

Four methods can be overridden: Web::getColorObj(), Spot::getSpotColor(), Pdf::getPdfColor() and Pdf::getColorObject(), plus the protected parser methods on Css and Spot::resolveSpotColorData(). Every other public method is final. A subclass that overrides one of the four must mirror its signature exactly.

This project follows Semantic Versioning. A change that alters a public signature, the bytes a method emits, or whether an input parses, goes in a major release. See CHANGELOG.md.

make deps
make help
make qa
make server

make server serves the example/ directory on http://localhost:8000. Use a custom port with make server PORT=8080.

make rpm
make deb

For system packages, bootstrap with:

require_once '/usr/share/php/Com/Tecnick/Color/autoload.php';

Contributions are welcome. Please review CONTRIBUTING.md, CODE_OF_CONDUCT.md, and SECURITY.md.