README

Color Engine for PHP

About Colority

Colority is a PHP library for working with colors. It handles conversions between RGB, HSL, Hex, and OKLCH formats, calculates WCAG-compliant contrast ratios, extracts color palettes from images, and more.

Features

Getting Started

Instantiating Color Objects
- Create RGB, HSL, Hex, and OKLCH color objects from strings or arrays
- Auto-detect color format with parse() method
Contrast Ratio (WCAG 2.0)
- getBestForegroundColor: Pick the best color from a list of candidates
- getMatchingForegroundColor: Generate a foreground color that matches the background's hue
- getContrastRatio: Calculate contrast ratios between colors
- ContrastRatioScore Enum: Validate accessibility compliance
Color Validation
- Parse and validate color strings with type-specific parsers
Color Conversion
- Convert between RGB, HSL, Hexadecimal, and OKLCH formats
Semantic Palette
- Eight built-in semantic slots (primary, secondary, success, danger, warning, info, light, dark) with overrides per slot, in bulk, or by custom name

Color Utilities

Color Adjustments: Adjust brightness and saturation
getImageMostCommonColor: Get the single most common color in an image
getImageColors: Extract representative colors from images using K-Means clustering
getImageDominantColors: Extract dominant colors by pixel frequency with metadata
textToColor: Generate deterministic colors from strings (usernames, emails, etc.)
getSimilarColor: Get random colors in the same palette
random: Generate completely random colors
gradient: Create smooth color gradients between multiple colors

Using Colority

Ways of using Colority
- Helper function colority() and facade pattern

Documentation & Resources

API Reference: Complete documentation of all classes and methods
Installation and Requirements: Get started with Composer

Getting Started

Instantiating Color objects

You can convert value colors (strings or, additionally, depending on the color type, arrays) to specific Color objects.

/**
 * RGB format - Commas, whitespace or any combination accepted
 *
 * @var RgbColor $rgbColor
 */
$rgbColor = colority()->fromRgb('rgb(255,255,255)');
$rgbColor = colority()->fromRgb('rgb(255, 255, 255)');
$rgbColor = colority()->fromRgb('rgb(255 255 255)');
$rgbColor = colority()->fromRgb('255,255,255');
$rgbColor = colority()->fromRgb('255 255 255');
$rgbColor = colority()->fromRgb([255, 255, 255]);

/**
 * Hexadecimal format - With or without hash, shorthand supported,
 * and array of three RGB byte values [R, G, B]
 *
 * @var HexColor $hexColor
 */
$hexColor = colority()->fromHex('#51B389');
$hexColor = colority()->fromHex('51B389');
$hexColor = colority()->fromHex('#ABC');
$hexColor = colority()->fromHex([81, 179, 137]);

/**
 * HSL format - Commas, whitespace, with or without deg/% units
 *
 * @var HslColor $hslColor
 */
$hslColor = colority()->fromHsl('hsl(168.31deg, 49.58%, 46.67%)');
$hslColor = colority()->fromHsl('hsl(168.31 49.58% 46.67%)');
$hslColor = colority()->fromHsl('168.31, 49.58, 46.67');
$hslColor = colority()->fromHsl('168.31 49.58 46.67');
$hslColor = colority()->fromHsl([168.31, 49.58, 46.67]);

/**
 * OKLCH format - Commas, whitespace, percentage form for L and C,
 * angle units (deg, rad, turn, grad) for H
 *
 * @var OklchColor $oklchColor
 */
$oklchColor = colority()->fromOklch('oklch(0.70 0.11 163)');
$oklchColor = colority()->fromOklch('oklch(0.70, 0.11, 163)');
$oklchColor = colority()->fromOklch('oklch(70% 27.5% 163deg)');
$oklchColor = colority()->fromOklch('oklch(0.70 0.11 0.45turn)');
$oklchColor = colority()->fromOklch('0.70 0.11 163');
$oklchColor = colority()->fromOklch([0.70, 0.11, 163]);

