Introduction
renfordt/colors is a PHP library for converting and manipulating colors across
six formats: Hex, RGB, HSL, HSV, RAL, and standard (CSS/X11) color names. Each
format is represented by its own class, and any color can be converted into any
other format.
Scope
The library covers:
- Parsing and constructing colors in each supported format.
- Auto-detecting the format of an arbitrary color string (
Color::parse()). - Converting between formats. Most conversions route through RGB internally.
- Carrying an optional alpha (opacity) channel through Hex, RGB, HSL, and HSV.
- Manipulating lightness on HSL colors (
brighten/darken). - Resolving and looking up standard color names (e.g.
rebeccapurple). - Matching an arbitrary color to the nearest entry in the RAL color table or to the nearest standard color name.
Component values are clamped to their valid ranges on assignment rather than raising errors, except for hex strings, which are validated and reject invalid input.
Requirements
- PHP 8.4 or higher
- Composer
renfordt/clamp(installed automatically as a dependency)
PHP 8.4 is required because the color classes expose their components through property hooks, a language feature introduced in that version.
Supported formats
| Format | Class | Components | Alpha |
|---|---|---|---|
| Hex | HexColor | 3-, 4-, 6-, or 8-digit hexadecimal string | yes |
| RGB | RGBColor | red, green, blue (0–255), alpha (0–255) | yes |
| HSL | HSLColor | hue (0–360), saturation, lightness, alpha | yes |
| HSV | HSVColor | hue (0–360), saturation, value, alpha | yes |
| RAL | RALColor | RAL classic code (lookup table) | — |
| Named | NamedColor | standard CSS/X11 color name | — |
All classes live in the Renfordt\Colors namespace. The shared hue-to-RGB
conversion logic used by HSLColor and HSVColor is in the
Renfordt\Colors\Traits\HueBasedTrait trait.
When the format of a value is not known ahead of time, the Color facade
inspects a string, detects its format, and returns the matching class above. See
Parsing unknown color strings.
The alpha channel is optional everywhere it is supported and defaults to fully opaque. See Concepts for how it is represented and preserved across conversions.