Download the PHP package tecnickcom/tc-lib-color without Composer

tc-lib-color

PHP library to manipulate various color representations.

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

Overview

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

Features

Color Models

• 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

Integration Helpers

• 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

Requirements

• PHP 8.2 or later
• Composer

Installation

Quick Start

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

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

Supported color notations

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:

Nearest named color

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 and spot colors

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.

Exceptions

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.

Roles and extension points

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.

Versioning

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.

Development

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

Packaging

For system packages, bootstrap with:

Contributing

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