Separator flexibility: RGB, HSL and OKLCH accept commas, whitespace or any combination as component separators (CSS Color Module Level 4). The internal canonical form remains stable: RGB and HSL store with commas, OKLCH stores with whitespace.

If you cannot specify the original format of the value color, use the parse() method. It will auto-detect the color type and return the appropriate Color object, or null if the format is invalid.

/** @var RgbColor|null $rgbColor */
$rgbColor = colority()->parse('rgb(255,255,255)');

/** @var HexColor|null $hexColor */
$hexColor = colority()->parse('#51B389');

/** @var HslColor|null $hslColor */
$hslColor = colority()->parse('hsl(168.31deg, 49.58%, 46.67%)');

/** @var OklchColor|null $oklchColor */
$oklchColor = colority()->parse('oklch(0.70 0.11 163)');

/** 
 * CSS gradients are auto-detected and resolved to the dominant stop:
 * 
 * @var RgbColor|null $dominantColor 
 */
$dominantColor = colority()->parse(
    'linear-gradient(135deg, rgb(17, 153, 142) 0%, rgb(56, 239, 125) 100%)'
);

// Always returns null for invalid formats
$invalid = colority()->parse('not-a-color'); // null

Gradients

parse() accepts CSS gradient strings and returns the dominant single color of the gradient, the stop whose visual area along the gradient axis is the largest.

$color = colority()->parse(
    'linear-gradient(135deg, rgb(17, 153, 142) 0%, rgb(56, 239, 125) 100%)'
);
// rgb(17,153,142) first stop wins on a 50/50 split

$color = colority()->parse(
    'linear-gradient(rgb(255,0,0) 0%, rgb(0,0,255) 30%, rgb(0,255,0) 100%)'
);
// rgb(0,0,255) blue dominates the 15%-65% range (50 units of width)

Supported syntax:

linear-gradient(...), radial-gradient(...), conic-gradient(...).
Any combination of CSS-supported color formats inside the stops (hex, rgb, hsl, oklch).
Optional <position>% after each stop. Missing positions are filled in following CSS rules: first stop defaults to 0%, last stop defaults to 100%, intermediate gaps are evenly distributed between declared neighbors.
Trailing !important is stripped before parsing.
Metadata segments (angle like 135deg, shape like circle, position like from 90deg at 50% 50%) are detected and skipped.

Dominance rule: for each stop the dominance interval is bounded by the midpoints with its neighbors (clamped to [0, 100] at the ends). The stop with the widest interval wins. Ties resolve to the first stop in declaration order.

Limitations:

Named CSS colors (red, blue, etc.) are not supported as stops; use hex/rgb/hsl/oklch.
The library returns one of the original stops, not a perceptual average. If every stop fails to parse, parse() returns null.

Contrast ratio (WCAG 2.0 standard)

When you have the Color object, you will be able to use all its methods. Below, we describe two of them related to the contrast ratio.

getBestForegroundColor

Returns a Color object with the most suitable foreground color (using the Luminosity Contrast Ratio algorithm).

You can pass an array with Color objects as a parameter, so it chooses the foreground color with the best contrast ratio. If no parameter is specified, it will default to white or black.

$hexColor = colority()->fromHex('#51B389');

/**
 * Automatic choice: Returns black or white, whichever has better contrast
 * 
 * @var HexColor $bestForegroundHexColor
 */
$bestForegroundHexColor = $hexColor->getBestForegroundColor();

/**
 * Custom palette: Chooses the best option from your brand colors
 * 
 * @var HexColor $bestForegroundHexColor
 */
$bestForegroundHexColor = $hexColor->getBestForegroundColor([
    new HexColor('#A63F3F'),
    new HexColor('#3FA684'),
    new HexColor('#6E3FA6'),
]);

getContrastRatio

Returns the contrast ratio (higher is better contrast, lower is worse) between the color invoking this method and the color passed as a parameter. If no color is passed as a parameter, the contrast ratio against black as foreground will be determined.

$hexColor = colority()->fromHex('#51B389');

/**
 * Contrast ratio with black (default)
 * 
 * @var float $contrastRatio
 */
