Colority
Colority it's a PHP library that allows you to: transform and validate colors, obtain the best contrast color (using contrast ratio from WCAG 2.0 standard), extract colors from images and more.
Install / Use
/learn @tomloprod/ColorityREADME
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
-
- Create RGB, HSL, Hex, and OKLCH color objects from strings or arrays
- Auto-detect color format with
parse()method
-
- 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
-
- Parse and validate color strings with type-specific parsers
-
- Convert between RGB, HSL, Hexadecimal, and OKLCH formats
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
- Helper function
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 - Multiple input formats supported
*
* @var RgbColor $rgbColor
*/
$rgbColor = colority()->fromRgb('rgb(255,255,255)');
$rgbColor = colority()->fromRgb('255,255,255');
$rgbColor = colority()->fromRgb([255, 255, 255]);
/**
* Hexadecimal format - With or without hash, shorthand supported
*
* @var HexColor $hexColor
*/
$hexColor = colority()->fromHex('#51B389');
$hexColor = colority()->fromHex('51B389');
$hexColor = colority()->fromHex('#ABC');
/**
* HSL format - Multiple input formats supported
*
* @var HslColor $hslColor
*/
$hslColor = colority()->fromHsl('hsl(168.31deg, 49.58%, 46.67%)');
$hslColor = colority()->fromHsl('168.31, 49.58, 46.67');
$hslColor = colority()->fromHsl([168.31, 49.58, 46.67]);
/**
* OKLCH format - Multiple input formats supported
*
* @var OklchColor $oklchColor
*/
$oklchColor = colority()->fromOklch('oklch(0.70 0.11 163)');
$oklchColor = colority()->fromOklch('0.70 0.11 163');
$oklchColor = colority()->fromOklch([0.70, 0.11, 163]);
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)');
// Always returns null for invalid formats
$invalid = colority()->parse('not-a-color'); // 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');
// AA level by default
$foregroundColor = $backgroundColor->getMatchingForegroundColor();
// AAA level for enhanced contrast
$foregroundColor = $backgroundColor->getMatchingForegroundColor(ContrastRatioScore::Excellent);
// 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::Good): 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: 7:1 ratio (WCAG AAA for normal text)ContrastRatioScore::Good(default): 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: $
