Colour
Reference for the Colour module: RGBA colour data types with float channels in the 0.0-1.0 range, named presets, component arithmetic, blending and interpolation, and conversion to and from CSS hex and ANSI.
This page is a pure reference. For how the framework fits together, see the Guide.
Colour- RGBA helpers, presets and hex conversion built on ColourTransparentData.ColourBlend- blend two colours by linear, square or square-root curves.ColourOpaqueData- an opaque colour: red, green and blue channels, no alpha.ColourRGBA- static helpers, presets and operations for RGBA colours.ColourTransparentData- a colour with red, green, blue and alpha channels.
Colour
RGBA helpers and presets with float channels in the 0.0-1.0 range. Preset functions return a ColourTransparentData; arithmetic, blending and conversion functions operate on them. Hex functions parse and emit CSS hex strings in gamma sRGB space.
Add
Colour::Add(ColourTransparentData $colour1, ColourTransparentData $colour2): ColourTransparentData
Add two colours channel by channel, including alpha.
| Name | Type | Description |
|---|---|---|
$colour1 | ColourTransparentData | The first colour. |
$colour2 | ColourTransparentData | The second colour. |
Returns ColourTransparentData The channel-wise sum.
Black
Colour::Black(): ColourTransparentData
The preset black colour (0, 0, 0, 1).
Returns ColourTransparentData Black.
Blue
Colour::Blue(): ColourTransparentData
The preset blue colour (0, 0, 1, 1).
Returns ColourTransparentData Blue.
Brightness
Colour::Brightness(string $hexColour): float
Relative luminance (sRGB) for a CSS hex colour, in the 0.0-1.0 range. An unknown format returns 0.5.
| Name | Type | Description |
|---|---|---|
$hexColour | string | A CSS hex colour. |
Returns float The relative luminance, or 0.5 when unparseable.
Brown
Colour::Brown(): ColourTransparentData
The preset brown colour (0.5, 0.25, 0, 1).
Returns ColourTransparentData Brown.
ByteValue
Colour::ByteValue(float $value): int
Convert a float channel value (0.0-1.0) to a byte value (0-255).
| Name | Type | Description |
|---|---|---|
$value | float | A channel value in the 0.0-1.0 range. |
Returns int The byte value, 0 to 255.
Clamp
Colour::Clamp(ColourTransparentData $colour, ColourTransparentData $minColour, ColourTransparentData $maxColour): ColourTransparentData
Clamp each channel of a colour between the matching channels of a minimum and maximum colour, including alpha.
| Name | Type | Description |
|---|---|---|
$colour | ColourTransparentData | The colour to clamp. |
$minColour | ColourTransparentData | The per-channel minimum. |
$maxColour | ColourTransparentData | The per-channel maximum. |
Returns ColourTransparentData The clamped colour.
Cyan
Colour::Cyan(): ColourTransparentData
The preset cyan colour (1, 0, 1, 1).
Returns ColourTransparentData Cyan.
Darken
Colour::Darken(ColourTransparentData $colour1, float $proportion): ColourTransparentData
Darken a colour by linearly blending it toward black by the given proportion.
| Name | Type | Description |
|---|---|---|
$colour1 | ColourTransparentData | The colour to darken. |
$proportion | float | The proportion of black to blend (0.0-1.0). |
Returns ColourTransparentData The darkened colour.
FromHex
Colour::FromHex(string $hex): ColourTransparentData
Parse a CSS hex colour (#rgb, #rgba, #rrggbb or #rrggbbaa) into a ColourTransparentData. Channels are gamma sRGB in the 0.0-1.0 range. Throws on an unparseable value.
| Name | Type | Description |
|---|---|---|
$hex | string | A CSS hex colour string. |
Returns ColourTransparentData The parsed colour.
Green
Colour::Green(): ColourTransparentData
The preset green colour (0, 1, 0, 1).
Returns ColourTransparentData Green.
Grey
Colour::Grey(float $value): ColourTransparentData
A grey colour with red, green and blue all set to the given value and alpha 1.
| Name | Type | Description |
|---|---|---|
$value | float | The grey level (0.0-1.0). |
Returns ColourTransparentData The grey colour.
Grey1
Colour::Grey1(): ColourTransparentData
The preset grey colour (0.1, 0.1, 0.2, 1).
Returns ColourTransparentData Grey1.
Grey2
Colour::Grey2(): ColourTransparentData
The preset grey colour (0.2, 0.2, 0.3, 1).
Returns ColourTransparentData Grey2.
Grey3
Colour::Grey3(): ColourTransparentData
The preset grey colour (0.3, 0.3, 0.3, 1).
Returns ColourTransparentData Grey3.
Grey4
Colour::Grey4(): ColourTransparentData
The preset grey colour (0.4, 0.4, 0.4, 1).
Returns ColourTransparentData Grey4.
Grey5
Colour::Grey5(): ColourTransparentData
The preset grey colour (0.5, 0.5, 0.5, 1).
Returns ColourTransparentData Grey5.
Grey6
Colour::Grey6(): ColourTransparentData
The preset grey colour (0.6, 0.6, 0.6, 1).
Returns ColourTransparentData Grey6.
Grey7
Colour::Grey7(): ColourTransparentData
The preset grey colour (0.7, 0.7, 0.7, 1).
Returns ColourTransparentData Grey7.
Grey8
Colour::Grey8(): ColourTransparentData
The preset grey colour (0.8, 0.8, 0.8, 1).
Returns ColourTransparentData Grey8.
Grey9
Colour::Grey9(): ColourTransparentData
The preset grey colour (0.9, 0.9, 0.9, 1).
Returns ColourTransparentData Grey9.
Interpolate
Colour::Interpolate(ColourTransparentData $colour1, ColourTransparentData $colour2, float $factor): ColourTransparentData
Linearly interpolate between two colours by the given factor, including alpha.
| Name | Type | Description |
|---|---|---|
$colour1 | ColourTransparentData | The colour returned at factor 0. |
$colour2 | ColourTransparentData | The colour returned at factor 1. |
$factor | float | The interpolation factor (0.0-1.0). |
Returns ColourTransparentData The interpolated colour.
Lighten
Colour::Lighten(ColourTransparentData $colour1, float $proportion): ColourTransparentData
Lighten a colour by linearly blending it toward white by the given proportion.
| Name | Type | Description |
|---|---|---|
$colour1 | ColourTransparentData | The colour to lighten. |
$proportion | float | The proportion of white to blend (0.0-1.0). |
Returns ColourTransparentData The lightened colour.
Magenta
Colour::Magenta(): ColourTransparentData
The preset magenta colour (0, 1, 1, 1).
Returns ColourTransparentData Magenta.
Maximum
Colour::Maximum(ColourTransparentData $colour1, ColourTransparentData $colour2): ColourTransparentData
The channel-wise maximum of two colours, including alpha.
| Name | Type | Description |
|---|---|---|
$colour1 | ColourTransparentData | The first colour. |
$colour2 | ColourTransparentData | The second colour. |
Returns ColourTransparentData The per-channel maximum.
Minimum
Colour::Minimum(ColourTransparentData $colour1, ColourTransparentData $colour2): ColourTransparentData
The channel-wise minimum of two colours, including alpha.
| Name | Type | Description |
|---|---|---|
$colour1 | ColourTransparentData | The first colour. |
$colour2 | ColourTransparentData | The second colour. |
Returns ColourTransparentData The per-channel minimum.
MixSrgb
Colour::MixSrgb(string $a, string $b, float $amountOfB): string
Mix two hex colours in gamma sRGB space and return the resulting hex. The direct analogue of CSS color-mix(in srgb, a, b) with amountOfB as a 0.0-1.0 proportion.
| Name | Type | Description |
|---|---|---|
$a | string | The first hex colour. |
$b | string | The second hex colour. |
$amountOfB | float | The proportion of the second colour (0.0-1.0). |
Returns string The mixed hex colour.
Multiply
Colour::Multiply(ColourTransparentData $colour1, ColourTransparentData $colour2): ColourTransparentData
Multiply two colours channel by channel, including alpha.
| Name | Type | Description |
|---|---|---|
$colour1 | ColourTransparentData | The first colour. |
$colour2 | ColourTransparentData | The second colour. |
Returns ColourTransparentData The channel-wise product.
Orange
Colour::Orange(): ColourTransparentData
The preset orange colour (1, 0.75, 0, 1).
Returns ColourTransparentData Orange.
Pink
Colour::Pink(): ColourTransparentData
The preset pink colour (1, 0.66, 0.66, 1).
Returns ColourTransparentData Pink.
Purple
Colour::Purple(): ColourTransparentData
The preset purple colour (0.75, 0, 1, 1).
Returns ColourTransparentData Purple.
Red
Colour::Red(): ColourTransparentData
The preset red colour (1, 0, 0, 1).
Returns ColourTransparentData Red.
Shade
Colour::Shade(string $hex, float $amount): string
Shade: mix a hex colour toward black by the given amount, producing a darker shade.
| Name | Type | Description |
|---|---|---|
$hex | string | The hex colour to shade. |
$amount | float | The proportion toward black (0.0-1.0). |
Returns string The darker hex colour.
Square
Colour::Square(ColourTransparentData $colour): ColourTransparentData
Square each channel of a colour, including alpha.
| Name | Type | Description |
|---|---|---|
$colour | ColourTransparentData | The colour to square. |
Returns ColourTransparentData The colour with squared channels.
SquareRoot
Colour::SquareRoot(ColourTransparentData $colour): ColourTransparentData
Take the square root of each channel of a colour (negative channels are treated as zero), including alpha.
| Name | Type | Description |
|---|---|---|
$colour | ColourTransparentData | The colour to process. |
Returns ColourTransparentData The colour with square-rooted channels.
Subtract
Colour::Subtract(ColourTransparentData $colour1, ColourTransparentData $colour2): ColourTransparentData
Subtract the second colour from the first channel by channel, including alpha.
| Name | Type | Description |
|---|---|---|
$colour1 | ColourTransparentData | The colour to subtract from. |
$colour2 | ColourTransparentData | The colour to subtract. |
Returns ColourTransparentData The channel-wise difference.
Tint
Colour::Tint(string $hex, float $amount): string
Tint: mix a hex colour toward white by the given amount, producing a lighter shade.
| Name | Type | Description |
|---|---|---|
$hex | string | The hex colour to tint. |
$amount | float | The proportion toward white (0.0-1.0). |
Returns string The lighter hex colour.
ToAnsi
Colour::ToAnsi(ColourTransparentData $colour): string
Convert a colour to an ANSI "R;G;B" byte string.
| Name | Type | Description |
|---|---|---|
$colour | ColourTransparentData | The colour to convert. |
Returns string The "R;G;B" byte string.
ToHex
Colour::ToHex(ColourTransparentData $colour): string
Serialise a colour to a CSS hex string. Emits #rrggbb when fully opaque, otherwise #rrggbbaa. Channels are clamped and rounded.
| Name | Type | Description |
|---|---|---|
$colour | ColourTransparentData | The colour to serialise. |
Returns string The CSS hex string.
White
Colour::White(): ColourTransparentData
The preset white colour (1, 1, 1, 1).
Returns ColourTransparentData White.
Yellow
Colour::Yellow(): ColourTransparentData
The preset yellow colour (1, 1, 0, 1).
Returns ColourTransparentData Yellow.
ColourBlend
Blend two colours by a factor using a linear, square or square-root curve. All blends include the alpha channel; Channel blends a single float value.
Channel
ColourBlend::Channel(float $value1, float $value2, float $factor): float
Linearly interpolate a single channel value between two values.
| Name | Type | Description |
|---|---|---|
$value1 | float | The value returned at factor 0. |
$value2 | float | The value returned at factor 1. |
$factor | float | The blend factor (0.0-1.0). |
Returns float The blended value.
Linear
ColourBlend::Linear(ColourTransparentData $colour1, ColourTransparentData $colour2, float $factor): ColourTransparentData
Linear blend between two colours including alpha. At factor 0.0 returns colour1; at 1.0 returns colour2.
| Name | Type | Description |
|---|---|---|
$colour1 | ColourTransparentData | The first colour. |
$colour2 | ColourTransparentData | The second colour. |
$factor | float | The blend factor (0.0-1.0). |
Returns ColourTransparentData The blended colour.
Square
ColourBlend::Square(ColourTransparentData $colour1, ColourTransparentData $colour2, float $factor): ColourTransparentData
Square blend between two colours, using a square interpolation curve that starts slowly and accelerates.
| Name | Type | Description |
|---|---|---|
$colour1 | ColourTransparentData | The first colour. |
$colour2 | ColourTransparentData | The second colour. |
$factor | float | The blend factor (0.0-1.0). |
Returns ColourTransparentData The blended colour.
SquareRoot
ColourBlend::SquareRoot(ColourTransparentData $colour1, ColourTransparentData $colour2, float $factor): ColourTransparentData
Square root blend between two colours, using a square-root interpolation curve that starts quickly and decelerates.
| Name | Type | Description |
|---|---|---|
$colour1 | ColourTransparentData | The first colour. |
$colour2 | ColourTransparentData | The second colour. |
$factor | float | The blend factor (0.0-1.0). |
Returns ColourTransparentData The blended colour.
ColourOpaqueData
An opaque colour: red, green and blue channels in the 0.0-1.0 range, with no alpha. The fields are readonly and set through the constructor.
Properties
| Name | Type | Description |
|---|---|---|
$red | float | The red channel (default 0.0). |
$green | float | The green channel (default 0.0). |
$blue | float | The blue channel (default 0.0). |
__construct
$var->__construct(float $red = 0.0, float $green = 0.0, float $blue = 0.0)
Construct an opaque colour from its red, green and blue channels.
| Name | Type | Description |
|---|---|---|
$red | float | The red channel (default 0.0). |
$green | float | The green channel (default 0.0). |
$blue | float | The blue channel (default 0.0). |
ColourRGBA
Static helpers, presets and operations for RGBA colours. Every colour is a ColourTransparentData with float channels (0.0-1.0), and the alpha channel is included in all operations.
Add
ColourRGBA::Add(ColourTransparentData $colour1, ColourTransparentData $colour2): ColourTransparentData
Add two colours channel by channel, including alpha.
| Name | Type | Description |
|---|---|---|
$colour1 | ColourTransparentData | The first colour. |
$colour2 | ColourTransparentData | The second colour. |
Returns ColourTransparentData The channel-wise sum.
Black
ColourRGBA::Black(): ColourTransparentData
The black colour (0, 0, 0, 1).
Returns ColourTransparentData Black.
Blue
ColourRGBA::Blue(): ColourTransparentData
The blue colour (0, 0, 1, 1).
Returns ColourTransparentData Blue.
Brightness
ColourRGBA::Brightness(string $hexColor): float
Calculate the brightness of a hex colour string using the luminance formula (0.299R + 0.587G + 0.114B) / 255, returning 0.0 (darkest) to 1.0 (lightest). Returns 0.0 when parsing fails.
| Name | Type | Description |
|---|---|---|
$hexColor | string | A six-digit hex colour, with or without a leading #. |
Returns float The brightness (0.0-1.0).
Brown
ColourRGBA::Brown(): ColourTransparentData
The brown colour (0.5, 0.25, 0, 1).
Returns ColourTransparentData Brown.
ByteValue
ColourRGBA::ByteValue(float $value): int
Convert a float channel value (0.0-1.0) to a byte value (0-255).
| Name | Type | Description |
|---|---|---|
$value | float | A channel value in the 0.0-1.0 range. |
Returns int The byte value, 0 to 255.
Clamp
ColourRGBA::Clamp(ColourTransparentData $colour, ColourTransparentData $minColour, ColourTransparentData $maxColour): ColourTransparentData
Clamp each channel of a colour between the matching channels of a minimum and maximum colour, including alpha.
| Name | Type | Description |
|---|---|---|
$colour | ColourTransparentData | The colour to clamp. |
$minColour | ColourTransparentData | The per-channel minimum. |
$maxColour | ColourTransparentData | The per-channel maximum. |
Returns ColourTransparentData The clamped colour.
Cyan
ColourRGBA::Cyan(): ColourTransparentData
The cyan colour (1, 0, 1, 1).
Returns ColourTransparentData Cyan.
Darken
ColourRGBA::Darken(ColourTransparentData $colour1, float $proportion): ColourTransparentData
Darken a colour by blending it with black by the given proportion.
| Name | Type | Description |
|---|---|---|
$colour1 | ColourTransparentData | The colour to darken. |
$proportion | float | The proportion of black to blend (0.0-1.0). |
Returns ColourTransparentData The darkened colour.
Green
ColourRGBA::Green(): ColourTransparentData
The green colour (0, 1, 0, 1).
Returns ColourTransparentData Green.
Grey
ColourRGBA::Grey(float $value): ColourTransparentData
Create a grey colour with all RGB channels set to the given value.
| Name | Type | Description |
|---|---|---|
$value | float | The grey level (0.0-1.0). |
Returns ColourTransparentData The grey colour.
Grey1
ColourRGBA::Grey1(): ColourTransparentData
The grey colour (0.1, 0.1, 0.2, 1).
Returns ColourTransparentData Grey1.
Grey2
ColourRGBA::Grey2(): ColourTransparentData
The grey colour (0.2, 0.2, 0.3, 1).
Returns ColourTransparentData Grey2.
Grey3
ColourRGBA::Grey3(): ColourTransparentData
The grey colour (0.3, 0.3, 0.3, 1).
Returns ColourTransparentData Grey3.
Grey4
ColourRGBA::Grey4(): ColourTransparentData
The grey colour (0.4, 0.4, 0.4, 1).
Returns ColourTransparentData Grey4.
Grey5
ColourRGBA::Grey5(): ColourTransparentData
The grey colour (0.5, 0.5, 0.5, 1).
Returns ColourTransparentData Grey5.
Grey6
ColourRGBA::Grey6(): ColourTransparentData
The grey colour (0.6, 0.6, 0.6, 1).
Returns ColourTransparentData Grey6.
Grey7
ColourRGBA::Grey7(): ColourTransparentData
The grey colour (0.7, 0.7, 0.7, 1).
Returns ColourTransparentData Grey7.
Grey8
ColourRGBA::Grey8(): ColourTransparentData
The grey colour (0.8, 0.8, 0.8, 1).
Returns ColourTransparentData Grey8.
Grey9
ColourRGBA::Grey9(): ColourTransparentData
The grey colour (0.9, 0.9, 0.9, 1).
Returns ColourTransparentData Grey9.
Interpolate
ColourRGBA::Interpolate(ColourTransparentData $colour1, ColourTransparentData $colour2, float $factor): ColourTransparentData
Linearly interpolate between two colours including alpha; factor 0.0 returns colour1 and 1.0 returns colour2.
| Name | Type | Description |
|---|---|---|
$colour1 | ColourTransparentData | The colour returned at factor 0. |
$colour2 | ColourTransparentData | The colour returned at factor 1. |
$factor | float | The interpolation factor (0.0-1.0). |
Returns ColourTransparentData The interpolated colour.
Lighten
ColourRGBA::Lighten(ColourTransparentData $colour1, float $proportion): ColourTransparentData
Lighten a colour by blending it with white by the given proportion.
| Name | Type | Description |
|---|---|---|
$colour1 | ColourTransparentData | The colour to lighten. |
$proportion | float | The proportion of white to blend (0.0-1.0). |
Returns ColourTransparentData The lightened colour.
Magenta
ColourRGBA::Magenta(): ColourTransparentData
The magenta colour (0, 1, 1, 1).
Returns ColourTransparentData Magenta.
Maximum
ColourRGBA::Maximum(ColourTransparentData $colour1, ColourTransparentData $colour2): ColourTransparentData
The channel-wise maximum of two colours, including alpha.
| Name | Type | Description |
|---|---|---|
$colour1 | ColourTransparentData | The first colour. |
$colour2 | ColourTransparentData | The second colour. |
Returns ColourTransparentData The per-channel maximum.
Minimum
ColourRGBA::Minimum(ColourTransparentData $colour1, ColourTransparentData $colour2): ColourTransparentData
The channel-wise minimum of two colours, including alpha.
| Name | Type | Description |
|---|---|---|
$colour1 | ColourTransparentData | The first colour. |
$colour2 | ColourTransparentData | The second colour. |
Returns ColourTransparentData The per-channel minimum.
Multiply
ColourRGBA::Multiply(ColourTransparentData $colour1, ColourTransparentData $colour2): ColourTransparentData
Multiply two colours channel by channel, including alpha.
| Name | Type | Description |
|---|---|---|
$colour1 | ColourTransparentData | The first colour. |
$colour2 | ColourTransparentData | The second colour. |
Returns ColourTransparentData The channel-wise product.
Orange
ColourRGBA::Orange(): ColourTransparentData
The orange colour (1, 0.75, 0, 1).
Returns ColourTransparentData Orange.
Pink
ColourRGBA::Pink(): ColourTransparentData
The pink colour (1, 0.66, 0.66, 1).
Returns ColourTransparentData Pink.
Purple
ColourRGBA::Purple(): ColourTransparentData
The purple colour (0.75, 0, 1, 1).
Returns ColourTransparentData Purple.
Red
ColourRGBA::Red(): ColourTransparentData
The red colour (1, 0, 0, 1).
Returns ColourTransparentData Red.
Square
ColourRGBA::Square(ColourTransparentData $colour): ColourTransparentData
Square each channel of a colour, including alpha.
| Name | Type | Description |
|---|---|---|
$colour | ColourTransparentData | The colour to square. |
Returns ColourTransparentData The colour with squared channels.
SquareRoot
ColourRGBA::SquareRoot(ColourTransparentData $colour): ColourTransparentData
Take the square root of each channel of a colour, including alpha.
| Name | Type | Description |
|---|---|---|
$colour | ColourTransparentData | The colour to process. |
Returns ColourTransparentData The colour with square-rooted channels.
Subtract
ColourRGBA::Subtract(ColourTransparentData $colour1, ColourTransparentData $colour2): ColourTransparentData
Subtract the second colour from the first channel by channel, including alpha.
| Name | Type | Description |
|---|---|---|
$colour1 | ColourTransparentData | The colour to subtract from. |
$colour2 | ColourTransparentData | The colour to subtract. |
Returns ColourTransparentData The channel-wise difference.
ToAnsi
ColourRGBA::ToAnsi(ColourTransparentData $colour): string
Convert a colour to an ANSI colour code string in the format "R;G;B".
| Name | Type | Description |
|---|---|---|
$colour | ColourTransparentData | The colour to convert. |
Returns string The "R;G;B" byte string.
White
ColourRGBA::White(): ColourTransparentData
The white colour (1, 1, 1, 1).
Returns ColourTransparentData White.
Yellow
ColourRGBA::Yellow(): ColourTransparentData
The yellow colour (1, 1, 0, 1).
Returns ColourTransparentData Yellow.
ColourTransparentData
A colour with red, green, blue and alpha channels in the 0.0-1.0 range. The fields are readonly and set through the constructor; helper functions convert to and from JSON.
Properties
| Name | Type | Description |
|---|---|---|
$red | float | The red channel (default 0.0). |
$green | float | The green channel (default 0.0). |
$blue | float | The blue channel (default 0.0). |
$alpha | float | The alpha channel (default 1.0). |
__construct
$var->__construct(float $red = 0.0, float $green = 0.0, float $blue = 0.0, float $alpha = 1.0)
Construct a colour from its red, green, blue and alpha channels.
| Name | Type | Description |
|---|---|---|
$red | float | The red channel (default 0.0). |
$green | float | The green channel (default 0.0). |
$blue | float | The blue channel (default 0.0). |
$alpha | float | The alpha channel (default 1.0). |
FromJson
ColourTransparentData::FromJson(stdClass $json): ColourTransparentData
Build a colour from a decoded JSON object, defaulting missing channels (red, green, blue to 0.0 and alpha to 1.0).
| Name | Type | Description |
|---|---|---|
$json | stdClass | A decoded JSON object with optional red, green, blue and alpha fields. |
Returns ColourTransparentData The colour.
ToJson
$var->ToJson(): array
Serialise the colour to an array with red, green, blue and alpha keys.
Returns array The colour as an associative array.