NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
Packagist
Packagist, #3264 most downloaded on Packagist
PHP library for color manipulation and conversion.
Latest stable
5.0.0
Last release 1 months ago
23 Oct 2026
Ships unpredictably
gaps range from 2 weeks to 2.8 years
Nearly every release is documented
notes for 22 of 22 stable releases
Nothing withdrawn
no release was ever pulled
9 years old
22 releases · first in 2017
Drag across the ruler to compare, or tap a release to open it.
It is a major release, please read Breaking changes before you upgrade.
Iris 5.0.0 fixes the PHP 8.5 deprecations, fixes a set of long-standing bugs, reads modern CSS color syntax, and adds alpha to OKLCH.
It is a major release, please read Breaking changes before you upgrade.
Non-canonical cast (double) in Rgba and Hsla is fixed. (#54)Factory::init('rgb(10 20 30 / 50%)'); // Rgba
Factory::init('hsl(0.5turn 50% 50% / .3)'); // Hsla
Factory::init('oklch(62.8% 0.2577 29.23 / 0.5)');
Factory::init('#f0f8'); // Hexa
Factory::init('transparent'); // Rgba
luminance(), contrast($background), isReadable($background) and mostReadable() pick an accessible text color.distance($other) (deltaE OK) and equals($other, $tolerance) compare colors in any model.toName(), invert(), complement(), json_encode() support, and Factory::tryInit() / Factory::isValid().oklch(... / 0.5) keeps the alpha through conversions and operations.lighten(), spin(), mix(), gradient() and the others no longer drop the alpha of Rgba, Hsla, Hexa and Oklch.toHex() on a Hex (and so on) returned the object itself.red(300) sets 255) and the hue wraps around 360 (hue(400) sets 40); a value that is not a number is ignored and the setter returns the color. Hex/Hexa setters take hex digits, as before.rgba(0,0,0,0.3) gives rgb(179,179,179)).mix(), tint(), shade() and gradient() mix the alpha and weight the channels by alpha, like less.js and Sass.fade(), fadeIn() and fadeOut() return Hexa for Hex/Hexa and Oklch for Oklch (before: Rgba).Oklch keeps the alpha of oklch(... / a), so conversions to opaque models blend it onto white; Oklch::values() includes the alpha; a lightness without % that is not greater than 1 is a fraction (oklch(0.7 0.1 120) is 70%).hsv(303.5,96.7%,96.5%); Hsv::value() returns a float.Factory::init() throws InvalidColorException for an empty string and unsupported functions (e.g. hwb()), and reads 4 hex digits only with a #.Hex/Hexa use the new HexTrait, Rgb/Rgba use RgbTrait with int channels, $castsInteger and some protected helpers are removed, BaseColor has new protected methods, and the method signatures have native types.The README has an Upgrading from 4.x section, and CHANGELOG.md has the full list.
Rgba setters read integers as hex: red(100) was ignored and red(5) set 55.spin() triggered "Implicit conversion from float to int" deprecations and lost the hue decimals.Factory::init() could not read space-separated oklch(), also not the output of Oklch::__toString().fade() on Hsla returned Rgba; gradient() crashed on an empty array and lost colors with few steps.1.0E-5), so some operations threw an exception.##fff and hsl(120,1%00,50) were accepted.Hsl, Hsla, Hsv and Cmyk were up to 2 units wrong (new Hsl('coral') gave #ff8052).spin(0), lighten(0) and other operations with 0 changed Hsv, Cmyk and Oklch colors.Full changelog: https://github.com/ozdemirburak/iris/blob/5.0.0/CHANGELOG.md
Your coding agent can read these notes before it upgrades. Set up the MCP server →
rgb(10 20 30)), the alpha after a / (rgb(10 20 30 / 50%)), the alpha as a percentage, RGB values as percentages, the hue units deg, grad, rad and turn, any hue angle (it wraps around 360, e.g. hsl(-120 …)), a + sign, and the none keywordrgb() and hsl() with an alpha: Factory::init() returns Rgba and Hsla, and the Rgba and Hsla classes accept themOklch: oklch(62.8% 0.2577 29.23 / 0.5) keeps the alpha, alpha() reads and sets it, and the string form writes it when it is below 1transparent keyword in Rgba, Hsla, Hexa and Factory::init()Hexa, and # with 4 digits in Factory::init()1e2), line breaks inside a color, and whitespace around a colorOklch chroma as a percentage (100% is 0.4)Rgba::background() without an argument returns a copy of the backgroundluminance(), contrast($background), isReadable($background, $ratio = 4.5) and mostReadable($candidates)distance($other) (deltaE OK, CSS Color 4) and equals($other, $tolerance = 0.0) to compare colors in any modeltoName() (e.g. tomato), invert() and complement()json_encode() of a color gives its string form (BaseColor implements JsonSerializable)Factory::tryInit() returns null for a string that is not a color, and Factory::isValid()Helpers\ColorString, one parser for all color functionscomposer analyse), with no baseline, and composer check to run PHPStan and the testscomposer.jsonactions/checkout v7Hex::toHex()); before, some manipulations changed the original Hsl, Rgb, Rgba and Hsla object, and a conversion to the same model returned the object itselfRgb, Rgba, Hsl, Hsla, Hsv, Cmyk and Oklch clamp a value that is out of range, e.g. red(300) sets 255 and saturation(150) sets 100, and the hue wraps around 360, e.g. hue(400) sets 40; before, these values were ignored. The setters of Hex and Hexa take hex digits, as beforeNAN or INF) ignores it and returns the color; before, hue('abc') returned the hue, and alpha('abc') set 0. The Oklch setters take only numbersRgba, Hsla, Hexa and Oklch keep the alpha (and the Rgba background); before, Rgba and Hsla were blended onto white and the alpha was lostmix(), tint(), shade() and gradient() mix the alpha of both colors, and weight the channels by alpha like less.js and Sass: rgba(255,0,0,1) mixed 50% with rgba(0,0,255,0) gives rgba(255,0,0,0.5); an opaque color mixed with a transparent one is blended onto whiteRgba::toRgb() and toHex()) rounds each channel; before, it rounded down, so 65% of the results were 1 too dark, e.g. rgba(0,0,0,0.3) gives rgb(179,179,179) and not rgb(178,178,178)fade(), fadeIn() and fadeOut() return Hexa for Hex and Hexa, and Oklch for Oklch; before, they returned RgbaOklch keeps the alpha of its input, so oklch(62.8% 0.2577 29.23 / 0.5)->toHex() is blended onto white and gives #ff8080 (4.x ignored the alpha and gave #ff0000); an alpha above 1 is rejected; Oklch::values() includes the alphaRgba, Hsla and Hexa keep their RGB and alpha when they convert to Oklch; before, they were blended onto whitehsv(303.5,96.7%,96.5%) and cmyk(0,60.6,84.6,3.5); round trips through HSV and CMYK give the same color; Hsv::value() returns a floatOklch reads a lightness without % that is not greater than 1 as a number from 0 to 1 (CSS Color 4), so oklch(0.7 0.1 120) is 70%; a larger number is still a percentageFactory::init() throws InvalidColorException for an empty string and for color functions it does not support (e.g. hwb()), and reads 4 hex digits only with a #, so words like cafe are not colors; before, it threw AmbiguousColorStringHex and Hexa accept only one leading #Hex and Hexa use the new HexTrait (hex string channels), and Rgb and Rgba use RgbTrait (int channels)BaseColor declares an abstract toHexa(); the manipulation methods return static; fade(), fadeIn(), fadeOut(), tint() and shade() take a float; isLight() and isDark() return bool; back() returns BaseColor; clone() returns static; getColorModelName() returns string; Rgb::red() returns int and Hex::red() returns string (also green and blue); all properties are typedBaseColor (see Added) and new protected methods (alphaRaw(), opaqueRgb(), opaqueHsl(), toAlphaModel(), limit(), wrapHue(), isNoChange(), gradientStop(), linearize(), rgbToOklab()), and HsTrait requires lightnessOrValue()spin(0), lighten(0), mix($color, 0)) give the same color, also for Hsv, Cmyk and OklchHsla and Hsv no longer go through RGB, so they are more precise, e.g. hsla(203,45%,43%,1)->saturate(20) gives hsla(203,65%,43%,1) and not hsla(203,65.2%,42.9%,1)Oklch::fromRgb() keeps the exact values; the getters and the string form round them, as beforegradient() are exactly the given colors; each color keeps its own alpha when the first color has an alpha channelInvalidColorException and AmbiguousColorString extend \InvalidArgumentException; they are still instances of \Exceptionnew Rgb() is about 4 times faster for the r,g,b strings that the conversions create, and Rgba creates its default white background only once.gitattributes)Non-canonical cast (double) in Rgba and HslaRgba setters (red(), green(), blue()) read integers as hex strings, so red(100) was ignored and red(5) set 55saturate(), desaturate(), lighten(), darken(), brighten(), spin(), mix(), tint(), shade() and gradient() on Rgba, Hsla and Hexa dropped the alpha channel (Rgba and Hsla were also blended onto white)Hsl, Hsla, Hsv and Cmyk came from rounded tables and were up to 2 units wrong, e.g. new Hsl('coral') gave #ff8052 and not #ff7f50; they now come from the exact hex valuefade() on Hsla returned an Rgbaspin() triggered Implicit conversion from float to int deprecations and lost the decimals of the huemix(), tint() and shade() with a percent outside 0-100 dropped color channels; the percent is now clampedgradient() with an empty color array threw DivisionByZeroError, and with fewer steps than colors it lost the last colorFactory::init() removed all spaces, so the space-separated oklch() syntax (also the output of Oklch::__toString()) failedFactory::init() read '0,0,0,5' (CMYK with a one-digit black) as RGBA and failed, and merged '10 20 30' into the hex #1020301.0E-5), so fade(), darken() and other operations threw an exceptionhsl(0,50%,0.009999999999998%) after darken(49.99)Hsv value with decimals (e.g. hsv(120,50%,50.5%)) triggered deprecations and was truncatedHex setters with a float triggered deprecationsrgba(0,0,0,.5)) were rejected, and rgb(255.4 0 0) was rejected although it rounds to 255Rgba/Hsla strings such as '1,2' triggered Undefined array key warningsRgba::toHsla() threw for very small alpha values (1.0E-5); Hsla::toRgba() rounded alpha to 2 decimalsRgba::toRgb() compositing used the rounded alphaback() could change the color that it was called on, and Rgba::background() shared its object with the callerOklch::fromRgb() rounded the values it stored, so 0.08% of the colors did not convert back exactly, and some got the hue 360oklch(1.2.3 0.1 20), hsl(120,1%00,50), ##fff and rgba((10,20,30,0.5\f) was not whitespace in Factory::init() and for color namesOklch got a random hue (89.88); it is now 0$castsInteger property and the protected methods AlphaTrait::fixPrecision(), HsTrait::validationRules(), RgbTrait::validateAndSet() and CmykTrait::validateAndSet(); the parsing is in Helpers\ColorStringClamp negative alpha values in AlphaTrait by @gaoflow in https://github.com/ozdemirburak/iris/pull/53
Full Changelog: https://github.com/ozdemirburak/iris/compare/4.1.1...4.1.2
alpha() clamps a negative value to 0; before, it passed through and gave a string that the constructor rejects (#53)Fixes incorrect param type for PHPStan.
Fixes incorrect param type for PHPStan.
Added gradient() method for generating color scales (#51, #50)
Added gradient() method for generating color scales (#51, #50)
gradient() method to generate color scales between two or more colors (#51)
$colorA->gradient($colorB, $steps)$colorA->gradient([$colorB, $colorC], $steps)Fixed OKLCH parsing, accepting both comma and space separated formats.
Fixed OKLCH parsing, accepting both comma and space separated formats.
A major release bringing modern PHP support and a new color space. This version requires PHP 8.1+ and introduces OKLCH, a perceptually uniform color s
A major release bringing modern PHP support and a new color space. This version requires PHP 8.1+ and introduces OKLCH, a perceptually uniform color space, which is ideal for creating accessible color palettes and smooth gradients.
new Oklch('oklch(70%, 0.15, 150)')$hex->toOklch()^10.5|^11.0Hex, Hexa, RGB, RGBA, HSL, HSLA, HSV, CMYK, OKLCH
Cmyk class, toCmyk() on all color classes, and CMYK detection in Factory::init() (NikarashiHatsu)toOklch() method on all color classesOklch::fromRgb() static factory method for RGB to OKLCH conversionclone() method for color objectsalphaRaw() protected method for internal alpha precision handlingUsing float instead of int to avoid warnings @jaulz
Use float instead of int to avoid warnings @jaulz
saturate(), desaturate(), brighten(), lighten() and darken() accept a float percentage @jaulzRemove PHP 7 support, will only support PHP 8
Made BaseColor::back() and BaseColor::getColorModelName() public, added mixInHsv() @rv1971
Release for PHP 7.3 and 7.4 on the 2.x branch.
BaseColor::mixInHsv() @rv1971Added new Hexa class, fixes issue #28, thanks to @amnuts.
Added new Hexa class, fixes issue #28, thanks to @amnuts.
Changed HSL to HSV conversion method, fixes issue #27.
Changed HSL to HSV conversion method, fixes issue #27.
Support PHP 8.0, fixes issue #26.
Added fade, fadeIn, and fadeOut methods.
Allow more than two precision for alpha @dtSniper
Added full list of CSS colours, thanks to @amnuts.
Upgrade to phpunit 8, updated tests for phpunit 9 deprecations.
- Added tint method. - Added shade method.
Added isLight and isDark methods.
Added isLight and isDark methods.
Added return types and docblocks
- Added HSLA and RGBA support.
Saturate, desaturate, grayscale, lighten, darken, brighten, spin and mix operations.
One column per quarter.