PHPackages ssnepenthe/color-utils - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. ssnepenthe/color-utils ActiveLibrary[Utility & Helpers](/categories/utility) ssnepenthe/color-utils ====================== A PHP library for performing SASS-like color manipulations. 0.4.2(8y ago)631.1M↑11.8%1[9 issues](https://github.com/ssnepenthe/color-utils/issues)9GPL-2.0PHPPHP >=7.0 Since Dec 14Pushed 3y ago2 watchersCompare [ Source](https://github.com/ssnepenthe/color-utils)[ Packagist](https://packagist.org/packages/ssnepenthe/color-utils)[ Docs](https://github.com/ssnepenthe/color-utils)[ RSS](/packages/ssnepenthe-color-utils/feed)WikiDiscussions master Synced 1mo ago READMEChangelogDependencies (6)Versions (8)Used By (9) color-utils =========== [](#color-utils) This package is intended to provide a variety of [SASS-like color manipulation functions](http://sass-lang.com/documentation/Sass/Script/Functions.html). Requirements ------------ [](#requirements) Composer, PHP 7.0 or later. Installation ------------ [](#installation) Install using Composer: ``` composer require ssnepenthe/color-utils ``` Usage ----- [](#usage) *All functions listed are within the `SSNepenthe\ColorUtils` namespace.* ### Color Representation [](#color-representation) Create Color objects using the `color` function: **color(array $color)** `$color` is an array of `$channel => $value` pairs. Valid channels are red, green, blue, hue, saturation, lightness and alpha. - `color(['red' => 255, 'green' => 0, 'blue' => 51])` - `color(['hue' => 348, 'saturation' => 100, 'lightness' => 50, 'alpha' => 0.7])` **color(string $color)** `$color` is a string representation of a color in one of the following formats: - Hex notation: `'#f03'` or `'#ff0033'` - Keyword notation: `'white'` ([list of valid keywords on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#Color_keywords)) - Functional hsl(a) notation: `'hsl(348, 100%, 50%)` or `'hsla(348, 100%, 50%, 0.7)'` - Functional rgb(a) notation: `'rgb(255, 0, 51)'` or `'rgba(255, 0, 51, 0.7)'` **color(int $red, int $green, int $blue, \[float $alpha\])** 0 - 255 range for each of `$red`, `$green` and `$blue`, 0 - 1 for `$alpha`. - `color(255, 0, 51)` - `color(255, 0, 51, 0.7)` **color(float $hue, float $saturation, float $lightness, \[float $alpha\])** 0 - 360 range for `$hue`, 0 - 100 for each of `$saturation` and `$lightness`, 0 - 1 for `$alpha`. - `color(348.0, 100.0, 50.0)` - `color(348.0, 100.0, 50.0, 0.7)` *Regarding the previous two examples:* The values 255, 0 and 51 could technically represent RGB values as well as HSL values. In cases like this, RGB takes precedence over HSL. If you need finer control, use the following functions: **hsl(float $hue, float $saturation, float $lightness)** **hsla(float $hue, float $saturation, float $lightness, float $alpha)** **rgb(int $red, int $green, int $blue)** **rgba(int $red, int $green, int $blue, float $alpha)** Lastly, the `hsla` and `rgba` functions can also be used to adjust the transparency of an existing color: ``` $hsl = hsl(348, 100, 50); echo $hsl; // 'hsl(348, 100%, 50%)' $hsla = hsla($hsl, 0.7); echo $hsla; // 'hsla(348, 100%, 50%, 0.7)' ``` ### Color Components [](#color-components) Individual color components are accessible using the following functions (which each accept any `$color` argument recognized by the `color` function, including a complete color object): **alpha($color)** Get the alpha channel of a color. - `alpha('#f03'); // 1.0` **blue($color)** Get the blue channel of a color. - `blue('#f03'); // 51` **brightness($color)** Calculates [color brightness](https://www.w3.org/TR/AERT#color-contrast) on a scale from 0 (black) to 255 (white). - `brightness('#f03') // 82.059` **green($color)** Get the green channel of a color. - `green('#f03'); // 0` **hue($color)** Get the hue channel of a color. - `hue('#f03'); // 348.0` **is\_bright($color)** Accepts an optional `$threshold` float as the last parameter with a default of 127.5. Checks `brightness($color) >= $threshold`. - `is_bright('#f03'); // false` - `is_bright('#f03', 82); // true` **is\_light($color)** Accepts an optional `$threshold` float as the last parameter with a default of 50.0. Checks `lightness($color) >= $threshold`. - `is_light('#f03'); // true` - `is_light('#f03', 55); // false` **lightness($color)** Get the lightness channel of a color. - `lightness('#f03'); // 50.0` **looks\_bright($color)** Accepts an optional `$threshold` float as the last parameter with a default of 127.5. Checks `perceived_brightness($color) >= $threshold`. - `looks_bright('#f03'); // true` - `looks_bright('#f03', 141.0); // false` **name($color)** Get the name (keyword) representation of a color. Returns an empty string if none is found. - `name('#f03'); // ''` - `name('#00f'); // 'blue'` **opacity($color)** Alias of `alpha($color)`. **perceived\_brightness($color)** Calculates the [perceived brightness](http://alienryderflex.com/hsp.html) of a color on a scale from 0 (black) to 255 (white). - `perceived_brightness('#f03'); // 140.49551` **red($color)** Get the red channel of a color. - `red('#f03'); // 255` **relative\_luminance($color)** Calculates the [relative luminance](https://www.w3.org/TR/WCAG20/#relativeluminancedef) of a color on a scale from 0 (black) to 1 (white). - `relative_luminance('#f03'); // 0.21499` **saturation($color)** Get the saturation channel of a color. - `saturation('#f03'); // 100.0` ### Color Calculations [](#color-calculations) The following functions calculate differences between two given colors: **brightness\_difference(Color $color1, Color $color2)** Calculates [brightness difference](https://www.w3.org/TR/AERT#color-contrast) on a scale from 0 to 255. - `brightness_difference(color('red'), color('green')) // 1.109` **color\_difference(Color $color1, Color $color2)** Calculates [color difference](https://www.w3.org/TR/AERT#color-contrast) on a scale from 0 to 765. - `color_difference(color('red'), color('green')) // 383` **constrast\_ratio(Color $color1, Color $color2)** Calculates the [contrast ratio](https://www.w3.org/TR/WCAG20/#contrast-ratiodef) between two colors on a scale from 1 to 21. - `contrast_ratio(color('red'), color('green')) // 1.28486` ### Color Transformations [](#color-transformations) Colors can be transformed using the following functions (all accept any `$color` argument recognized by the `color` function): **adjust\_color($color, array $channels)** Creates a new color by increasing/decreasing one or more channel values of `$color`. This can change red, green, blue, hue, saturation, lightness and alpha channels. `$channels` are specified as an array of `$channel => $amount` pairs. - `(string) adjust_color('rgb(50, 100, 150)', ['green' => 50, 'blue' => -50]); // 'rgb(50, 150, 100)'` **change\_color($color, array $channels)** Creates a new color by changing one or more channel values of `$color`. This can change red, green, blue, hue, saturation, lightness and alpha channels. `$channels` are specified as an array of `$channel => $amount` pairs. - `(string) change_color('rgb(50, 100, 150)', ['green' => 50, 'blue' => 25]); // 'rgb(50, 50, 25)'` **invert($color)** Creates a new color by inverting (subtracting from 255) the red, green and blue channels of `$color`. Alpha is left unchanged. - `(string) invert('rgb(50, 100, 150)'); // 'rgb(205, 155, 105)'` **mix(Color $color1, Color $color2, int $weight = 50)** Creates a new color by averaging the red, green and blue channels from `$color1` and `$color2`, with `$color1` optionally weighted by `$weight`%. Alpha is also considered. [Uses the same algorithm as SASS](https://github.com/sass/sass/blob/stable/lib/sass/script/functions.rb#L1291). - `(string) mix(color('rgb(50, 100, 150)'), color('rgb(100, 100, 100)')); // 'rgb(75, 100, 125)` - `(string) mix(color('rgb(50, 100, 150)'), color('rgb(100, 100, 100)'), 25); // 'rgb(88, 100, 113)` - `(string) mix(color('rgb(50, 100, 150)'), color('rgb(100, 100, 100)'), 75); // 'rgb(63, 100, 138)` **scale\_color($color, array $channels)** Creates a new color by scaling one or more channel values of `$color`. This can change red, green, blue, hue, saturation, lightness and alpha channels. `$channels` are specified as an array of `$channel => $percent` pairs, and each channel value is scaled by `$percent`% of the max possible adjustment. In the example below, green is 100 and we want to scale positively by 50%. The maximum allowed value is 255 which means the maximum possible adjustment is 155. The new green value then becomes 100 + (155 \* 0.5). Likewise, blue is 150 and we want to scale negatively by 50%. The minimum allowed value is 0 which means the maximum possible adjustment is -150. The new blue value then becomes 150 + (-150 \* 0.5). - `(string) scale_color('rgb(50, 100, 150)', ['green' => 50, 'blue' => -50]); // 'rgb(50, 178, 75)'` **adjust\_hue($color, float $degrees)** Alias of `adjust_color($color, ['hue' => $degrees])`. **complement($color)** Alias of `adjust_color($color, ['hue' => 180])`. **darken($color, float $amount)** Alias of `adjust_color($color, ['lightness' => -1 * $amount])`. **desaturate($color, float $amount)** Alias of `adjust_color($color, ['saturation' => -1 * $amount])`. **fade\_in($color, float $amount)** Alias of `opacify($color, $amount)`. **fade\_out($color, float $amount)** Alias of `transparentize($color, $amount)`. **grayscale($color)** Alias of `change_color($color, ['saturation' => 0])`. **lighten($color, float $amount)** Alias of `adjust_color($color, ['lightness' => $amount])`. **opacify($color, float $amount)** Alias of `adjust_color($color, ['alpha' => $amount])`. **saturate($color, float $amount)** Alias of `adjust_color($color, ['saturation' => $amount])`. **shade($color, int $weight = 50)** Alias of `mix(color('black'), color($color), $weight)`. **tint($color, int $weight = 50)** Alias of `mix(color('white'), color($color), $weight)`. **transparentize($color, float $amount)** Alias of `adjust_color($color, ['alpha' => -1 * $amount])`. ### Health Score 38 — LowBetter than 85% of packages Maintenance17 Infrequent updates — may be unmaintained Popularity50 Moderate usage in the ecosystem Community17 Small or concentrated contributor base Maturity53 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~37 days Total 6 Last Release 3255d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/acf42baca29dd8d1ffaf61009a3000068423a84db153c5cb864ef6fde64a1b87?d=identicon)[ssnepenthe](/maintainers/ssnepenthe) --- Top Contributors [![ssnepenthe](https://avatars.githubusercontent.com/u/10903810?v=4)](https://github.com/ssnepenthe "ssnepenthe (100 commits)") --- Tags convertmanipulationconversioncolorrgbsassscsshextransformationBrightnesshslrgbahslaalphahuehexadecimalgreenbluesaturationredlightnessluminance ### Code Quality TestsPHPUnit Static AnalysisPsalm Code StylePHP\_CodeSniffer Type Coverage Yes ### Embed Badge ![Health badge](/badges/ssnepenthe-color-utils/health.svg) ``` [![Health](https://phpackages.com/badges/ssnepenthe-color-utils/health.svg)](https://phpackages.com/packages/ssnepenthe-color-utils) ``` ### Alternatives [ozdemirburak/iris PHP library for color manipulation and conversion. 1201.7M16](/packages/ozdemirburak-iris)[tecnickcom/tc-lib-color PHP library to manipulate various color representations 247.2M9](/packages/tecnickcom-tc-lib-color)[spatie/color A little library to handle color conversions 38118.9M28](/packages/spatie-color)[scssphp/scssphp scssphp is a compiler for SCSS written in PHP. 62827.7M220](/packages/scssphp-scssphp)[fjw/color-compare A library for converting colors (Hex, RGB, HSL, CIELAB (LAB), DIN-99) and calculating color distances based on DIN-99. 1310.0k](/packages/fjw-color-compare) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)