spatie/color

A little library to handle color conversions

1.6.2 2024-12-09 16:20 UTC

Requires

• php: ^7.3|^8.0

Requires (Dev)

• pestphp/pest: ^1.22
• phpunit/phpunit: ^6.5||^9.0

MIT

• Sebastian De Deyne

• conversion
• color
• rgb
• spatie

README

A little library to handle color conversions and comparisons. Currently, supports CSS names, rgb, rgba, hex, hsl, hsla, CIELab, and xyz color formats as well as CIE76, CIE94, and CIEDE2000 color comparison algorithms.

$named = Named::fromString('peru'); // case-insensitive

echo $named->red(); // 205
echo $named->green(); // 133
echo $named->blue(); // 63

echo $named->toHex(); // #cd853f

$rgb = Rgb::fromString('rgb(55,155,255)');

echo $rgb->red(); // 55
echo $rgb->green(); // 155
echo $rgb->blue(); // 255

echo $rgb; // rgb(55,155,255)

$rgba = $rgb->toRgba(); // `Spatie\Color\Rgba`
$rgba->alpha(); // 1
echo $rgba; // rgba(55,155,255,1)

$hex = $rgb->toHex(); // `Spatie\Color\Hex`
$rgba->alpha(); // ff
echo $hex; // #379bff

$cmyk = $rgb->toCmyk(); // `Spatie\Color\Cmyk`
echo $cmyk; // cmyk(78,39,0,0)

$hsl = $rgb->toHsl(); // `Spatie\Color\Hsl`
echo $hsl; // hsl(210,100%,100%)

$hsb = $rgb->toHsb(); // `Spatie\Color\Hsb`
echo $hsb; // hsl(210,78.4%,100%)

$lab = $rgb->toCIELab();
echo $lab; // CIELab(62.91,5.34,-57.73)

$xyz = $rgb->toXyz();
echo $xyz; // xyz(31.3469,31.4749,99.0308)

$hex2 = Hex::fromString('#2d78c8');

$ratio = Contrast::ratio(Hex::fromString('#f0fff0'), Hex::fromString('#191970')); 
echo $ratio; // 15.0

$cie76_distance = Distance::CIE76($rgb, $hex2);
$cie76_distance = Distance::CIE76('rgba(55,155,255,1)', '#2d78c8'); // Outputs the same thing, Factory is built-in to all comparison functions
echo $cie76_distance; // 55.89468042667388

$cie94_distance = Distance::CIE94($rgb, $hex2);
echo $cie94_distance; // 13.49091942790753

$cie94_textiles_distance = Distance::CIE94($rgb, $hex2, 1); // Third parameter optionally sets the application type (0 = Graphic Arts [Default], 1 = Textiles)
echo $cie94_textiles_distance; // 7.0926538068477

$ciede2000_distance = Distance::CIEDE2000($rgb, $hex2);
echo $ciede2000_distance; // 12.711957696300898

Support us

We invest a lot of resources into creating best in class open source packages. You can support us by buying one of our paid products.

We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on our contact page. We publish all received postcards on our virtual postcard wall.

Installation

You can install the package via composer:

composer require spatie/color

Usage

The Color package contains a separate class per color format, which each implement a Color interface.

There are seven classes which implement the Color interface:

• CIELab
• Cmyk
• Hex
• Hsb
• Hsl
• Hsla
• Rgb
• Rgba
• Xyz

interface Spatie\Color\Color

fromString(): Color

Parses a color string and returns a Color implementation, depending on the format of the input string.

Named::fromString('blue');
Hex::fromString('#000000');
Rgba::fromString('rgba(255, 255, 255, 1)');
Hsla::fromString('hsla(360, 100%, 100%, 1)');

Throws an InvalidColorValue exception if the string can't be parsed.

Rgb, Rgba, Hsl and Hsla strings are allowed to have spaces. rgb(0,0,0) is just as valid as rgb(0, 0, 0).

red(): int|string

Return the value of the red color channel.

Hex::fromString('#ff0000')->red(); // 'ff'
Rgb::fromString('rgb(255, 0, 0)')->red(); // 255

green(): int|string

Return the value of the green color channel.

Hex::fromString('#00ff00')->green(); // 'ff'
Rgb::fromString('rgb(0, 255, 0)')->green(); // 255

