Search by

oceanmoon / color

mossy2100

Immutable PHP Color class with RGB/HSL support, CSS color names, and WCAG accessibility features.

Package info

github.com/mossy2100/PHP-Color

pkg:composer/oceanmoon/color

Statistics

Installs: 0

Dependents: 0

Suggesters: 0

Stars: 1

Open Issues: 0

v2.0.0 2026-06-18 00:24 UTC

This package is auto-updated.

Last update: 2026-11-11 22:05:14 UTC


README

An immutable Color class for PHP with support for RGB and HSL color spaces, CSS color names, and WCAG accessibility features.

License | Changelog | Documentation

PHP 8.4

Description

This package provides a comprehensive Color class for working with colors in PHP. The class is designed to be:

  • Immutable - Color values cannot be changed after creation, so a color can be shared safely
  • Simple - The RGBA components are read-only int properties, and HSL values are computed on first use
  • Feature-rich - Supports RGB, HSL, hex strings, CSS and extra color names, and accessibility calculations
  • CSS-compatible - Outputs to modern CSS color formats (hex, rgb, hsl)

Development and Quality Assurance

This package was developed with Claude Code:

  • The author developed the initial concept, designed the public API, and did most of the initial coding.
  • Claude Code wrote the tests and most of the documentation.
  • Claude Code also assisted with multiple code reviews, which led to bug fixes, performance improvements and other refinements.

The code is checked with:

Code Coverage

Requirements

  • PHP ^8.4
  • ext-ctype
  • ext-intl, through mossy2100/core, for toRgbString() and toHslString()
  • mossy2100/core

Installation

composer require mossy2100/color

Quick Start

use Mossy2100\Color\Color;

// Create colors from various formats
$red = Color::fromString('red');
$blue = Color::fromString('#0000ff');
$purple = new Color(128, 0, 255);           // Bytes [0, 255]
$orange = Color::fromRgba(100, 50, 0);      // Percentages [0, 100], as in CSS rgb()
$green = Color::fromHsla(120, 100, 50);     // Degrees and percentages, as in CSS hsl()

// Access color properties
$color = Color::fromString('#ff6600');
$color->red;         // 255
$color->hue;         // 24.0
$color->lightness;   // 50.0

// Modify colors (returns new instance)
$darkRed = $red->withLightness(30);
$transparent = $red->withAlpha(50, percent: true);

// Color operations
$mixed = $red->mix($blue, 50);
$complement = $red->complement();

// Accessibility
$textColor = $color->bestTextColor();       // Color for black or white
$ratio = $red->contrastRatio($blue);

// Output formats
echo $color->toHex();        // '#ff6600ff'
echo $color->toRgbString();  // 'rgb(255 102 0 / 100%)'
echo $color->toHslString();  // 'hsl(24deg 100% 50% / 100%)'

Classes

Color

Immutable class for color manipulation with support for:

  • RGB and HSL color spaces with automatic conversion
  • CSS color names (148 standard names plus 'transparent'), and around 300 extra color names
  • Hex string parsing (3, 4, 6, or 8 digits)
  • Immutable modification methods (withRed, withHue, etc.)
  • Color mixing and complementary colors
  • WCAG accessibility calculations (contrast ratio, text color selection)
  • Multiple output formats (hex, rgb(), hsl())

ColorNames

The CSS named colors and around 300 extra color names, mapped to hex values, with the name lookup Color uses.

Testing

The library includes comprehensive test coverage:

# Run all tests
vendor/bin/phpunit

# Run with coverage (generates HTML report and clover.xml)
composer test

License

MIT License - see LICENSE for details

Support

For questions or suggestions, please open an issue.

Changelog

See CHANGELOG.md for version history and changes.