Download the PHP package bugo/iris without Composer

Iris

По-русски

Color space conversions, serialization, and operations for legacy and modern CSS colors.

Named after Iris, the goddess of the rainbow in Greek mythology.

Installation

Color spaces

Iris supports the legacy CSS spaces and the modern color spaces used by lab(), lch(), oklab(), oklch(), and color(...).

XyzColor is reused for both xyz-d65 and xyz-d50; the white point depends on the method or route you call.

Channel scales and conventions

RgbColor channels are always normalized to 0-1, on every API surface. The same object can be passed to SpaceConverter, CssSerializer, LiteralSerializer, ColorMixResolver, and the manipulators without rescaling, and rgbToX() / xToRgb() pairs are exact inverses of each other.

Bytes appear only at the input and output boundary:

• LiteralParser accepts byte-based hex literals and named colors, and returns normalized RgbColor.
• LiteralSerializer and HexEncoder convert normalized channels back to hex bytes.
• NamedColors::NAMED_RGB stores byte-like channel values, since it mirrors the CSS named color table.

Other spaces keep the scale their CSS function uses: HslColor and HwbColor use percentage-like 0-100 channels, LabColor, LchColor, OklabColor and OklchColor store lightness on 0-100, and chroma or a/b axes stay on their native numeric ranges.

SpaceRouter routes by string space name on top of the channel API. It is best suited for CSS color(<space> ...) flows, where spaces such as srgb, display-p3, rec2020, and xyz-* are passed around as normalized channel triples. lab, lch, oklab, and oklch are also accepted for symmetry, but the typed SpaceConverter methods are usually clearer when you already know the target space at compile time.

Migrating from 0.3

RgbColor no longer accepts byte channels. Divide existing values by 255, or let LiteralParser do it:

Other breaking changes:

• CssSerializer::toCss() now emits a percentage lightness for oklab() and oklch(), matching what it already did for lab() and lch(). The previous bare-number form was not valid CSS.
• ColorMixResolver::mixHsl(), mixLab(), mixLch(), mixOklab() and mixOklch() gained a $premultiplied flag, mirroring mixSrgb(). Serializer enables it, so color-mix() results change for colors with alpha below 1.
• color-mix(in srgb-linear, ...) now interpolates in linear-light sRGB instead of gamma-encoded sRGB.
• Percentage channels in lch(), oklab() and oklch() are resolved against the CSS Color 4 reference ranges instead of being dropped.
• SpaceConverter::normalizedChannelsToOklch() is deprecated in favor of rgbToOklch(); both now behave identically.

When to use what

• SpaceConverter: typed color math and direct conversions between concrete spaces.
• SpaceRouter: dispatch from a string space name to RGBA or XYZ D65.
• Serializer: normalize CSS color strings and optionally convert supported functions to hex.
• CssSerializer: serialize typed color objects back to CSS functions.
• LiteralConverter and LiteralSerializer: convert hex and named colors to or from RgbColor.
• LegacyManipulator, PerceptualManipulator, SrgbManipulator: adjust, mix, and transform colors at different abstraction levels.

Usage

Creating color objects

Converting between color spaces

The *Channels* methods are the low-level channel API. Methods that accept color objects such as RgbColor or OklchColor remain object-oriented entry points; both operate on the same normalized sRGB channels, so rgbToOklch() and oklchToRgb() round-trip exactly.

Routing by space name

Color manipulations

Gamut mapping

GamutMapper maps out-of-sRGB-gamut colors back into gamut using two algorithms from CSS Color Level 4.

Both methods accept and return OklchColor. For other spaces, convert to OklchColor first.

CSS color-mix() interpolation

ColorMixResolver implements CSS Color Level 4 interpolation rules, including none channel handling and all four hue interpolation methods.

If one side uses null for a channel, the other side wins instead of interpolating. If both sides are null, the result stays null.

Every mix*() method takes an optional $premultiplied flag. Per CSS Color Level 4, interpolation should happen in premultiplied form when alpha differs between the two colors; the hue channel of cylindrical spaces is never premultiplied. Serializer enables the flag when resolving color-mix().

Hex encoding

Parsing CSS color literals

Serializer vs CssSerializer

Use Serializer when the input is already a CSS string and you want normalization or optional hex conversion.

Use CssSerializer when the input is a typed color object and you want a CSS function string.

If you specifically need hex from an RgbColor, call CssSerializer::toHex() or LiteralSerializer. Both read the same normalized channels; LiteralSerializer additionally prefers a CSS named color when one matches exactly.

Model conversion

Perceptual manipulations

Linear RGB manipulations

Wide-gamut color spaces

Polar math utilities

Named colors

NamedColors::NAMED_RGB stores byte-like channel values, mirroring the CSS named color table. Use LiteralParser::toRgb() to get a normalized RgbColor from a name.

ColorValueInterface

All Spaces/* classes implement Bugo\Iris\Contracts\ColorValueInterface.

Exceptions

All exceptions extend IrisException, which extends \RuntimeException.

• UnsupportedColorSpace: unknown space passed to SpaceRouter or other string-based conversion entry points.
• InvalidColorFormat: malformed CSS color literals, unsupported function syntax, or invalid serialization input.
• InvalidColorChannel: out-of-domain or malformed channel values for APIs that validate channel content.

Comparison with other implementations

See comparisons_results.md for the results.

Useful links

• https://www.w3.org/TR/css-color-4/
• https://github.com/w3c/csswg-drafts/blob/main/css-color-4/conversions.js
• https://github.com/color-js/color.js/tree/main/src/spaces