ryangjchandler/color

A simple Color object for PHP packages and applications.

v1.1.0 2021-03-19 10:06 UTC

Requires

• php: ^7.4|^8.0

Requires (Dev)

• ryangjchandler/puny: ^0.1.0

MIT

• Ryan Chandler

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