README

coloreeze

A PHP library to deal with color conversions

[TOC]

Summary

Coloreeze is a PHP library to deal with color conversions.

Currently it supports the following color spaces:

Hexadecimal
Integer
RGB(a)
HSB/HSV
HSL
CMYK
CIELab
XYZ

Features

Additionally this library contains some useful methods to:

Generate a greyscale version from a color
Generate a darker version from a color
Generate a lighter version from a color
to create gradients and measure the distance CIE76 between colors.

Installation

You can install the package via composer:

$ composer require alcidesrc/coloreeze

Usage

Coloreeze package contains independent color classes, all of them implementing a Color interface:

ColorCIELab
ColorCMYK
ColorFactory
ColorHSB
ColorHSL
ColorHex
ColorInt
ColorRGBA
ColorXYZ

Color Factory

ColorFactory::fromString(string $input): Color

The ColorFactory class allows you to create a color instance from any valid input string.

If the input string is not a valid color representation it throws an InvalidInput exception.

ColorFactory::fromString('rgb(0,100,200)'); // Returns a `ColorRGBA` instance
ColorFactory::fromString('#336699'); // Returns a `ColorHex` instance
ColorFactory::fromString('unknown(1,2,3)'); // Throws an `InvalidInput` exception

Color Interface

__toString(): string

Cast the color value to a string:

echo ColorRGBA::fromString('rgba(0,100,200,1.0)');
echo ColorHex::fromString('#336699');

'rgba(0,100,200,1.0)'
'#336699'

fromString(string $input): Color

Parses an input string and returns accordingly the related Color implementation:

$hex = ColorHex::fromString('#336699');
$rgba = ColorRGBA::fromString('rgba(0,100,200,1.0)');
...

It throws an InvalidInput exception in case of the string is not well formed or unsupported color.

getValue(): mixed

Returns the Color value. On single-value colors, this method returns a primitive value (int or string) but on composite ones it returns an array with color's components:

$int = ColorInt::fromString('int(100)');
var_dump($int->getValue());

int(100)

$rgba = ColorRGBA::fromString('rgba(0, 100, 200)');
var_dump($int->getValue());

array(3) {
  [0]=>
  int(0)
  [1]=>
  int(100)
  [2]=>
  int(200)
}

$hex = ColorHex::fromString('#336699');
var_dump($int->getValue());

string(7) "#336699"

toCIELab(): ColorCIELab

Converts a color to a CIELab:

$lab = ColorHex::fromString('#336699')->toCIELab();

toCMYK(): ColorCMYK

Converts a color to a CMYK:

$cmyk = ColorHex::fromString('#336699')->toCMYK();

toHex(): ColorHex

Converts a color to a Hex:

$hex = ColorRGBA::fromString('rgba(100,200,200,1.0)')->toHex();

toHSB(): ColorHSB

Converts a color to a HSB/HSV:

$hsb = ColorHex::fromString('#336699')->toHSB();

toHSL(): ColorHSL

Converts a color to a HSL:

$hsl = ColorHex::fromString('#336699')->toHSL();

toInt(): ColorInt

Converts a color to an Int:

$int = ColorHex::fromString('#336699')->toInt();

toRGBA(): ColorRGBA

$rgba = ColorInt::fromString('int(255)')->toRGBA();

toXYZ(): ColorXYZ

$rgba = ColorCMYK::fromString('cmyk(0,0,0,0)')->toXYZ();

toComplementary(): Color

$complementary = ColorRGBA::fromString('hsl(182,25,50)')->toComplementary();

toGreyscale(): Color

$greyscale = ColorInt::fromString('int(4278255615)')->toGreyscale();

adjustBrightness(int $steps): Color

$dark = ColorInt::fromString('int(4278255615)')->adjustBrightness(-10);
$light = ColorInt::fromString('int(4278255615)')->adjustBrightness(10);

distanceCIE76(Color $color): float

$distance = ColorInt::fromString('int(4278255615)')->distanceCIE76(ColorInt::fromString('int(0)'));

Testing

You can run the test suite via composer:

$ composer tests

This Composer script runs the PHPUnit command with PCOV support in order to generate a Code Coverage report.

Unit Tests

This library provides a PHPUnit testsuite with 1434 unit tests and 2670 assertions:

Time: 00:00.426, Memory: 24.00 MB

OK (1434 tests, 2670 assertions)

Code Coverage

Here is the Code Coverage report summary:

Code Coverage Report:
  2022-07-22 06:32:15

 Summary:
  Classes: 100.00% (11/11)
  Methods: 100.00% (135/135)
  Lines:   100.00% (475/475)

Full report will be generated in ./reports/coverage folder.

QA

Static Analyzer

You can check this library with PHPStan:

$ composer phpstan

This command generates the following report:

> vendor/bin/phpstan analyse --level 9 --memory-limit 1G --ansi ./src ./tests
 29/29 [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100%

 [OK] No errors

PHP Parallel Lint

You can check this library with PHP Parallel Lint:

$ composer linter