felixdorn / php-color
A simple library to work and smartly generate colors in PHP
Requires
- php: ^8.3
- savvot/random: ^v0.3.0
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3
- pestphp/pest: ^v2.34
- phpstan/phpstan: ^1
- spatie/pest-plugin-snapshots: ^2.1
- symfony/var-dumper: ^7
This package is auto-updated.
Last update: 2024-10-17 17:56:09 UTC
README
Installation
Requires PHP 8.3+
You can install the package via composer:
composer require felixdorn/php-color
Features
- 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
TOC
Usage
Generating nice looking 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.
Working with the HSLA object.
You may be getting a color from somewhere which is not HSLA, you can convert them:
From RGB to HSLA
\Felix\PHPColor\Hsla::fromRGB(255, 0, 0);
From Hex to HSLA
\Felix\PHPColor\Hsla::fromHex("#FF0000") \Felix\PHPColor\Hsla::fromHex("FF0000")
From scratch
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);
Luminance
As in https://www.w3.org/TR/2008/REC-WCAG20-20081211/#relativeluminancedef.
$color->luminance(); // 0.0 - 1.0
Contrast
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
Testing
composer test
PHP Color was created by Félix Dorn under the MIT license.