$contrastRatio = $hexColor->getContrastRatio();

/**
 * Contrast ratio with a specific foreground color
 * 
 * @var float $contrastRatio
 */
$contrastRatio = $hexColor->getContrastRatio(new HexColor('#3FA684'));

Contrast ratio scale:

1.0: No contrast (same color)
3.0: Minimum for UI components (WCAG AA)
4.5: Minimum for normal text (WCAG AA)
7.0: Enhanced contrast for normal text (WCAG AAA)
21.0: Maximum contrast (black on white)

getMatchingForegroundColor

Generates a foreground color that preserves the background's hue while meeting WCAG contrast requirements.

Difference from getBestForegroundColor:

getBestForegroundColor() picks the best color from a list of candidates (defaults to black/white)

getMatchingForegroundColor() generates a new color by adjusting lightness while keeping the same hue

use Tomloprod\Colority\Support\Algorithms\ContrastRatioScore;

$backgroundColor = colority()->fromHex('#336699');

// AAA level by default
$foregroundColor = $backgroundColor->getMatchingForegroundColor();

// AA level for relaxed contrast requirements
$foregroundColor = $backgroundColor->getMatchingForegroundColor(ContrastRatioScore::Good);

// With custom lightness step (faster but less precise)
$foregroundColor = $backgroundColor->getMatchingForegroundColor(
    targetScore: ContrastRatioScore::Good,
    lightnessStep: 5 // the default value is 1
);

Optional parameters:

targetScore (default: ContrastRatioScore::Excellent): The desired contrast level. See ContrastRatioScore Enum.
lightnessStep (default: 1): The amount of lightness points (1-100) to jump in each iteration while searching for a matching color. Larger values are faster but less precise.

ContrastRatioScore Enum

The Tomloprod\Colority\Support\Algorithms\ContrastRatioScore enum defines the standard contrast levels and provides helper methods to validate them.

Available contrast levels:

ContrastRatioScore::Excellent (default): 7:1 ratio (WCAG AAA for normal text)
ContrastRatioScore::Good: 4.5:1 ratio (WCAG AA for normal text)
ContrastRatioScore::Acceptable: 3:1 ratio (WCAG AA for large text/UI).
ContrastRatioScore::Insufficient

You can also use the enum's static methods to manually check if a specific contrast ratio meets WCAG levels:

/** @var HexColor $hexColor */
$hexColor = colority()->fromHex('#51B389');

/**
 * The `getContrastRatio` method can take a `Color` object as the foreground 
 * to calculate the contrast ratio against that color. Black is used by default.
 * 
 * @var float $contrastRatio
 */
$contrastRatio = $hexColor->getContrastRatio();

/**
 * AA Level for texts
 */
$passsesAALevelForLargeText = ContrastRatioScore::passesTextAALevel(
    contrastRatio: $contrastRatio,
    largeText: true
);

$passsesAALevelForNormalText = ContrastRatioScore::passesTextAALevel(
    contrastRatio: $contrastRatio,
    largeText: false
);

/**
 * AAA Level for texts
 */
$passsesAAALevelForLargeText = ContrastRatioScore::passesTextAAALevel(
    contrastRatio: $contrastRatio,
    largeText: true
);

$passsesAAALevelForNormalText = ContrastRatioScore::passesTextAAALevel(
    contrastRatio: $contrastRatio,
    largeText: false
);

/**
 * AA Level for Graphical Objects and User Interface Components
 */
$passsesAALevelForUI = ContrastRatioScore::passesUIAALevel(
    $contrastRatio
);

Color validation

The concrete Color classes have a static method called getParser() which returns an instance of ValueColorParser.

The parse method returns a string with the value color adapted to work correctly with Colority or throws an InvalidArgumentException when it's not valid.

use Tomloprod\Colority\Colors\HexColor;
use InvalidArgumentException;

$hexParser = HexColor::getParser();

try {

    // This will throw InvalidArgumentException
    $valueColor = $hexParser->parse('Not a valid value color');

} catch (InvalidArgumentException $e) {
    // Handle invalid color format
}

