Spot

Namespace: Com\Tecnick\Color

Extends: Web

Implements: SpotRegistryInterface

File: Spot.php line 58

Spot Color class

Extension points: getSpotColor() and the protected resolveSpotColorData(). The registry mutators and the PDF emitters are final.

Tags

• since: 2015-02-21
• category: Library
• author: Nicola Asuni info@tecnick.com
• copyright: 2015-2026 Nicola Asuni - Tecnick.com LTD
• license: https://www.gnu.org/copyleft/lesser.html GNU-LGPL v3 (see LICENSE)
• link: https://github.com/tecnickcom/tc-lib-color
• phpstan-type: TLabTriplet array{0: float, 1: float, 2: float}
• phpstan-type: TLabRange array{0: float, 1: float, 2: float, 3: float}
• phpstan-type: TSpotColor array{ ‘i’: int, ’n’: int, ’name’: string, ‘color’: Cmyk, ‘space’: ‘DeviceCMYK’|‘Lab’, ’lab’: array{ ‘whitepoint’: TLabTriplet, ‘blackpoint’: TLabTriplet, ‘range’: TLabRange, ‘c0’: TLabTriplet, ‘model’: Lab, }|null, }

Constants

DEFAULT_SPOT_COLORS

File: Spot.php line 75

public array<string, array{'name': string, 'color': array{'cyan': int|float, 'magenta': int|float, 'yellow': int|float, 'key': int|float, 'alpha': int|float}}> DEFAULT_SPOT_COLORS = ['none' => ['name' => 'None', 'color' => ['cyan' => 0, 'magenta' => 0, 'yellow' => 0, 'key' => 0, 'alpha' => 1]], 'all' => ['name' => 'All', 'color' => ['cyan' => 1, 'magenta' => 1, 'yellow' => 1, 'key' => 1, 'alpha' => 1]], 'cyan' => ['name' => 'Cyan', 'color' => ['cyan' => 1, 'magenta' => 0, 'yellow' => 0, 'key' => 0, 'alpha' => 1]], 'magenta' => ['name' => 'Magenta', 'color' => ['cyan' => 0, 'magenta' => 1, 'yellow' => 0, 'key' => 0, 'alpha' => 1]], 'yellow' => ['name' => 'Yellow', 'color' => ['cyan' => 0, 'magenta' => 0, 'yellow' => 1, 'key' => 0, 'alpha' => 1]], 'key' => ['name' => 'Key', 'color' => ['cyan' => 0, 'magenta' => 0, 'yellow' => 0, 'key' => 1, 'alpha' => 1]], 'white' => ['name' => 'White', 'color' => ['cyan' => 0, 'magenta' => 0, 'yellow' => 0, 'key' => 0, 'alpha' => 1]], 'black' => ['name' => 'Black', 'color' => ['cyan' => 0, 'magenta' => 0, 'yellow' => 0, 'key' => 1, 'alpha' => 1]], 'red' => ['name' => 'Red', 'color' => ['cyan' => 0, 'magenta' => 1, 'yellow' => 1, 'key' => 0, 'alpha' => 1]], 'green' => ['name' => 'Green', 'color' => ['cyan' => 1, 'magenta' => 0, 'yellow' => 1, 'key' => 0, 'alpha' => 1]], 'blue' => ['name' => 'Blue', 'color' => ['cyan' => 1, 'magenta' => 1, 'yellow' => 0, 'key' => 0, 'alpha' => 1]]]

WEBHEX

File: Web.php line 59

