Convert first when the consumer requires a specific space. Otherwise, call toCss() without an argument to preserve the object's native representation. Formatting should express an already-made color decision, not silently choose the working space.
Keep conversion and formatting separate
Conversion changes coordinates. Formatting turns the current value into text. Keeping those steps visible makes gamut reduction and browser delivery choices reviewable.
Format in the object's native CSS syntax
Calling toCss() with no argument asks the concrete color object for its native CSS representation:
use PhpColor\Color\Color;
$rgb = Color::parse('#3b82f6');
$oklch = $rgb->to('oklch');
$p3 = $rgb->to('display-p3');
echo $rgb->toCss();
echo $oklch->toCss();
echo $p3->toCss();
The output is:
rgb(59 130 246)
oklch(0.623083 0.188015 259.815)
color(display-p3 0.310018 0.503944 0.936356)
Native output is usually the clearest choice after an explicit conversion.
PHPColor omits alpha from native CSS output when it is exactly 1.0. For a partially transparent color, the CSS string includes / followed by the formatted alpha.
Convert first when you need predictable output
The optional argument accepted by toCss() is implemented by each concrete color class. It is a formatting request, not the universal conversion registry used by to(). Supported requests therefore depend on the current class.
For predictable output, convert to the target object and then format it:
use PhpColor\Color\Color;
$color = Color::parse('oklch(0.65 0.18 264)');
$rgbCss = $color->to('srgb')->toCss();
$p3Css = $color->to('display-p3')->toCss();
$labCss = $color->to('lab')->toCss();
echo $rgbCss;
echo $p3Css;
echo $labCss;
This approach avoids assuming that the source class can directly format every other space. Passing an unsupported format to toCss() raises InvalidColorException.
An sRGB object also supports HSL formatting without creating a separate HSL object:
use PhpColor\Color\Color;
$hsl = Color::parse('#ff0000')->toSrgb()->toCss('hsl');
echo $hsl;
The output is hsl(0 100% 50%). HSL formatting is an sRGB presentation option; hsl is not a registered target for to().
Choose delivery syntax for the consumer
Use native decimal CSS to retain a wide-gamut or perceptual space. Use rgb() or hexadecimal only when the consumer requires conventional sRGB. PHPColor does not generate a fallback declaration pair or detect browser support; create the fallback and enhancement as separate application output.
Continue with Precision and gamut, Generate hexadecimal output, or ColorInterface.