// Normalize shorthand: Returns "#FFFFFF"
$valueColor = $hexParser->parse('#FFF');

You can use the specific parser for any type of color:

use Tomloprod\Colority\Colors\{HexColor, HslColor, RgbColor, OklchColor};

$hexParser = HexColor::getParser(); // Validates Hex format
$hslParser = HslColor::getParser(); // Validates HSL format
$rgbParser = RgbColor::getParser(); // Validates RGB format
$oklchParser = OklchColor::getParser(); // Validates OKLCH format

Color conversion

Colority allows you to convert a Color object to any other Color object of the desired format.

$hexColor = colority()->fromHex('#51B389');

/** @var HexColor $hexColor */
$hexColor = $hexColor->toHex();

/** @var RgbColor $rgbColor */
$rgbColor = $hexColor->toRgb();

/** @var HslColor $hslColor */
$hslColor = $hexColor->toHsl();

/** @var OklchColor $oklchColor */
$oklchColor = $hexColor->toOklch();

Note: Conversions between RGB, HSL, and Hex are lossless. Conversions involving OKLCH may be lossy (due to gamut clipping-OKLCH can represent colors outside the sRGB gamut that must be clipped to the nearest displayable color).

CSS-ready string with measure units

HslColor and OklchColor implement the HasMeasureUnits interface, which exposes a string with the conventional unit suffixes for the format.

$hsl = colority()->fromHsl([180, 50, 50]);
$hsl->getValueColor(); // "hsl(180,50,50)"
$hsl->getValueColorWithMeasureUnits();  // "hsl(180deg,50%,50%)"

$oklch = colority()->fromOklch([0.5, 0.1, 180]);
$oklch->getValueColor(); // "oklch(0.5 0.1 180)"
$oklch->getValueColorWithMeasureUnits();  // "oklch(50% 25% 180deg)"

For OKLCH, L is rendered as a percentage of 1, C as a percentage of the 0.4 reference (so 0.1 becomes 25%), and H with the deg suffix.

Semantic palette

Colority ships with eight semantic color slots primary, secondary, success, danger, warning, info, light, dark, preloaded with default values and overridable per slot, in bulk, or all at once.

// Defaults are available out of the box.
colority()->primary(); // HexColor #5B8DEF
colority()->success(); // HexColor #4BD396
colority()->danger(); // HexColor #F5707A

Override individual slots

Each slot has a dedicated setter. Both Color instances and hex strings are accepted.

colority()->setPrimary('#FF6347');
colority()->setDanger(colority()->fromOklch('oklch(0.6 0.2 30)'));

colority()->primary()->getValueColor(); // "#FF6347"

Bulk configuration

configure() overrides multiple slots at once and preserves the ones not provided.

colority()->configure([
    'primary' => '#FF6347',
    'success' => '#00CED1',
    'warning' => colority()->fromHsl('hsl(40, 90%, 60%)'),
]);

Custom slot names

Beyond the eight semantic names, you can register and read arbitrary slots through the generic accessors.

colority()->setColor('brand', '#0D6EFD');
colority()->setColor('accent', '#FF00AA');

colority()->color('brand');   // ?Color
colority()->color('unknown'); // null

Reverting to defaults

resetPalette() discards every override and restores the eight defaults. Useful between tests.

colority()->resetPalette();

The eight defaults Colority ships with:

Slot	Hex
`primary`	`#5B8DEF`
`secondary`	`#A1A8B3`
`success`	`#4BD396`
`danger`	`#F5707A`
`warning`	`#F9C851`
`info`	`#3AC9D6`
`light`	`#F4F6F8`
`dark`	`#1F2937`

Build a palette from a brand color

buildPalette() derives a coherent palette from a single brand color. The algorithm, applied in HSL space:

