ryangjchandler / color
A simple Color object for PHP packages and applications.
Fund package maintenance!
ryangjchandler
Requires
- php: ^7.4|^8.0
Requires (Dev)
- ryangjchandler/puny: ^0.1.0
README
A simple Color object for PHP packages and applications. 🎨
Installation
This package can be installed via Composer:
composer require ryangjchandler/color
Usage
This package provides a single RyanChandler\Color\Color
object.
Creating a color
To create a color, instantiate a new RyanChandler\Color\Color
object:
use RyanChandler\Color\Color; $color = new Color(255, 255, 255);
The constructor accepts three optional arguments. The red, green and blue decimal representations of your color.
If you prefer using static constructors you can use the Color::new()
method, Ã la Rust.
$color = Color::new(255, 255, 255);
Creating a color from a hex
If you wish to create a color using the hex representation, you can use the Color::hex()
method.
$color = Color::hex('#ffffff');
This will convert your hex representation into the RGB equivalent.
The #
is not compulsory. It will only be removed if the string provided starts with it.
It's worth noting that any alpha values specified on the hex value will be stripped since the string is clamped to a length of 6. This is something that might be supported in a future version.
Creating a color from HSL values
You can also use hue, saturation and lightness values to create a color using the Color::hsl()
method.
$color = Color::hsl(0, 0, 100);
This will convert your HSL values into the RGB equivalent.
You can also define the alpha as an optional fourth argument
Color::hsl(0, 0, 100, 0.5)
Generating a random color
You can generate a random color using the Color::random()
method.
$random = Color::random();
Accessing the red, green and blue values
Each color value can be accessed using a public property on the Color
object.
$color = Color::new(255, 255, 255); $color->red; // 255 $color->green; // 255 $color->blue; // 255
Getting the hex representation
If you wish to get the hex equivalent of your color, you can use the Color::toHex()
method.
Color::new(255, 255, 255)->toHex(); // #ffffff
Getting the HSL representation
If you wish to get the HSL equivalent of your color as an array, you can use the Color::toHsl()
method.
[$h, $s, $l] = Color::new(255, 255, 255)->toHsl(); // [0, 0, 100]
Getting the string representation
By default, the Color::toString()
method returns a tuple-like string.
Color::new(255, 255, 255)->toString(); // "(255, 255, 255)"
You can also use the Color::toString()
method to retrieve the hex representation.
Color::new(255, 255, 255)->toString(true); // #ffffff
Or use PHP's typecasting to get a string instead.
(string) Color::new(255, 255, 255); // "(255, 255, 255)"
Getting an array
You can use the Color::toArray()
method to get all three color values in an ordered list.
Color::new(255, 255, 255)->toArray(); // [255, 255, 255]
The array does not use string-keys, so you can unpack the array into separate variables too.
[$r, $g, $b] = Color::new(255, 255, 255)->toArray();
Finding the distance between 2 colors
If you need to calculate the distance between 2 colors, you can use the Color::distanceBetween()
method.
$one = Color::new(0, 0, 220); $two = Color::new(255, 0, 220); Color::distanceBetween($one, $two); // 65_025
The return value is the distance between the 2 colors, squared. Generally speaking, this number will be more readable and recognisable than the radical (result of the square root).
Using an existing Color
If you already have a Color
object, you can use the Color::distanceTo()
method as well.
$one = Color::new(0, 0, 220); $two = Color::new(255, 0, 220); $one->distanceTo($two); // 65_025
It is worth noting that the distance calculations and
Color
objects do not support alpha-based colors. This is potentially something that will be added in the future.
Comparing colors
You can compare two colors using the Color::bothEqual()
method.
$one = Color::rgb('#aaa'); $two = Color::rgb('#aaa'); $three = Color::rgb('#ccc'); Color::bothEqual($one, $two); // true Color::bothEqual($one, $three); // false
You can also compare one color to another using the equals
method on one of the colors.
$one = Color::rgb('#aaa'); $two = Color::rgb('#aaa'); $three = Color::rgb('#ccc'); $one->equals($two); // true $one->equals($three); // false