public array<string, string> WEBHEX = ['aliceblue' => 'f0f8ffff', 'antiquewhite' => 'faebd7ff', 'aqua' => '00ffffff', 'aquamarine' => '7fffd4ff', 'azure' => 'f0ffffff', 'beige' => 'f5f5dcff', 'bisque' => 'ffe4c4ff', 'black' => '000000ff', 'blanchedalmond' => 'ffebcdff', 'blue' => '0000ffff', 'blueviolet' => '8a2be2ff', 'brown' => 'a52a2aff', 'burlywood' => 'deb887ff', 'cadetblue' => '5f9ea0ff', 'chartreuse' => '7fff00ff', 'chocolate' => 'd2691eff', 'coral' => 'ff7f50ff', 'cornflowerblue' => '6495edff', 'cornsilk' => 'fff8dcff', 'crimson' => 'dc143cff', 'cyan' => '00ffffff', 'darkblue' => '00008bff', 'darkcyan' => '008b8bff', 'darkgoldenrod' => 'b8860bff', 'darkgray' => 'a9a9a9ff', 'darkgrey' => 'a9a9a9ff', 'dkgray' => 'a9a9a9ff', 'darkgreen' => '006400ff', 'darkkhaki' => 'bdb76bff', 'darkmagenta' => '8b008bff', 'darkolivegreen' => '556b2fff', 'darkorange' => 'ff8c00ff', 'darkorchid' => '9932ccff', 'darkred' => '8b0000ff', 'darksalmon' => 'e9967aff', 'darkseagreen' => '8fbc8fff', 'darkslateblue' => '483d8bff', 'darkslategray' => '2f4f4fff', 'darkslategrey' => '2f4f4fff', 'darkturquoise' => '00ced1ff', 'darkviolet' => '9400d3ff', 'deeppink' => 'ff1493ff', 'deepskyblue' => '00bfffff', 'dimgray' => '696969ff', 'dimgrey' => '696969ff', 'dodgerblue' => '1e90ffff', 'firebrick' => 'b22222ff', 'floralwhite' => 'fffaf0ff', 'forestgreen' => '228b22ff', 'fuchsia' => 'ff00ffff', 'gainsboro' => 'dcdcdcff', 'ghostwhite' => 'f8f8ffff', 'gold' => 'ffd700ff', 'goldenrod' => 'daa520ff', 'gray' => '808080ff', 'grey' => '808080ff', 'green' => '008000ff', 'greenyellow' => 'adff2fff', 'honeydew' => 'f0fff0ff', 'hotpink' => 'ff69b4ff', 'indianred' => 'cd5c5cff', 'indigo' => '4b0082ff', 'ivory' => 'fffff0ff', 'khaki' => 'f0e68cff', 'lavender' => 'e6e6faff', 'lavenderblush' => 'fff0f5ff', 'lawngreen' => '7cfc00ff', 'lemonchiffon' => 'fffacdff', 'lightblue' => 'add8e6ff', 'lightcoral' => 'f08080ff', 'lightcyan' => 'e0ffffff', 'lightgoldenrodyellow' => 'fafad2ff', 'lightgray' => 'd3d3d3ff', 'lightgrey' => 'd3d3d3ff', 'ltgray' => 'd3d3d3ff', 'lightgreen' => '90ee90ff', 'lightpink' => 'ffb6c1ff', 'lightsalmon' => 'ffa07aff', 'lightseagreen' => '20b2aaff', 'lightskyblue' => '87cefaff', 'lightslategray' => '778899ff', 'lightslategrey' => '778899ff', 'lightsteelblue' => 'b0c4deff', 'lightyellow' => 'ffffe0ff', 'lime' => '00ff00ff', 'limegreen' => '32cd32ff', 'linen' => 'faf0e6ff', 'magenta' => 'ff00ffff', 'maroon' => '800000ff', 'mediumaquamarine' => '66cdaaff', 'mediumblue' => '0000cdff', 'mediumorchid' => 'ba55d3ff', 'mediumpurple' => '9370dbff', 'mediumseagreen' => '3cb371ff', 'mediumslateblue' => '7b68eeff', 'mediumspringgreen' => '00fa9aff', 'mediumturquoise' => '48d1ccff', 'mediumvioletred' => 'c71585ff', 'midnightblue' => '191970ff', 'mintcream' => 'f5fffaff', 'mistyrose' => 'ffe4e1ff', 'moccasin' => 'ffe4b5ff', 'navajowhite' => 'ffdeadff', 'navy' => '000080ff', 'oldlace' => 'fdf5e6ff', 'olive' => '808000ff', 'olivedrab' => '6b8e23ff', 'orange' => 'ffa500ff', 'orangered' => 'ff4500ff', 'orchid' => 'da70d6ff', 'palegoldenrod' => 'eee8aaff', 'palegreen' => '98fb98ff', 'paleturquoise' => 'afeeeeff', 'palevioletred' => 'db7093ff', 'papayawhip' => 'ffefd5ff', 'peachpuff' => 'ffdab9ff', 'peru' => 'cd853fff', 'pink' => 'ffc0cbff', 'plum' => 'dda0ddff', 'powderblue' => 'b0e0e6ff', 'purple' => '800080ff', 'rebeccapurple' => '663399ff', 'red' => 'ff0000ff', 'rosybrown' => 'bc8f8fff', 'royalblue' => '4169e1ff', 'saddlebrown' => '8b4513ff', 'salmon' => 'fa8072ff', 'sandybrown' => 'f4a460ff', 'seagreen' => '2e8b57ff', 'seashell' => 'fff5eeff', 'sienna' => 'a0522dff', 'silver' => 'c0c0c0ff', 'skyblue' => '87ceebff', 'slateblue' => '6a5acdff', 'slategray' => '708090ff', 'slategrey' => '708090ff', 'snow' => 'fffafaff', 'springgreen' => '00ff7fff', 'steelblue' => '4682b4ff', 'tan' => 'd2b48cff', 'teal' => '008080ff', 'thistle' => 'd8bfd8ff', 'tomato' => 'ff6347ff', 'turquoise' => '40e0d0ff', 'violet' => 'ee82eeff', 'wheat' => 'f5deb3ff', 'white' => 'ffffffff', 'whitesmoke' => 'f5f5f5ff', 'yellow' => 'ffff00ff', 'yellowgreen' => '9acd32ff']

