Convert between spaces

Convert colors when an operation or consumer requires a different coordinate system, without treating conversion as formatting.

Convert when the next operation needs different coordinates or the next system requires a named schema. Do not convert merely to make a color "standard": every conversion introduces a target space, and RGB targets can introduce gamut clipping.

Separate working coordinates from delivery

One color can move through three representations in a single workflow:

  1. the input space records what arrived;
  2. the working space exposes useful channels;
  3. the delivery space matches the consumer.
use PhpColor\Color\Color;

$source = Color::parse('#3b82f6');
$working = $source->to('oklch');
$delivery = $working->to('display-p3');

echo $source::getSpaceName().PHP_EOL;
echo $working::getSpaceName().PHP_EOL;
echo $delivery->toCss().PHP_EOL;

The output is:

srgb
oklch
color(display-p3 0.310018 0.503944 0.936356)

Each call returns a new representation. The original object remains unchanged.

Use canonical names at application boundaries

Use to() for application-level conversion:

use PhpColor\Color\Color;
use PhpColor\Color\OklchColor;

$source = Color::parse('#3b82f6');
$converted = $source->to('oklch');

var_dump($converted instanceof OklchColor);
var_dump($source::getSpaceName());
var_dump($converted::getSpaceName());

The checks produce true, srgb, and oklch.

Use canonical names in configuration and application code so the target remains visible. An unsupported name raises PhpColor\Color\Exception\InvalidColorException.

Use toSrgb() when the target is known

Every color implements toSrgb():

use PhpColor\Color\Color;
use PhpColor\Color\SrgbColor;

$color = Color::parse('oklch(0.65 0.18 264 / 0.8)');
$srgb = $color->toSrgb();

var_dump($srgb instanceof SrgbColor);
var_dump($srgb->getAlpha());

The checks produce true and 0.8. Conversion preserves alpha. Use the generic to() method for other target spaces; typed conversion helpers beyond toSrgb() are specific to particular concrete classes and are not part of the common ColorInterface contract.

Verify the target that matters

Conversion and formatting answer different questions. to('display-p3') chooses coordinates; toCss() serializes the current object; toHex() converts again through sRGB and quantizes the result.

When gamut or exact output matters, verify the serialized representation that the consumer receives. A successful conversion does not perform general gamut mapping, add CSS fallbacks, or preserve an out-of-gamut color in hexadecimal.

Continue with Choose a color space, Format CSS colors, or ColorInterface for the complete conversion contract.