nabeghe / colory

v1.0.0 2026-09-27 21:41 UTC

Requires

• php: >=7.1

Requires (Dev)

• phpunit/phpunit: ^9.5 || ^10.0 || ^11.0 || ^12.0 || ^13.0

MIT

• Hadi Akbarzadeh

• library
• color
• helper
• rgb
• hsl
• hsv
• palette
• hex
• wcag
• contrast
• colory
• color-helper
• color-converter
• color-manipulation

Published on Packagist.org on 2026-09-27 21:45 UTC

README

Simple yet powerful color helper & manipulation library for PHP with HEX, RGB, HSL, HSV, alpha, WCAG contrast, and CSS support.

🚀 Installation

You can install the package via Composer:

composer require nabeghe/colory

🎨 Quick Start

Colory supports both a Fluent Object-Oriented API and Static Utility Methods.

1. Fluent Interface (Immutable)

use Nabeghe\Colory\Colory;

// Create color from HEX, RGB, HSL, or CSS string
$color = Colory::make('#3498DB');

echo $color->toHex();         // #3498DB
echo $color->toRgbCss();      // rgb(52, 152, 219)
echo $color->toHslCss();      // hsl(204, 70%, 53%)

// Manipulation (returns a new instance, immutable)
$darker = $color->darken(15);
echo $darker->toHex();        // #1F6B9E

// Contrast & WCAG Accessibility
if ($color->isDark()) {
    $textColor = '#FFFFFF';
} else {
    $textColor = '#000000';
}

// Or automatically pick the most readable text color:
$textColor = $color->contrastColor(); // #FFFFFF or #000000

2. Static Utility Methods

use Nabeghe\Colory\Colory;

// Conversions
$rgb = Colory::hexToRgb('#FF5733'); // ['r' => 255, 'g' => 87, 'b' => 51]
$hex = Colory::rgbToHex($rgb);      // #FF5733

// HSL & HSV
$hsl = Colory::rgbToHsl($rgb);      // ['h' => 11, 's' => 100, 'l' => 60]
$hsv = Colory::rgbToHsv($rgb);      // ['h' => 11, 's' => 80, 'v' => 100]

// Invert
$inverted = Colory::invertHex('#FF5733'); // #00A8CC

// WCAG Contrast Ratio
$ratio = Colory::contrastRatio('#FFFFFF', '#000000'); // 21.0

📖 Feature Overview

1. Universal Parsing (Colory::parse)

Accepts virtually any color format and normalizes it to an RGB array:

Colory::parse('#3498DB');              // 6-digit hex
Colory::parse('#FFF');                  // 3-digit hex
Colory::parse('#3498DB80');            // 8-digit hex (with alpha)
Colory::parse('rgb(52, 152, 219)');    // CSS rgb()
Colory::parse('rgba(52, 152, 219, 0.5)'); // CSS rgba()
Colory::parse('hsl(204, 70%, 53%)');   // CSS hsl()
Colory::parse('tomato');                // CSS named color
Colory::parse([52, 152, 219]);         // Indexed array [r, g, b]
Colory::parse(['r' => 52, 'g' => 152, 'b' => 219]); // Assoc array

2. Color Conversions

Convert seamlessly between HEX, RGB, HSL, HSV, and CSS:

// RGB <-> HEX
Colory::rgbToHex(['r' => 255, 'g' => 99, 'b' => 71]); // #FF6347
Colory::hexToRgb('#FF6347');                         // ['r' => 255, 'g' => 99, 'b' => 71]

// RGB <-> HSL
Colory::rgbToHsl(['r' => 255, 'g' => 0, 'b' => 0]);  // ['h' => 0, 's' => 100, 'l' => 50]
Colory::hslToRgb(['h' => 0, 's' => 100, 'l' => 50]); // ['r' => 255, 'g' => 0, 'b' => 0]

// CSS strings
Colory::rgbToCss(['r' => 255, 'g' => 0, 'b' => 0, 'a' => 0.8]); // rgba(255, 0, 0, 0.8)
Colory::hslToCss(['h' => 120, 's' => 100, 'l' => 50]);         // hsl(120, 100%, 50%)

3. Color Manipulation

Easily adjust colors dynamically:

$color = Colory::make('#3498DB');

$lighter    = $color->lighten(10);     // Lighten by 10%
$darker     = $color->darken(10);      // Darken by 10%
$saturated  = $color->saturate(20);    // Saturate by 20%
$desaturated= $color->desaturate(20);  // Desaturate by 20%
$grayscale  = $color->grayscale();     // Complete desaturation
$faded      = $color->fade(0.5);       // Set alpha to 50%
$mixed      = $color->mix('#E74C3C', 50); // Blend 50/50 with another color

Static equivalents are also available: Colory::lighten($color, 10), Colory::darken(...), Colory::mix(...), etc.

4. WCAG Accessibility & Contrast

Make sure your colors are readable and pass accessibility standards:

// Check relative luminance (0.0 to 1.0)
$lum = Colory::luminance('#3498DB');

// Dark or Light detection
Colory::isDark('#1E1E1E');  // true
Colory::isLight('#FAFAFA'); // true

// WCAG Contrast Ratio (1.0 to 21.0)
$ratio = Colory::contrastRatio('#000000', '#FFFFFF'); // 21.0

// Automatic text color recommendation (black or white)
$textColor = Colory::contrastColor('#3498DB'); // '#FFFFFF'

// Verify WCAG readability level ('AA', 'AAA', 'AA-large', 'AAA-large')
$readable = Colory::isReadable('#000000', '#FFFFFF', 'AAA'); // true

5. Harmonies & Palette Generation

Generate cohesive color palettes with a single call:

$color = Colory::make('#E74C3C');

$complementary = $color->complementary(); // Complementary color (+180°)
$triadic       = $color->triadic();       // 3 colors (+0°, +120°, +240°)
$analogous     = $color->analogous(30);   // 3 colors (-30°, 0°, +30°)
$tetradic      = $color->tetradic();      // 4 colors (+0°, +90°, +180°, +270°)

// Gradient steps between two colors:
$palette = Colory::steps('#3498DB', '#E74C3C', 5);
// Returns an array of 5 interpolated colors

6. Random Colors

Generate random colors in various formats:

Colory::randomHex();                 // e.g. '#A3C9E2'
Colory::randomHex(true);             // e.g. '#A3C9E280' (with alpha)
Colory::randomHex(false, false);     // e.g. 'A3C9E2' (without #)

Colory::randomRgb();                 // ['r' => 120, 'g' => 45, 'b' => 200]
Colory::randomRgb(true);             // with alpha: ['r' => ..., 'a' => 0.65]

Colory::randomRgbCss();              // "rgba(120, 45, 200)"
Colory::randomHsl();                 // ['h' => 210, 's' => 75, 'l' => 60]
Colory::randomHslCss();              // "hsl(210, 75%, 60%)"

🧪 Testing

Run the test suite using PHPUnit:

composer test
# or
./vendor/bin/phpunit

📖 License

Licensed under the MIT License. See LICENSE.md for details.