aristath / ari-color
A PHP library for color manipulation in themes and plugins
Fund package maintenance!
aristath
Installs: 25 024
Dependents: 0
Suggesters: 0
Security: 0
Stars: 59
Watchers: 7
Forks: 11
Open Issues: 0
Requires
- php: >=5.2
Requires (Dev)
- composer/installers: ~1.0
- phpunit/phpunit: ~4.0
- satooshi/php-coveralls: ~2.2
This package is auto-updated.
Last update: 2024-11-15 15:40:23 UTC
README
A PHP library for color manipulation in themes and plugins
ariColor
is a PHP library that will hopefully help WordPress theme developers do their job easier and more effectively.
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:
You have an option where users can define the background color for their <body>
. 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:
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:
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:
newColor
getNew
toCSS
newColor
Used to create a new object. Example:
$color = ariColor::newColor( 'rgba(0, 33, 176, .62)' );
The newColor
method has 2 arguments:
$color
: can accept any color value (see below for examples)$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
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:
$property
: can accept any of the properties listed above$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
Returns a CSS-formatted color value.
The toCSS
has a single argument:
$mode
: can accept any of the values listed below (defaults tohex
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:
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
composer update --dev ./vendor/bin/phpunit