Requires PHP 8.3+
You can install the package via composer:
composer require felixdorn/php-color
- Support HSLA (and HSL)&, HEX, RGBA (and RGB)
- Generate a color for a given seed (like a user email)
- Darken, lighten the color.
- Compute the luminance, lightness, darkness
- Check the contrast of two colors
You can generate colors on the fly:
use Felix\PHPColor\Generator;
Generator::one();
Generator::many(n: 10)
Generator::manyLazily(n: 10_000)
Important: the colors generated are generate with the following defaults
- Hue: [0, 360] (all hues)
- Saturation: [50, 90] (out of [0, 100])
- Lightness [50, 70] (out of [0, 100])
- Alpha [100, 100] (out of [0, 100])
This generates bright, saturated colors.
You may change the defaults for all generated colors used by the Generator
.
use Felix\PHPColor\Generator;
Generator::withDefaults(
hue: [100, 200],
saturation: 50,
lightness: [40, 60],
alpha: [100, 100]
);
Or some of the defaults
Generator::withDefaults(
hue: [120, 140] // just restrict the hue but keep the saturation and lightness settings
);
You may force the generator to use a certain seed:
$avatarColor = Generator::one(seed: $email); // will always return the same color for the given seed.
This also works for Generator::many
and Generator::manyLazily
.
You may override the default hue, saturation, and lightness ranges used to generate a color:
use Felix\PHPColor\Generator;
$avatarColor = Generator::one(
hue: [100, 200],
lightness: [40, 80]
);
$avatarColor = Generator::many(
hue: null, // use global defaults
saturation: [100, 100]
lightness: [40, 80]
);
$avatarColor = Generator::manyLazily(
lightness: [50, 60]
)
Or specify a single number instead of a range:
use Felix\PHPColor\Generator;
$avatarColor = Generator::one(hue: [0, 360], lightness: 50, saturation: 100)
The generator returns Hsla
objects. Let us see how they work.
You may be getting a color from somewhere which is not HSLA, you can convert them:
\Felix\PHPColor\Hsla::fromRGB(255, 0, 0);
\Felix\PHPColor\Hsla::fromHex("#FF0000")
\Felix\PHPColor\Hsla::fromHex("FF0000")
use Felix\PHPColor\Hsla;
$color = new Hsla(100, 20, 20);
$color = new Hsla(100, .2, .2); // automatically normalized to 0-100
Hsla::boundedRandom([0, 360], [0,100], [0,100], [0, 100], $seed)
Hsla::random($seed);
You may convert your HSLA color back to hex, RGB, HSLA...
$color->toHex(); // #000000
$color->toRgba(); // rgb(0, 0, 0)
$color->toHsla(); // hsl(0, 0, 0)
You may access the properties of the color:
$color->hue; # between 0-360
$color->saturation; # between 0-100
$color->lightness; # between 0-100
$color->alpha; # between 0-100
$color->setHue(...)->setSaturation(...)->setLightness(...)->setAlpha(...); // modifies the color
$color->withHue(...) // returns a new instance
$color->withSaturation(...); // returns a new instance
$color->withLightness(...); // returns a new instance
$color->withAlpha(...); // returns a new instance
// If you chain more than one with...(), use clone() + set...() instead:
$color->clone()
->setHue(...)
->setSaturation(...)
->setLightness()
->setAlpha();
$color->colorChannels(); // returns [r, g, b]
$color->red(); // 0-255
$color->green(); // 0-255
$color->blue(); // 0-255
And check the brightness of a color:
$color->isDark();
$color->isBright();
You may also specify a threshold, a number between 0 (darkest) and 100 (brightest):
$color->isDark(threshold: 5);
You may darken or lighten a given color:
// Returns a new instance of the color
$color->darken($percentage = 15);
$color->lighten($percentage = 15);
As in https://www.w3.org/TR/2008/REC-WCAG20-20081211/#relativeluminancedef.
$color->luminance(); // 0.0 - 1.0
As in https://www.w3.org/TR/2008/REC-WCAG20-20081211/#contrast-ratiodef. Very useful for accessibility testing. Returns a value between 1 and 21. Usually, this is written as 1:1 or 21:1. This returns "n:1".
$color->contrast($otherColor); // 1 - 21
composer test
PHP Color was created by Félix Dorn under the MIT license.