README

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

License | Changelog | Documentation

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, ensuring predictability and thread safety
• Memory-efficient - Colors are stored internally as a 4-byte binary string
• Feature-rich - Supports RGB, HSL, hex strings, CSS color names, and accessibility calculations
• CSS-compatible - Outputs to modern CSS color formats (hex, rgb, hsl)

Development and Quality Assurance / AI Disclosure

Claude Chat and Claude Code were used in the development of this package. The core classes were designed, coded, and commented primarily by the author, with Claude providing substantial assistance with code review, suggesting improvements, debugging, and generating tests and documentation. All code was thoroughly reviewed by the author, and validated using industry-standard tools including PHP_Codesniffer, PHPStan (to level 9), and PHPUnit to ensure full compliance with PSR-12 coding standards and comprehensive unit testing with 100% code coverage. This collaborative approach resulted in a high-quality, thoroughly-tested, and well-documented package delivered in significantly less time than traditional development methods.

Requirements

• PHP ^8.4
• ext-ctype
• galaxon/core

Installation

composer require galaxon/color

Quick Start

use Galaxon\Color\Color;

// Create colors from various formats
$red = new Color('red');
$orange = new Color('#ff8000');
$purple = Color::fromRgba(128, 0, 255);
$green = Color::fromHsla(120, 1.0, 0.5);

// Access color properties
$color = new Color('#ff8040');
$color->red;         // 255
$color->hue;         // 20.0
$color->lightness;   // 0.625

// Modify colors (returns new instance)
$darkRed = $red->withLightness(0.3);
$transparent = $red->withAlpha(128);

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

// Accessibility
$textColor = $background->bestTextColor();  // 'black' or 'white'
$ratio = $color1->contrastRatio($color2);

// Output formats
echo $color->toHex();        // '#ff8040ff'
echo $color->toRgbString();  // 'rgb(255 128 64 / 1)'
echo $color->toHslString();  // 'hsl(20deg 100% 62.5% / 1)'

Classes

Color

Immutable class for color manipulation with support for:

• RGB and HSL color spaces with automatic conversion
• CSS color names (147 standard names plus 'transparent')
• 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())

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

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

For questions or suggestions, please open an issue.

Support

• Issues: https://github.com/mossy2100/Galaxon-PHP-Color/issues
• Documentation: See docs/ directory for detailed class documentation
• Examples: See test files for comprehensive usage examples

Changelog

See CHANGELOG.md for version history and changes.