A simple Color object for PHP packages and applications. 🎨

This package can be installed via Composer:

composer require ryangjchandler/color

This package provides a single RyanChandler\Color\Color object.

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);

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.

You can generate a random color using the Color::random() method.

$random = Color::random();

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

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

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)"

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();

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).

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.

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