Choose an invalid-input contract

Decide when malformed color input should raise a parsing exception, return null, or pass into a separate application policy check.

Use Color::parse() when invalid input means a broken program or configuration contract. Use Color::tryFrom() when failure is an expected branch, such as form validation or an optional import.

Choose failure behavior at the boundary

Situation Recommended entry point Result on invalid text
A trusted configuration value must be valid Color::parse() Throws ParseException
A form field may contain invalid text Color::tryFrom() Returns null
An import must report why each row failed Color::parse() inside a try block Preserves the parsing error
A parameter accepts a string or an existing color Color::from() or Color::tryFrom() Parses strings and preserves objects

The two failure modes are deliberately different:

use PhpColor\Color\Color;
use PhpColor\Color\Exception\ParseException;

$maybeColor = Color::tryFrom('not-a-color');
echo (null === $maybeColor ? 'null' : 'color').PHP_EOL;

try {
    Color::parse('not-a-color');
} catch (ParseException $exception) {
    echo $exception::class.PHP_EOL;
}

The output is:

null
PhpColor\Color\Exception\ParseException

tryFrom() catches parsing failures and discards their details. Do not use it when the caller must distinguish malformed syntax from an unsupported color() space.

Separate syntax acceptance from application policy

A successful parse means that PHPColor recognizes the concrete color syntax. It does not mean the value satisfies every rule in your application.

For example, an application may accept only sRGB values even though PHPColor can parse Display P3:

use PhpColor\Color\Color;

$color = Color::tryFrom('color(display-p3 0.82 0.23 0.18)');

if (null === $color) {
    echo 'invalid syntax'.PHP_EOL;
} elseif ('srgb' !== $color::getSpaceName()) {
    echo 'valid color, unsupported application space'.PHP_EOL;
}

The output is:

valid color, unsupported application space

Apply requirements such as allowed spaces, required opacity, storage format, or accessibility thresholds after parsing. Those are policy decisions, not syntax errors.

Preserve useful errors where they matter

Exceptions are useful when a failure indicates a defect that should stop the operation. A malformed color in a checked configuration file is different from a user mistyping a form value.

At an interactive boundary, a nullable result is often enough to attach a stable application message. The Validate a CSS color input recipe shows that complete form task. At an import boundary, catching ParseException lets the importer associate the original error with a row or field.

Know what nullable parsing hides

Color::tryFrom() returns an existing ColorInterface unchanged. For strings, it returns null only when parsing raises ParseException. It does not provide a structured error result or identify the original notation.

If a CSS expression depends on variables, the current color, or the color scheme, do not classify it as malformed merely because Color::parse() cannot resolve it. Concrete and deferred CSS colors explains the separate contextual path.

Continue