Methods

__construct()

File: Css.php line 75

public __construct([ComponentNormalizer|null $normalizer = null ]) : mixed

Parameters

• $normalizer : ComponentNormalizer|null = null: Component scaler; the default is used when omitted.

addSpotColor()

File: Spot.php line 413

public final addSpotColor(string $name, Cmyk $cmyk) : string

Parameters

• $name : string: Full name of the spot color.
• $cmyk : Cmyk: CMYK color object

Tags

• throws: Exception if the name is unusable or the color has already been emitted by getPdfSpotObjects()

Return values

string —

Spot color key.

addSpotColorFromArray()

File: Spot.php line 441

public final addSpotColorFromArray(string $name, array<string, int|float|string> $components) : string

Parameters

• $name : string: Full name of the spot color.
• $components : array<string, int|float|string>: CMYK components.

Tags

• throws: Exception if the name is unusable or the color has already been emitted
• throws: UnknownComponentException if $components carries a name the CMYK model does not define

Return values

string —

Spot color key.

addSpotLabColor()

File: Spot.php line 475

public final addSpotLabColor(string $name, float $lstar, float $astar, float $bstar, array<int, float> ...$labOptions) : string

The optional Lab settings are passed as separate trailing array arguments, in this order: whitepoint, blackpoint, range, col0. For example: addSpotLabColor(‘My Color’, 50.0, 10.0, -20.0, $whitepoint, $blackpoint, $range, $col0); Each option array is read element by element, so a shorter array is allowed and any missing element falls back to its default: D65 whitepoint [0.9505, 1.0, 1.089], zero blackpoint, [-128, 127, -128, 127] range and [100, 0, 0] col0.

