Use collections and scales

Choose between named palettes, scales, and groups of parsed colors.

Choose a named palette when keys carry application meaning. Choose a scale when position and order carry the meaning. This structural decision controls which operations PHPColor can perform safely.

Choose a scale or a named palette

PHPColor has two palette shapes:

  • a scale is an ordered list addressed by integer keys;
  • a named palette is a map addressed by string keys.

The distinction controls which operations are valid. Positional interpolation, slicing, reversing, and merging are scale operations. CSS custom-property export is a named-palette operation.

Create a scale from color objects:

use PhpColor\Color\Color;
use PhpColor\Color\Palette\ColorPalette;

$scale = ColorPalette::scale([
    Color::parse('#dbeafe'),
    Color::parse('#3b82f6'),
    Color::parse('#1e3a8a'),
]);

echo $scale->count();
echo $scale->get(1)->toHex();

The output is 3 and #3b82f6. scale() requires at least one color.

Create a named palette when keys have semantic meaning:

use PhpColor\Color\Color;
use PhpColor\Color\Palette\ColorPalette;

$tokens = ColorPalette::named([
    'primary' => Color::parse('#3b82f6'),
    'success' => Color::parse('#10b981'),
    'warning' => Color::parse('#f59e0b'),
]);

echo $tokens->get('success')->toHex();

named() also requires at least one color. isNamed() tells you which shape a palette has, and names() returns the string keys of a named palette or an empty array for a scale.

Parse several colors at once

Use fromHex() for hexadecimal strings and parse() for mixed CSS color syntax:

use PhpColor\Color\Palette\ColorPalette;

$hexScale = ColorPalette::fromHex([
    '#dbeafe',
    '#3b82f6',
    '#1e3a8a',
]);

$named = ColorPalette::parse([
    'primary' => 'oklch(0.65 0.18 264)',
    'surface' => 'rgb(255 255 255)',
]);

Both methods preserve input keys. A list produces a scale; an associative array produces a named palette. Invalid color text is handled by the underlying parser and raises its parse exception.

Preserve the shape across boundaries

Do not remove names merely to call a positional method: the resulting indexes no longer express which color was primary, surface, or warning. Likewise, adding numeric labels to a scale does not turn its positions into semantic roles.

Convert or transform either shape as a complete collection when every member should follow the same rule. Use a separate mapping step when each semantic role requires different behavior.

Continue with Generate palettes, Export a palette as CSS variables, or ColorPalette.