Nether\Dye

Simple colour parsing and manipulation library. Lightweight, dependency free. Able to automatically parse common colour strings. No messing around with different classes for the various supported formats.

Supported String Formats

• RGB Hex String #FF0000
• RGBA Hex String #FF0000FF
• RGB CSS String rgb(255, 0, 0)
• RGBA CSS String rgba(255, 0, 0, 1.0)
• HSL CSS String hsl(255, 0, 0)
• HSLA CSS String hsla(255, 0, 0, 1.0)

use Nether\Dye\Colour;

$Red = new Colour('#FF0000');
// ...

Requirements

• PHP 8.1+

Classes

Nether\Dye\Colour

Basic colour object where modifications will be mixed into the current object and all relevant properties recalculated to remain current.

Nether\Dye\ColourImmutable

Same API as Colour except all methods that would have modified the current dataset return new objects leaving the original unaltered.

Factory API

Colour::From(string|RGBA|HSLA $Input): static

• Parse input colour from strings fitting known formats.

Colour::FromIntRGB(int $RGB): static

• Parse input colour from 24bit RGB integer.

Colour::FromIntRGBA(int $RGB): static

• Parse input colour from 32bit RGBA integer.

Colour::FromRGB(int $R, int $G, int $B, int|float $A=255): static

• Parse RGB by component.

Colour::FromHSL(int $H, float $S, float $L, float $A=1.0): static

• Parse HSL by component.

Manipulation API

Setting Components

$Colour->SetRGB(?int $R, ?int $G, ?int $B, ?int $A): self

• Set any of the RGB[A] components that are specified and not null.

$Colour->SetHSL(?int $H, ?float $S, ?float $L, ?float $A): self

• Set any of the HSL[A] components that are specified and not null.

Shooping Around.

$Colour->HueRotate(int $Degrees): self

• Hue rotate a colour the specified number of degrees.

$Colour->HueShift(float $Percent): self

• Hue rotate a colour shifted over by the specified percentage.

$Colour->Saturation(float $Mult): self

• Modify the saturation of the colour by the specified multiplier.

$Colour->Saturate(float $Str): self

• Increase the saturation by the specified strength.

$Colour->Desaturate(float $Str): self

• Reduce the saturation by the specified strength.

$Colour->Lightness(float $Mult): self

• Modify the lightness of the colour by the specified multiplier.

$Colour->Lighten(float $Str): self

• Increase the lightness by the specified strength.

$Colour->Darken(float $Str): self

• Reduce the lightness by the specified strength.

$Colour->Mix(Colour $With, float $Str=0.5): self

• Blend the specified colour with this one at the specified strength.

Query API

$Colour->IsBright(): bool

• Returns TRUE if the colour would be perceived as bright.

$Colour->IsDark(): bool

• Returns TRUE if the colour would be perceived as dark.

Printing API

$Colour->ToHexRGB(): string

• Return a hex encoded string like #FF0000

$Colour->ToHexRGBA(): string

• Return a hex encoded string like #FF0000FF

$Colour->ToStyleRGB(): string

• Return a hex encoded string like rgb(255, 0, 0)

$Colour->ToStyleRGBA(): string

• Return a hex encoded string like rgb(255, 0, 0, 1.00)

$Colour->ToStyleHSL(): string

• Return a hex encoded string like hsl(0, 1.00, 0.50)

$Colour->ToStyleHSLA(): string

• Return a hex encoded string like hsl(0, 1.00, 0.50, 1.0)

Format Component API

Note: all manipulations should be done via the methods on the root colour object to keep the various properties in sync. The SetRGB() and SetHSL() methods accept optional labeled arguments and array splattering.

$Colour->RGB->ToArray(bool $Indexed=TRUE): array

• Return an indexed array or a list of RGB data.

$Colour->RGB->R(): int

• Return the Red component of the RGB data.

$Colour->RGB->G(): int

• Return the Green component of the RGB data.

$Colour->RGB->B(): int

• Return the Blue component of the RGB data.

$Colour->RGB->A(): int

• Return the Alpha component of the RGB data.

$Colour->HSL->ToArray(bool $Indexed=TRUE): array

• Return an indexed array or a list of HSL data.

$Colour->HSL->H(): int

• Return the Hue component of the HSL data.

$Colour->HSL->S(): float

• Return the Saturation component of the HSL data.

$Colour->HSL->L(): float

• Return the Lightness component of the HSL data.

$Colour->HSL->A(): float

• Return the Alpha component of the HSL data.

Examples

Instantiation Choices

use Nether\Dye\Colour;

// long form
$C1 = new Colour;
$C1->Import('#aabbcc');

// condensed form
$C2 = new Colour('#aabbcc');

// factory form
$C3 = Colour::From('#aabbcc');

Immutables

use Nether\Dye\ColourImmutable;

$R = new ColourImmutable('#FF0000');
$G = $R->HueRotate(120);
$B = $G->HueRotate(120);

printf(
	'R: %s, G: %s, B: %s%s',
	$R->ToHexRGB(),
	$G->ToHexRGB(),
	$B->ToHexRGB(),
	PHP_EOL
);

// R: #FF0000, G: #00FF00, B: #0000FF

Testing

$ phpunit

• Run the unit test suite.

$ php -S localhost:8080 -t wwwtest

• Run a test page to see some things.