NOTE: the stored CMYK equivalent is an approximation computed from the Lab values using the D65 whitepoint; the whitepoint option only affects the PDF Lab color space metadata emitted by getPdfSpotObjects(), not the CMYK fallback.

The range option is clamped to [-128..127], the interval the Lab color model represents.

Parameters

• $name : string: Full name of the spot color.
• $lstar : float: Lab L* component in [0..100].
• $astar : float: Lab a* component.
• $bstar : float: Lab b* component.
• $labOptions : array<int, float>: Optional Lab settings: whitepoint, blackpoint, range, col0.

Tags

• throws: Exception if the name is unusable or the color has already been emitted by getPdfSpotObjects()

Return values

string —

Spot color key.

encodeSpotColorName()

File: Spot.php line 258

public final encodeSpotColorName(string $name) : string

The original name is preserved as-is, including spaces and uppercase letters. Any byte that is not a regular PDF name character is escaped as “#” followed by a 2-digit uppercase hexadecimal code, as required by the PDF name object syntax (ISO 32000-1:2008, 7.3.5). For example “SPOTTYPE 279 C” becomes “SPOTTYPE#20279#20C”.

The result is not truncated to the 127-byte name object limit set by ISO 32000-1:2008, Annex C.2.

Parameters

• $name : string: Full name of the spot color.

Return values

string

extractHexCode()

File: Web.php line 268

public final extractHexCode(string $hex) : string

Parameters