blue(): int|string

Return the value of the blue color channel.

Hex::fromString('#0000ff')->blue(); // 'ff'
Rgb::fromString('rgb(0, 0, 255)')->blue(); // 255

toCmyk(): Cmyk

Convert a color to a Cmyk color.

Rgb::fromString('rgb(0, 0, 255)')->toCmyk();
// `Cmyk` instance; 'cmyk(100,100,0,0)'

toHex(): Hex

Convert a color to a Hex color.

Rgb::fromString('rgb(0, 0, 255)')->toHex();
// `Hex` instance; '#0000ff'

When coming from a color format that doesn't support opacity, it can be added by passing it to the $alpha parameter.

toHsb(): Hsb

Convert a color to a Hsb color.

Rgb::fromString('rgb(0, 0, 255)')->toHsb();
// `Hsl` instance; 'hsb(240, 100%, 100%)'

toHsl(): Hsl

Convert a color to a Hsl color.

Rgb::fromString('rgb(0, 0, 255)')->toHsl();
// `Hsl` instance; 'hsl(240, 100%, 50%)'

When coming from a color format that supports opacity, the opacity will simply be omitted.

Rgba::fromString('rgba(0, 0, 255, .5)')->toHsl();
// `Hsl` instance; 'hsl(240, 100%, 50%)'

toHsla(float $alpha = 1): Hsla

Convert a color to a Hsla color.

Rgb::fromString('rgb(0, 0, 255)')->toHsla();
// `Hsla` instance; 'hsla(240, 100%, 50%, 1.0)'

When coming from a color format that doesn't support opacity, it can be added by passing it to the $alpha parameter.

Rgb::fromString('rgb(0, 0, 255)')->toHsla(.5);
// `Hsla` instance; 'hsla(240, 100%, 50%, 0.5)'

toRgb(): Rgb

Convert a color to an Rgb color.

Hex::fromString('#0000ff')->toRgb();
// `Rgb` instance; 'rgb(0, 0, 255)'

When coming from a color format that supports opacity, the opacity will simply be omitted.

Rgba::fromString('rgb(0, 0, 255, .5)')->toRgb();
// `Rgb` instance; 'rgb(0, 0, 255)'

toRgba(float $alpha = 1): Rgba

Convert a color to a Rgba color.

Rgb::fromString('rgb(0, 0, 255)')->toRgba();
// `Rgba` instance; 'rgba(0, 0, 255, 1)'

When coming from a color format that doesn't support opacity, it can be added by passing it to the $alpha parameter.

Rgba::fromString('rgb(0, 0, 255)')->toRgba(.5);
// `Rgba` instance; 'rgba(0, 0, 255, .5)'

__toString(): string

Cast the color to a string.

(string) Rgb::fromString('rgb(0, 0, 255)'); // 'rgb(0,0,255)'
(string) Rgba::fromString('rgb(0, 0, 255, .5)'); // 'rgb(0,0,255,0.5)'
(string) Hex::fromString('#0000ff'); // '#0000ff'
(string) Hsl::fromString('hsl(240, 100%, 50%)'); // 'hsl(240, 100%, 50%)'
(string) Hsla::fromString('hsla(240, 100%, 50%, 1.0)'); // 'hsla(240, 100%, 50%, 1.0)'

Factory::fromString(): Color

With the Factory class, you can create a color instance from any string (it does an educated guess under the hood). If the string isn't a valid color string in any format, it throws an InvalidColorValue exception.

Factory::fromString('rgb(0, 0, 255)'); // `Rgb` instance
Factory::fromString('blue'); // `Named` instance
Factory::fromString('#0000ff'); // `Hex` instance
Factory::fromString('hsl(240, 100%, 50%)'); // `Hsl` instance
Factory::fromString('Hello world!'); // `InvalidColorValue` exception

Changelog

Please see CHANGELOG for more information what has changed recently.

Testing

$ composer test

Contributing

Please see CONTRIBUTING for details.

Security

If you've found a bug regarding security please mail [e-mail] instead of using the issue tracker.

Credits

• Sebastian De Deyne
• All Contributors

About Spatie

Spatie is a webdesign agency based in Antwerp, Belgium. You'll find an overview of all our open source projects on our website.

License

The MIT License (MIT). Please see License File for more information.