Skip to main content

Color

Renfordt\Colors\Color

A facade that inspects an arbitrary color string, detects its format, and returns the matching color object. It is the entry point to use when the format of a value is not known ahead of time — for example a string coming from user input, a config file, or a database.

The returned object is a regular HexColor, RGBColor, HSLColor, HSVColor, NamedColor, or RALColor, so it can be converted to any other format through the usual conversion chain.

use Renfordt\Colors\Color;

Color::parse('#FF3377AA')->toRGB();        // RGBColor with alpha
Color::parse('rgb(255, 51, 119)')->toHex();// HexColor
Color::parse('RebeccaPurple')->toHSL();    // HSLColor
Color::parse('RAL 3020')->toHex();         // HexColor

Supported inputs​

InputExampleReturns
Hex (3/4/6/8 digits)#FF3377AA, #f37, FF3377HexColor
Named (CSS/X11)red, RebeccaPurpleNamedColor
rgb() / rgba()rgb(255, 51, 119), rgba(0,0,0,.5)RGBColor
hsl() / hsla()hsl(340, 100%, 60%)HSLColor
hsv() / hsva()hsv(340, 80%, 100%)HSVColor
RAL classic codeRAL 3020, ral-1000RALColor

The input is trimmed before detection. Formats are tried in this order: functional notation (rgb/hsl/hsv), RAL code, named color, hex.

Static methods​

parse(string $input): HexColor|RGBColor|HSLColor|HSVColor|NamedColor|RALColor​

Detects the format of the given string and returns the matching color object.

Throws InvalidArgumentException when:

  • the string is empty (after trimming),
  • a RAL prefix is present but the code is not in the RAL table,
  • a functional notation has fewer than three components, or
  • no format can be detected.
Color::parse('hsl(340, 100%, 60%)');  // HSLColor
Color::parse('');                      // throws InvalidArgumentException
Color::parse('not-a-color');           // throws InvalidArgumentException
Color::parse('RAL 9999');              // throws InvalidArgumentException (unknown code)

make(string $input): HexColor|RGBColor|HSLColor|HSVColor|NamedColor|RALColor​

Alias of parse().

Functional notation​

Both the legacy comma syntax and the modern space/slash syntax are accepted, so commas, slashes, and surrounding whitespace are all treated as separators:

Color::parse('rgb(255, 51, 119)');        // legacy commas
Color::parse('rgb(255 51 119)');          // modern, space-separated
Color::parse('rgba(255 51 119 / 0.5)');   // modern, with alpha after a slash

Component values are interpreted per format:

  • RGB components accept an integer 0–255 or a percentage (50% → 128).
  • RGB alpha accepts a 0.0–1.0 opacity (CSS convention) or a percentage, scaled to the 0–255 integer alpha used by RGBColor.
  • Hue accepts a number with an optional deg suffix (340deg).
  • Saturation / lightness / value / alpha for HSL and HSV accept a percentage (100% → 1.0) or a 0.0–1.0 fraction.

Out-of-range values are not rejected here; they are clamped by the resulting color object as usual. See Concepts → Value ranges and clamping.

Color::parse('rgb(50%, 0, 100%)')->getRGB();   // [128, 0, 255]
Color::parse('hsl(340deg, 100%, 60%)')->hue;   // 340
Color::parse('rgba(0, 0, 0, 0.5)')->alpha;     // 128

RAL and named detection​

A RAL value must carry the RAL prefix (optionally followed by spaces or a hyphen) and a four-digit classic code. A recognised prefix with an unknown code raises InvalidArgumentException rather than falling through to another format:

Color::parse('RAL 3020');   // RALColor
Color::parse('ral-1000');   // RALColor
Color::parse('RAL 9999');   // throws InvalidArgumentException

Named colors are matched case-insensitively against the standard CSS/X11 list. See NamedColor.

See also​