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

This command generates the following report:

PHP 8.1.8 | 10 parallel jobs
.............................                                29/29 (100 %)
Checked 29 files in 0.1 seconds
No syntax error found

PHP Insights

You can check this library with PHP Insights:

$ composer phpinsights

This command generates the following summary:

> ./vendor/bin/phpinsights --fix

 16/16 [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100%

 ✨ Analysis Completed !

[2022-07-22 08:20:20] `/code`

                99.0%                  89.5%                  94.1%                  100 %
                Code                 Complexity            Architecture              Style

Score scale: ◼ 1-49 ◼ 50-79 ◼ 80-100

[CODE] 99 pts within 494 lines

Comments ....................................................... 5.1 %
Classes ....................................................... 85.6 %
Functions ...................................................... 0.0 %
Globally ....................................................... 9.3 %

[COMPLEXITY] 89.5 pts with average of 1.32 cyclomatic complexity

[ARCHITECTURE] 94.1 pts within 13 files

Classes ....................................................... 84.6 %
Interfaces ..................................................... 7.7 %
Globally ....................................................... 7.7 %
Traits ......................................................... 0.0 %

[MISC] 100 pts on coding style and 0 security issues encountered

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities:

PLEASE DON'T DISCLOSE SECURITY-RELATED ISSUES PUBLICLY

Supported Versions

Only the latest major version receives security fixes.

Reporting a Vulnerability

If you discover a security vulnerability within this project, please open an issue here. All security vulnerabilities will be promptly addressed.

License

The MIT License (MIT). Please see License File for more information.