Slot	Formula
`primary`	the brand color, untouched
`secondary`	`HSL(brand.H + 180°, max(10, brand.S × 0.4), brand.L)`, complementary hue with saturation reduced to 40% (floored at 10 so it never goes pure grey). When the brand itself is near-grey (`S < 5`), the default secondary is used instead.
`light`	`brand.lighter(40)`, lightness + 40 (clamped to 100)
`dark`	`brand.darker(40)`, lightness - 40 (clamped to 0)

The semantic slots (success, danger, warning, info) keep their library defaults so they remain visually recognizable across brands. Any custom slots previously registered via setColor() are dropped, buildPalette() rebuilds the whole palette.

colority()->buildPalette('#FF6347');

colority()->primary(); // #FF6347 (your brand)
colority()->secondary(); // complementary hue, desaturated
colority()->light(); // brand brightened
colority()->dark(); // brand darkened

Color utilities

Color Adjustments

Adjust the brightness (lightness) and saturation of any color. All methods return an HslColor that you can convert as needed.

$color = colority()->fromHex('#3498db');

// Adjust brightness
$color->lighter(); // 10% brighter (default)
$color->lighter(20); // 20% brighter
$color->darker(); // 10% darker (default)
$color->darker(15); // 15% darker

// Adjust saturation
$color->saturate(); // 10% more saturated
$color->desaturate(25); // 25% less saturated

// Direct adjustment (positive or negative)
$color->adjustLightness(30); // +30% lightness
$color->adjustSaturation(-20); // -20% saturation

// Convert result to any format
$color->lighter()->toHex(); // Get as HexColor
$color->darker()->toRgb(); // Get as RgbColor

getImageMostCommonColor

Returns the single most common color in an image based on pixel frequency.

/** @var RgbColor $mostCommon */
$mostCommon = colority()->getImageMostCommonColor(__DIR__.'/photo.png');

echo $mostCommon->toHex()->getValueColor(); // e.g., "#3A7B5C"

getImageColors

It allows you to obtain the colors detected in an image. As the first argument, the path to the image must be provided.

It has an optional second parameter (default is 5) that specifies the number of colors to be returned.

/** @var array<RgbColor> $imageColors */
$imageColors = colority()->getImageColors(
    imagePath: __DIR__.'/image-colors.png',
    desiredNumColors: 10
);

getImageDominantColors

Extracts the most dominant colors based on pixel frequency, returning detailed metadata for each color.

use Tomloprod\Colority\Support\Dtos\ImageColorFrequency;

/** @var array<ImageColorFrequency> $dominantColors */
$dominantColors = colority()->getImageDominantColors(
    imagePath: __DIR__.'/photo.png',
    desiredNumColors: 5
);

foreach ($dominantColors as $frequency) {
    $frequency->color; // RgbColor object
    $frequency->percentage; // e.g., 45.2
    $frequency->pixelCount; // e.g., 4520
}

Optional parameter:

similarityThreshold (default: 50): Minimum RGB distance (0-441) to consider colors as distinct. Higher values filter out more similar colors.

// More aggressive filtering (groups similar shades)
$dominantColors = colority()->getImageDominantColors(
    imagePath: __DIR__.'/photo.png',
    desiredNumColors: 5,
    similarityThreshold: 80
);

textToColor

Generate a deterministic color based on any string. Same input always produces the same color.

/**
 * Basic usage - generates a unique color from text
 * 
 * @var HslColor $hslColor
 */
$hslColor = colority()->textToColor("Hi, I'm Tomás");

Constrain to a color range:

Pass a fromColor to generate only colors within the same hue range.

/**
 * Only grayscale colors will be generated
 * 
 * @var HslColor $hslColor
 */
$hslColor = colority()->textToColor(
    "Hi, I'm Tomás", 
    colority()->fromHex('#CCC')
);

Interpolate between two colors:

Pass both fromColor and toColor to perform linear interpolation. The same text always maps to the same position in the gradient.

/**
 * Color will fall somewhere between light green and dark teal
 * 
 * @var HslColor $hslColor
 */
$hslColor = colority()->textToColor(
    "Hi, I'm Tomás",
    colority()->fromHex('#85d5a4'), // Start: Light green
    colority()->fromHex('#165a59')  // End: Dark teal
);

