PHPackages konradmichalik/php-color - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. konradmichalik/php-color ActiveLibrary[Utility & Helpers](/categories/utility) konradmichalik/php-color ======================== A small, framework-agnostic PHP library for color conversion, luminance, contrast and deterministic string-to-color hashing. 0.2.0(today)0206↑2637.9%GPL-2.0-or-laterPHPPHP ~8.2.0 || ~8.3.0 || ~8.4.0 || ~8.5.0CI passing Since Jun 19Pushed todayCompare [ Source](https://github.com/konradmichalik/php-color)[ Packagist](https://packagist.org/packages/konradmichalik/php-color)[ RSS](/packages/konradmichalik-php-color/feed)WikiDiscussions main Synced today READMEChangelog (2)Dependencies (7)Versions (5)Used By (0) Color ===== [](#color) [![Coverage](https://camo.githubusercontent.com/a1dc762a0c2870201a3fbe9ee70753407b13787bb4270778695531f52826bd4b/68747470733a2f2f696d672e736869656c64732e696f2f636f766572616c6c73436f7665726167652f6769746875622f6b6f6e7261646d696368616c696b2f7068702d636f6c6f723f6c6f676f3d636f766572616c6c73)](https://coveralls.io/github/konradmichalik/php-color)[![CGL](https://camo.githubusercontent.com/31102db52094e1e771a8c43e3eff944aa65863d4a1b079683b98da20a422cbe8/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6b6f6e7261646d696368616c696b2f7068702d636f6c6f722f63676c2e796d6c3f6c6162656c3d63676c266c6f676f3d676974687562)](https://github.com/konradmichalik/php-color/actions/workflows/cgl.yml)[![Tests](https://camo.githubusercontent.com/a8d061eb543376c62bc84b144ff3381814d516e37f97a95accfc05b28ecbdd33/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6b6f6e7261646d696368616c696b2f7068702d636f6c6f722f74657374732e796d6c3f6c6162656c3d7465737473266c6f676f3d676974687562)](https://github.com/konradmichalik/php-color/actions/workflows/tests.yml)[![Supported PHP Versions](https://camo.githubusercontent.com/d313a19f99a996680e2d423d2390ed9fccfd74cdc388d17e162b1cc139b9e48e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646570656e64656e63792d762f6b6f6e7261646d696368616c696b2f7068702d636f6c6f722f7068703f6c6f676f3d706870)](https://packagist.org/packages/konradmichalik/php-color)[![License](https://camo.githubusercontent.com/e9c5c69a6c237e40b1ff4594b56365d49639e9f5a109c57336c0ccd9b9eae2ca/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6b6f6e7261646d696368616c696b2f7068702d636f6c6f72)](LICENSE) A small, **framework-agnostic** PHP library for color conversion, luminance, contrast and deterministic string-to-color hashing. No runtime dependencies. 🚀 Features ---------- [](#-features) - Immutable `Color` value object with `Rgb` and `Hsl` companions - Lossless conversion between hex, RGB and HSL - Multi-format string parsing via `fromString()` / `tryFromString()` - CSS `rgb()` / `rgba()` output with optional alpha channel - WCAG 2.x relative luminance and contrast ratio - `optimalTextColor()` — pick readable text color for any background - Deterministic string → color hashing (SHA-256/HSL or CRC32) 🔥 Installation -------------- [](#-installation) [![Packagist](https://camo.githubusercontent.com/faa491a355cdef584a6d118697685736dcb13b87f1cfd1e686ecbb188756215d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6b6f6e7261646d696368616c696b2f7068702d636f6c6f723f6c6162656c3d76657273696f6e266c6f676f3d7061636b6167697374)](https://packagist.org/packages/konradmichalik/php-color)[![Packagist Downloads](https://camo.githubusercontent.com/ce9f338a85f1371ae39356c1143cd4b34f0f7ff4fc58dacbc0f499be562ba062/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6b6f6e7261646d696368616c696b2f7068702d636f6c6f723f636f6c6f723d627269676874677265656e)](https://packagist.org/packages/konradmichalik/php-color) ``` composer require konradmichalik/php-color ``` ⚡ Usage ------- [](#-usage) ### Conversion [](#conversion) ``` use KonradMichalik\Color\Color; $color = Color::fromHex('#3366cc'); $color->toRgb(); // Rgb(51, 102, 204) $color->toHsl(); // Hsl(220.0, 60.0, 50.0) $color->toHex(); // "#3366cc" Color::fromRgb(51, 102, 204)->toHex(); // "#3366cc" Color::fromHsl(220, 60, 50)->toHex(); // "#3366cc" $color->withLightness(85)->toHex(); // a lighter variant (HSL space) $color->scaleRgb(0.5)->toHex(); // halve each RGB channel → "#1a3366" $color->darken(0.5)->toHex(); // alias for scaleRgb() ``` `scaleRgb()` multiplies every RGB channel by the factor (clamped to `0–255`), while `withLightness()` works in HSL space — use `scaleRgb()` for plain per-channel brightness math. `darken()` is an alias. Factors below `0.0` throw `InvalidColorValue`: ``` use KonradMichalik\Color\ColorHasher; ColorHasher::crc32()->hash($string)->scaleRgb(0.5)->toHex(); // darkened avatar color ``` Short hex (`#abc`), missing `#` and surrounding whitespace are all accepted. Invalid values throw `KonradMichalik\Color\Exception\InvalidColorValue`. ### Parsing arbitrary strings [](#parsing-arbitrary-strings) `fromString()` accepts hex, `rgb(r, g, b)` and `hsl(h, s%, l%)` in one call — whitespace is ignored, prefixes are case-insensitive and the HSL percent signs are optional: ``` Color::fromString('#ff0000'); // red Color::fromString('f00'); // red Color::fromString('rgb(255, 0, 0)'); // red Color::fromString('hsl(0, 100%, 50%)'); // red Color::fromString('HSL(0,100,50)'); // red ``` Use `tryFromString()` for fallbacks — it returns `null` instead of throwing: ``` Color::tryFromString($userInput) ?? Color::fromHex('#cccccc'); ``` ### CSS output with alpha [](#css-output-with-alpha) ``` $rgb = Color::fromHex('#ff0000')->toRgb(); $rgb->toCssString(); // "rgb(255, 0, 0)" $rgb->toCssString(0.8); // "rgba(255, 0, 0, 0.8)" Color::fromHex('#ff0000')->toRgbaString(0.8); // "rgba(255, 0, 0, 0.8)" ``` The model stays RGB-only; alpha is an output concern. Values outside `0.0–1.0`throw `KonradMichalik\Color\Exception\InvalidColorValue`. ### Contrast & readable text [](#contrast--readable-text) ``` $background = Color::fromHex('#222222'); $background->relativeLuminance(); // 0.0185… $background->contrastRatio(Color::fromHex('#fff')); // 15.9… $background->isDark(); // true $background->optimalTextColor()->toHex(); // "#ffffff" ``` `optimalTextColor()` returns whichever candidate (black/white by default, or two custom colors) has the higher contrast against the background. ### Deterministic colors from strings [](#deterministic-colors-from-strings) Great for avatar backgrounds or tag colors — the same input always yields the same color: ``` use KonradMichalik\Color\ColorHasher; $hasher = ColorHasher::hsl(); // balanced SHA-256 → HSL (recommended) $hasher->hash('konrad@example.com'); // stable Color $hasher = ColorHasher::hsl(saturation: 70, lightness: 45); $hasher = ColorHasher::crc32(); // lightweight CRC32 → hex ``` Need a custom mapping? Implement `KonradMichalik\Color\Hashing\HashStrategy` and pass it to `new ColorHasher($strategy)`. 🧑‍💻 Contributing ---------------- [](#‍-contributing) Please have a look at [`CONTRIBUTING.md`](CONTRIBUTING.md). 📄 License --------- [](#-license) This project is licensed under [GPL-2.0-or-later](LICENSE). ### Health Score 44 — FairBetter than 91% of packages Maintenance100 Actively maintained with recent releases Popularity16 Limited adoption so far Community6 Small or concentrated contributor base Maturity44 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~0 days Total 2 Last Release 0d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/11557705846f24da32a0e6e75c460db505c1b847f081ddaa3d27f3ea27f4097b?d=identicon)[konradmichalik](/maintainers/konradmichalik) --- Top Contributors [![konradmichalik](https://avatars.githubusercontent.com/u/4558190?v=4)](https://github.com/konradmichalik "konradmichalik (22 commits)") --- Tags colorcontrasthslluminancephprgbcolorrgbhexwcaghslluminancecontrast ### Code Quality TestsPHPUnit Static AnalysisPHPStan, Rector Type Coverage Yes ### Embed Badge ![Health badge](/badges/konradmichalik-php-color/health.svg) ``` [![Health](https://phpackages.com/badges/konradmichalik-php-color/health.svg)](https://phpackages.com/packages/konradmichalik-php-color) ``` ### Alternatives [ssnepenthe/color-utils A PHP library for performing SASS-like color manipulations. 631.2M15](/packages/ssnepenthe-color-utils)[ozdemirburak/iris PHP library for color manipulation and conversion. 1201.8M20](/packages/ozdemirburak-iris)[spatie/color A little library to handle color conversions 38220.5M34](/packages/spatie-color)[tecnickcom/tc-lib-color PHP library to manipulate various color representations 247.7M20](/packages/tecnickcom-tc-lib-color)[fjw/color-compare A library for converting colors (Hex, RGB, HSL, CIELAB (LAB), DIN-99) and calculating color distances based on DIN-99. 1310.4k](/packages/fjw-color-compare)[davidgorges/color-contrast A tiny library to find color combinations with a contrast threshold 10558.8k](/packages/davidgorges-color-contrast) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)