Skip to main content

NamedColor

Renfordt\Colors\NamedColor

Represents a color from the standard set of CSS/X11 color names (e.g. red, rebeccapurple, dodgerblue). A single name→hex table is the source of truth; every other representation is derived through the normal conversion chain. Implements \Stringable.

Properties​

PropertyTypeNotes
namestringThe standard color name. Assignment is normalized (trimmed + lower-cased) and validated; an unknown name throws InvalidArgumentException. Reading returns the normalized name.

Validation​

Names are case-insensitive and surrounding whitespace is ignored. A name that is not in the standard list raises InvalidArgumentException.

NamedColor::create('RebeccaPurple');  // ok -> "rebeccapurple"
NamedColor::create('  tomato  ');     // ok -> "tomato"
NamedColor::create('notacolor');      // throws InvalidArgumentException

Static methods​

create(string $name): NamedColor​

Creates an instance from a standard color name.

$named = NamedColor::create('tomato');

make(string $name): NamedColor​

Alias of create().

exists(string $name): bool​

Returns whether the given name is a known standard color. Case-insensitive and whitespace-tolerant; does not throw.

NamedColor::exists('Tomato');     // true
NamedColor::exists('notacolor');  // false

all(): array​

Returns the full list of standard colors as a name => hex map.

$all = NamedColor::all();
echo $all['tomato'];  // #ff6347
echo count($all);     // number of known colors

fromHex(HexColor $hex): ?NamedColor​

Returns the NamedColor that exactly matches the given hex color, or null when no standard color shares that value.

fromRGB(RGBColor $rgb): ?NamedColor​

Returns the NamedColor that exactly matches the given RGB color, or null when none matches. The match is on the RGB components only; alpha is ignored.

NamedColor::fromHex(HexColor::create('#ff6347'));   // NamedColor "tomato"
NamedColor::fromRGB(RGBColor::create([1, 2, 3]));    // null

findClosest(HexColor|RGBColor $color): NamedColor​

Returns the standard color whose value is nearest to the given color, measured as the Euclidean distance in RGB space. Always returns a NamedColor.

$closest = NamedColor::findClosest(HexColor::create('#ff6300'));
echo $closest->name;  // nearest standard color name

Instance methods​

toHex(): HexColor​

Returns the hexadecimal representation of the named color.

toRGB(): RGBColor​

Returns the RGB representation, via hex.

toHSL(int $precision = 4): HSLColor​

Returns the HSL representation, via hex. $precision controls rounding.

toHSV(int $precision = 4): HSVColor​

Returns the HSV representation, via hex. $precision controls rounding.

__toString(): string​

Returns the normalized color name.

echo (string) NamedColor::create('Tomato');  // tomato

Reverse lookup from other classes​

RGBColor::getName() and HexColor::getName() are convenience wrappers around the exact lookup, returning the matching standard name or null:

RGBColor::create([255, 99, 71])->getName();  // "tomato"
HexColor::create('#ff6347')->getName();       // "tomato"

Example​

use Renfordt\Colors\NamedColor;

$named = NamedColor::create('rebeccapurple');

$hex = $named->toHex();   // #663399
$rgb = $named->toRGB();   // RGBColor
$hsl = $named->toHSL();   // HSLColor

// Nearest name to an arbitrary color
$nearest = NamedColor::findClosest($rgb);