• $hex : string: string containing the hexadecimal color hash (i.e. #RGB, #RGBA, #RRGGBB, #RRGGBBAA)

Tags

• throws: Exception if the hash is not found or has an invalid format

Return values

string —

the hash code (e.g.: ‘40e0d0’)

getClosestWebColor()

File: Web.php line 463

public final getClosestWebColor(array<string, float> $col) : string

Nearness is the Euclidean distance in sRGB, which is not perceptually uniform; getClosestWebColorByDeltaE() gives a perceptual match. A missing component counts as 0, so an empty array matches black. Ties resolve to the first matching color name.

Parameters

• $col : array<string, float>: Color as RGB array (keys: ‘red’, ‘green’, ‘blue’)

Return values

string

getClosestWebColorByDeltaE()

File: Web.php line 535

public final getClosestWebColorByDeltaE(array<string, float> $col) : string

Nearness is the CIE76 color difference in CIE Lab. Ties resolve to the first matching color name.

Parameters

• $col : array<string, float>: Color as Lab array (keys: ’lstar’, ‘astar’, ‘bstar’)

Return values

string

getClosestWebColorByDeltaEFromString()

File: Web.php line 556

public final getClosestWebColorByDeltaEFromString(string $color) : string

Parameters

• $color : string: String containing web color definition

Return values

string

getClosestWebColorFromString()

File: Web.php line 483

public final getClosestWebColorFromString(string $color) : string

Parameters

• $color : string: String containing web color definition

Return values

string

getColorObj()

File: Web.php line 391

public getColorObj(string $color) : Model|null

Parameters

• $color : string: String containing web color definition

Tags

• throws: Exception if the hash is malformed, the name is unknown, the color function is unsupported or its syntax is invalid, or the expression cannot be evaluated

Return values

Model|null

getHexFromName()

File: Web.php line 224

public final getHexFromName(string $name) : string

Everything up to and including the first dot is discarded, so the Acrobat JavaScript spelling ‘color.green’ resolves to ‘green’.

Parameters

• $name : string: Name of the color to search (e.g.: ’turquoise’)

Tags

• throws: Exception if the color is not found

Return values

string —

color hexadecimal code (e.g.: ‘40e0d0ff’)

getLabSquareDistance()

File: Web.php line 518

public final getLabSquareDistance(array<string, float> $cola, array<string, float> $colb) : float

Parameters

• $cola : array<string, float>: First color as Lab array
• $colb : array<string, float>: Second color as Lab array

Return values

float

getNameFromHex()

File: Web.php line 249

public final getNameFromHex(string $hex) : string

Parameters

• $hex : string: hexadecimal color hash (i.e. #RRGGBBAA)

Tags

• throws: Exception if the color is not found

Return values

string —

color name

getPdfSpotObjects()

File: Spot.php line 626

public final getPdfSpotObjects(int &$pon) : string

Only the entries emitted here can be listed as a resource by getPdfSpotResources().

Parameters

• $pon : int: Current PDF object number

Return values

string —

PDF command

getPdfSpotResources()

File: Spot.php line 777

public final getPdfSpotResources() : string

Call getPdfSpotObjects() first: every registered spot color must have been emitted as a PDF object.

Tags

• throws: Exception if a registered spot color has not been emitted

Return values

string —

PDF command

getPdfSpotResourcesByKeys()

File: Spot.php line 791

public final getPdfSpotResourcesByKeys(array<string|int, string> $keys) : string

Parameters

• $keys : array<string|int, string>: Array of spot color keys.

Tags

• throws: Exception if a key is not registered or has not been emitted

Return values

string —

PDF command

getRgbObjFromHex()

File: Web.php line 312

public final getRgbObjFromHex(string $hex) : Rgb

Parameters

• $hex : string: hexadecimal color hash (i.e. #RGB, #RGBA, #RRGGBB, #RRGGBBAA)

Tags

• throws: Exception if the hash is malformed or has an unsupported length

Return values

Rgb

getRgbObjFromName()

File: Web.php line 326

public final getRgbObjFromName(string $name) : Rgb

Parameters

• $name : string: Color name

Tags

• throws: Exception if the color is not found

Return values

Rgb —

object

getRgbSquareDistance()

File: Web.php line 444

public final getRgbSquareDistance(array<string, float> $cola, array<string, float> $colb) : float

Parameters

• $cola : array<string, float>: First color as RGB array
• $colb : array<string, float>: Second color as RGB array

Return values

float

getSpotColor()

File: Spot.php line 293

public getSpotColor(string $name) : TSpotColor

A default spot color that is not yet registered is added to the internal registry, so that it is emitted by getPdfSpotObjects() and getPdfSpotResources(). Use resolveSpotColorData() for a lookup with no side effect.

Parameters

• $name : string: Full name of the spot color.

Tags

• throws: Exception if the color is not found

Return values

TSpotColor

getSpotColorObj()

File: Spot.php line 352

public final getSpotColorObj(string $name) : Cmyk

Parameters

• $name : string: Full name of the spot color.

Tags

• throws: Exception if the color is not found

Return values

Cmyk

getSpotColors()

File: Spot.php line 202

public final getSpotColors() : array<string, TSpotColor>

The color models are copies of the registered ones.

Return values

array<string, TSpotColor>

getSpotLabColorObj()

File: Spot.php line 367

public final getSpotLabColorObj(string $name) : Lab

A CMYK-defined spot color has no Lab metadata, so its Lab equivalent is derived on the fly.

Parameters

• $name : string: Full name of the spot color.

Tags

• throws: Exception if the color is not found

Return values

Lab

normalizeSpotColorName()

File: Spot.php line 238

public final normalizeSpotColorName(string $name) : string

Every character outside [a-z0-9] is dropped, so names that differ only in punctuation, spacing or accents share a key: ‘Bleu Ciel é’ and ‘Bleu-Ciel’ both normalize to ‘bleuciel’.

Parameters

• $name : string: Full name of the spot color.

Return values

string

normalizeValue()

File: Web.php line 377

public final normalizeValue(mixed $value, int $max) : float

Delegates to ComponentNormalizer::normalize().

Parameters

• $value : mixed: Value to convert
• $max : int: Max input value (reference value), must be positive

Return values

float —

value [0..1]

tryGetColorObj()

File: Web.php line 427

public final tryGetColorObj(string $color) : Model|null

Parameters

• $color : string: String containing web color definition

Return values

Model|null