Choose text or channel input

Choose between parsing text, normalizing an existing object, and constructing channels whose color space and numeric scale are already known.

Parse text when the notation identifies its own space and channel scales. Construct a color directly only when the producer already guarantees the numeric schema. Use Color::from() when a boundary accepts either a string or an existing color object.

Match the entry point to the data contract

Available input Entry point Why
A concrete CSS color string Color::parse() The notation defines how to interpret the values
A string or ColorInterface Color::from() One boundary normalizes both accepted PHP types
Known normalized sRGB channels Color::rgb() The application already owns the channel schema
Known Oklab or Oklch channels Color::oklab() or Color::oklch() The application already owns the space and scale
Channels in another supported space Its public concrete class The class makes the required space explicit

Parsing and construction can represent the same color, but they start from different contracts:

use PhpColor\Color\Color;

$parsed = Color::parse('rgb(59 130 246)');
$constructed = Color::rgb(59 / 255, 130 / 255, 246 / 255);
$normalized = Color::from($constructed);

echo $parsed->toHex().PHP_EOL;
echo $constructed->toHex().PHP_EOL;
echo ($normalized === $constructed ? 'same object' : 'new object').PHP_EOL;

The output is:

#3b82f6
#3b82f6
same object

Color::from() returns an existing ColorInterface unchanged. When it receives a string, it delegates to the concrete color parser.

Treat numeric channels as typed data

The facade provides focused constructors for common spaces:

use PhpColor\Color\Color;

$srgb = Color::rgb(0.23, 0.51, 0.96);
$oklab = Color::oklab(0.62, -0.05, -0.15);
$oklch = Color::oklch(0.65, 0.18, 264, 0.8);

echo $srgb::getSpaceName().PHP_EOL;
echo $oklab::getSpaceName().PHP_EOL;
echo $oklch->toCss().PHP_EOL;

The output is:

srgb
oklab
oklch(0.65 0.18 264 / 0.8)

sRGB channels passed to Color::rgb() use normalized values, not CSS integer values from 0 to 255. Oklab and Oklch lightness use a unit scale, and Oklch hue uses degrees.

Direct constructors do not share one validation policy. Some classes clamp some channels, while other classes preserve values outside their documented range. They are therefore not a substitute for validating an unknown numeric payload. Validate the payload's keys, numeric types, ranges, and declared color space before construction.

Use a concrete class when the space is part of the schema

The facade does not provide a named constructor for every supported space. A producer that explicitly supplies Display P3 coordinates can map them to the corresponding class:

use PhpColor\Color\DisplayP3Color;

$color = new DisplayP3Color(0.25, 0.5, 0.9, 0.75);

echo $color::getSpaceName().PHP_EOL;
echo $color->toCss().PHP_EOL;

The output is:

display-p3
color(display-p3 0.25 0.5 0.9 / 0.75)

Do not infer a color space from three unlabeled numbers. The same triplet has different meaning in sRGB, Display P3, Lab, and Oklab.

Keep convenience constructors in perspective

Methods such as Color::black(), Color::white(), and Color::red() provide familiar sRGB constants. They improve readability when the exact constant is part of the code, but they do not replace parsing for arbitrary CSS names.

Use Supported concrete color input for external text. Continue with Choose an invalid-input contract when malformed text is an expected possibility.

Continue