PHPackages aristath/ari-color - 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. aristath/ari-color ActiveLibrary[Utility & Helpers](/categories/utility) aristath/ari-color ================== A PHP library for color manipulation in themes and plugins v1.1.2(5y ago)6128.6k↑43.3%10GPL-2.0-or-laterPHPPHP >=5.2CI failing Since Jul 24Pushed 5y ago7 watchersCompare [ Source](https://github.com/aristath/ariColor)[ Packagist](https://packagist.org/packages/aristath/ari-color)[ Docs](http://aristath.github.io/ariColor)[ GitHub Sponsors](https://github.com/aristath)[ RSS](/packages/aristath-ari-color/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (2)Dependencies (3)Versions (3)Used By (0) ariColor ======== [](#aricolor) A PHP library for color manipulation in themes and plugins [![Build Status](https://camo.githubusercontent.com/a216c80153c86ca330125af0670b01bfb7e54a7c353e0fbed692c6979854001d/68747470733a2f2f7472617669732d63692e6f72672f61726973746174682f617269436f6c6f722e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/aristath/ariColor) [![codecov.io](https://camo.githubusercontent.com/4051ebad366de501f5e326f687eda00ad1b666151da683c524a7df1542d10ce2/68747470733a2f2f636f6465636f762e696f2f6769746875622f61726973746174682f617269436f6c6f722f636f7665726167652e7376673f6272616e63683d6d6173746572)](https://codecov.io/github/aristath/ariColor?branch=master) [![License](https://camo.githubusercontent.com/e59e947b9f67c2271503c2d3b6d600b04a07ceaa780a7a4daf3a50394f1fbfd0/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d47504c2d2d322e302532422d7265642e737667)](https://raw.githubusercontent.com/aristath/ariColor/master/LICENSE) `ariColor` is a PHP library that will hopefully help WordPress theme developers do their job easier and more effectively. #### Installation [](#installation) ``` composer require aristath/ari-color ``` It does not provide you with methods like `lighten()`, `darken()` etc. Instead, what it does is give you the ability to create these yourself with extreme ease by giving you all the properties of a color at hand, and allowing you to manipulate them however you see fit. Example: First, let's create our color object: ``` $color = ariColor::newColor( '#049CBE', 'hex' ); ``` If you don't like using that method you can write your own proxy function: ``` function my_custom_color_function( $color = '#ffffff' ) { return ariColor::newColor( $color, 'auto' ); } ``` Notice that we used `auto` as the mode. If you use `auto` or completely omit the 2nd argument, `ariColor` will auto-detect it for you. You can use `rgb`, `rgba`, `hsl`, `hsla`, or even arrays as colors. Then you can use it like this: ``` $color = my_custom_color_function( '#049CBE' ); ``` Say you want to get the values for red, green, blue: ``` // Get red value: $red = $color->red; // Get green value: $green = $color->green; // Get blue value $blue = $color->blue; ``` Or you want to get the hue, saturation, lightness or even luminance of your color: ``` // Get hue $hue = $color->hue; // Get saturation $saturation = $color->saturation; // Get lightness $lightness = $color->lightness; // Get luminance $luminance = $color->luminance; ``` ### Scenario 1: [](#scenario-1) You have an option where users can define the background color for their ``. In order to make sure the text is always readable, you can either give them a 2nd option to set the text color, or auto-calculate it for readability. Example function that given a background color decides if we're going to use white/black text color: ``` /** * determine the luminance of the given color * and then return #FFFFFF or #222222 so that our text is always readable * * @param $background color string|array * * @return string (hex color) */ function custom_get_readable_color( $background_color = '#FFFFFF' ) { $color = ariColor::newColor( $background_color ); return ( 127 < $color->luminance ) ? '#222222' : '#FFFFFF'; } ``` Usage: ``` $text_color = custom_get_readable_color( get_theme_mod( 'bg_color', '#ffffff' ) ); ``` Easy, right? What we did above is simply check the luminance of the background color, and then if the luminance is greater than 127 we return black, otherwise we return white. ### Scenario 2: [](#scenario-2) We have a HEX color, and we want to get the same color as rgba, with an opacity of `0.7`: ``` function my_theme_get_semitransparent_color( $color ) { // Create the color object $color_obj = ariColor::newColor( $color ); // Set alpha (opacity) to 0.7 $color_obj->alpha = 0.7; // return a CSS-formated rgba color return $color_obj->toCSS( 'rgba' ); } ``` or you could write it shorter like this: ``` function my_theme_get_semitransparent_color( $color ) { $color_obj = ariColor::newColor( $color ); return $color_obj->getNew( 'alpha', .7 )->toCSS( 'rgba' ); } ``` or the same thing like this: ``` function my_theme_get_semitransparent_color( $color ) { $color_obj = ariColor::newColor( $color ); $color_new = ariColor::newColor( 'rgba(' . $color_obj->red . ',' . $color_obj->green . ',' . $color_obj->blue . ',0.7)', 'rgba' ); return $color_new->->toCSS( 'rgba' ); } ``` The choice is yours and you can manipulate colors in any way you want. Properies list: --------------- [](#properies-list) - `mode` (string: hex/rgb/rgba/hsl/hsla) - `red` (red value, `integer`, range: 0-255) - `green` (green value, `integer`, range: 0-255) - `blue` (blue value, `integer`, range: 0-255) - `alpha`(alpha/opacity value, `float`, range 0-1) - `hue` (color hue, `integer`, range 0-360) - `saturation` (color saturation, `integer`, range 0-100) - `lightness` (color lightness, `integer`, range 0-100) - `luminance`(color luminance, `integer`, range 0-255) - `hex` (the hex value of the current color) Methods: -------- [](#methods) - `newColor` - `getNew` - `toCSS` ### newColor [](#newcolor) Used to create a new object. Example: ``` $color = ariColor::newColor( 'rgba(0, 33, 176, .62)' ); ``` The `newColor` method has 2 arguments: 1. `$color`: can accept any color value (see below for examples) 2. `$mode`: the color mode. If undefined will be auto-detected. Some example of acceptable formats for the color used in the 1st argument on the method: ``` 'black' 'darkmagenta' '#000' '#000000' 'rgb(0, 0, 0)' 'rgba(0, 0, 0, 1)' 'hsl(0, 0%, 0%)' 'hsla(0, 0%, 0%, 1)' array( 'rgba' => 'rgba(0,0,0,1)' ) array( 'color' => '#000000' ) array( 'color' => '#000000', 'alpha' => 1 ) array( 'color' => '#000000', 'opacity' => '1' ) array( 0, 0, 0, 1 ) array( 0, 0, 0 ) array( 'r' => 0, 'g' => '0', 'b' => 0 ) array( 'r' => 0, 'g' => '0', 'b' => 0, 'a' => 1 ) array( 'red' => 0, 'green' => 0, 'blue' => 0 ) array( 'red' => 0, 'green' => 0, 'blue' => 0, 'alpha' => 1 ) array( 'red' => 0, 'green' => 0, 'blue' => 0, 'opacity' => 1 ) ``` And more! This way you can use the saved values from all known frameworks. ### getNew [](#getnew) Used if we want to create a new object identical to the one we already have, but changing one of its properties. The `getNew` method has 2 arguments: 1. `$property`: can accept any of the properties listed above 2. `$value`: the new value of the property. Example 1: Darken a color by 10% ``` // Create a new object using rgba as our original color $color = ariColor::newColor( 'rgba(0, 33, 176, .62)' ); // Darken the color by 10% $dark = $color->getNew( 'lightness', $color->lightness - 10 ); // return HEX color return $dark->toCSS( 'hex' ); ``` Or you could write the above simpler like this by combining 2 steps: ``` $color = ariColor::newColor( 'rgba(0, 33, 176, .62)' ); return $color->getNew( 'lightness', $color->lightness - 10 )->toCSS( 'hex' ) ``` Example 2: Remove any traces of green from an HSL color ``` // Create a new color object using an HSL color as source $color = ariColor::newColor( 'hsl(200, 33%, 82%)' ); // I don't like green, color, let's remove any traces of green from that color $new_color = $color->getNew( 'green', 0 ); ``` ### toCSS [](#tocss) Returns a CSS-formatted color value. The `toCSS` has a single argument: 1. `$mode`: can accept any of the values listed below (defaults to `hex` if undefined) - `hex` - `rgb` - `rgba` - `hsl` - `hsla` Example: ``` // Create our instance $color = ariColor::newColor( 'hsl(200, 33%, 82%)' ); // Get HEX color $hex = $color->toCSS( 'hex' ); // Get RGB color $rgb = $color->toCSS( 'rgb' ); // Get RGBA color $rgba = $color->toCSS( 'rgba' ); // Get HSL color $hsl = $color->toCSS( 'hsl' ); // Get HSLA color $hsla = $color->toCSS( 'hsla' ); ``` ### Color sanitization: [](#color-sanitization) All colors are sanitized inside the class so you could easily write a proxy function that will always return a sanitized color like this: ``` /** * Sanitizes a CSS color. * * @param $color string accepts all CSS-valid color formats * @return string the sanitized color */ function custom_color_sanitize( $color = '' ) { // If empty, return empty if ( '' == $color ) { return ''; } // If transparent, return 'transparent' if ( is_string( $color ) && 'transparent' == trim( $color ) ) { return 'transparent'; } // Instantiate the object $color_obj = ariColor::newColor( $color ); // Return a CSS value, using the auto-detected mode return $color_obj->toCSS( $color_obj->mode ); } ``` You can even use a function like this one as a `sanitize_callback` in a customizer control :) ### Testing [](#testing) ``` composer update --dev ./vendor/bin/phpunit ``` ### Health Score 35 — LowBetter than 80% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity40 Moderate usage in the ecosystem Community16 Small or concentrated contributor base Maturity51 Maturing project, gaining track record Bus Factor1 Top contributor holds 76.9% 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 ~52 days Total 2 Last Release 2072d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/471c510b2590bce99d5e41cc9b817f0c0d420f08d0930e70b18299f993ffa965?d=identicon)[aristath](/maintainers/aristath) --- Top Contributors [![aristath](https://avatars.githubusercontent.com/u/588688?v=4)](https://github.com/aristath "aristath (40 commits)")[![yarri](https://avatars.githubusercontent.com/u/974278?v=4)](https://github.com/yarri "yarri (8 commits)")[![Sammyjo20](https://avatars.githubusercontent.com/u/29132017?v=4)](https://github.com/Sammyjo20 "Sammyjo20 (4 commits)") ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/aristath-ari-color/health.svg) ``` [![Health](https://phpackages.com/badges/aristath-ari-color/health.svg)](https://phpackages.com/packages/aristath-ari-color) ``` ### Alternatives [spatie/ssh A lightweight package to execute commands over an SSH connection 8322.8M41](/packages/spatie-ssh)[log1x/pagi A better WordPress pagination. 59105.4k](/packages/log1x-pagi)[kepex/laravel-crud-generator php artisan command to generate fully working crud with grid paginated server side only by having database tables 10216.7k](/packages/kepex-laravel-crud-generator) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)