getSimilarColor

Generate a random color similar to a given color (within the same color palette).

$hexColor = colority()->fromHex('#51B389');

/**
 * Get a random similar color (default variation ranges)
 * 
 * @var HexColor $similarHexColor
 */
$similarHexColor = colority()->getSimilarColor($hexColor);

// Fine-tune the similarity with custom ranges
$similarHexColor = colority()->getSimilarColor(
    $hexColor,
    hueRange: 20, // +- 20 degrees on color wheel
    saturationRange: 5, // +- 5% saturation
    lightnessRange: 5 // +- 5% lightness
);

random

Generates a completely random color.

/**
 * Returns a random HSL color
 * 
 * @var HslColor $randomColor
 */
$randomColor = colority()->random();

// And, if you want, convert to your preferred format
$hexRandom = $randomColor->toHex();

gradient

Generates a smooth gradient of colors between multiple color stops.

/**
 * Create a 10-step gradient from red -> green -> blue
 * 
 * @var array<HexColor> $gradient
 */
$gradient = colority()->gradient(
    colors: [
        colority()->fromHex('#ff0000'), // Red
        colority()->fromHex('#00ff00'), // Green
        colority()->fromHex('#0000ff') // Blue
    ],
    steps: 10
);

This returns an array of 10 HexColor objects.

Ways of using Colority

You can use Colority either with the helper function colority():

use Tomloprod\Colority\Colors\HexColor;

/**
 * Using the helper function
 * 
 * @var HexColor $hexColor
 */
$hexColor = colority()->fromHex('#CCC');

or by directly invoking the static methods of the Colority facade:

use Tomloprod\Colority\Support\Facades\Colority;
use Tomloprod\Colority\Colors\HexColor;

/**
 * Using the facade directly
 * 
 * @var HexColor $hexColor
 */
$hexColor = Colority::fromHex('#CCC');

Both approaches are equivalent.

API Reference

Colority provides a comprehensive API through its facade and color classes.

View complete API documentation

Installation and Requirements

Requires PHP 8.2+

You may use Composer to install Colority into your PHP project:

composer require tomloprod/colority

Upgrade from 1.x to 2.0

Most consumers (those using colority() or the Colority facade) do not need to change anything. The breaking changes affect only callers who reach into the internal parser API:

Tomloprod\Colority\Contracts\ValueColorParser::parse() now returns array<ColorComponent> instead of string. Direct callers must adapt to the new return shape.
ColorityManager::fromHex() and Colority::fromHex() accept string|array<int|float>. Existing string usage is unchanged; the array form is additive.
colority()->parse() now intercepts CSS gradient strings and returns the dominant stop color. Code that relied on parse() returning null for gradients should use the GradientResolver::isGradient() static check.
getMatchingForegroundColor() defaults targetScore to ContrastRatioScore::Excellent (7:1, WCAG AAA) instead of ContrastRatioScore::Good (4.5:1, WCAG AA). Pass the enum explicitly to opt back into the previous default.

Contributing

Contributions are welcome, and are accepted via pull requests. Please review these guidelines before submitting any pull requests.

Colority was created by Tomás López and open-sourced under the MIT license.

tomloprod / colority

Maintainers

Package info

Fund package maintenance!

Statistics

Security

README

About Colority

Features

Getting Started

Color Utilities

Using Colority

Documentation & Resources

Getting Started

Instantiating Color objects

Gradients

Contrast ratio (WCAG 2.0 standard)

getBestForegroundColor

getContrastRatio

getMatchingForegroundColor

ContrastRatioScore Enum

Color validation

Color conversion

CSS-ready string with measure units

Semantic palette

Override individual slots

Bulk configuration

Custom slot names

Reverting to defaults

Build a palette from a brand color

Color utilities

Color Adjustments

getImageMostCommonColor

getImageColors

getImageDominantColors

textToColor

getSimilarColor

random

gradient

Ways of using Colority

API Reference

Installation and Requirements

Requires PHP 8.2+

Upgrade from 1.x to 2.0

Contributing