PHPackages                             wwaz/colorservice-php - 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. wwaz/colorservice-php

ActiveLibrary[Utility & Helpers](/categories/utility)

wwaz/colorservice-php
=====================

Bridge screen RGB and print CMYK using ICC profiles — with perception preview, color names, and schemes.

v1.0.0(1mo ago)01MITPHPPHP ^8.2CI passing

Since Jul 3Pushed 1mo agoCompare

[ Source](https://github.com/WWAZ/colorservice-php)[ Packagist](https://packagist.org/packages/wwaz/colorservice-php)[ Docs](https://github.com/WWAZ/colorservice-php)[ RSS](/packages/wwaz-colorservice-php/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (1)Dependencies (5)Versions (2)Used By (0)

Color Service PHP
=================

[](#color-service-php)

Convert colors between RGB and CMYK using real ICC profiles, not just math formulas.

This library is useful when screen colors and print colors should match as closely as possible. It also returns a perception preview, a color name, contrast helpers, and optional color schemes.

Input types: `rgb`, `cmyk`, `hex`.

---

Installation
------------

[](#installation)

```
composer require wwaz/colorservice-php
```

Dependencies:

- `wwaz/colorconvert-php`
- `wwaz/colorprofile-php`
- `wwaz/colormodel-php`
- `wwaz/colorname-php`

### ICC Profiles Setup

[](#icc-profiles-setup)

Profile names like `sRGB_v4_ICC_preference` are resolved through `wwaz/colorprofile-php`. Before first use, install the profiles once:

```
vendor/bin/colorprofile init
vendor/bin/colorprofile install sRGB_v4_ICC_preference ISOcoated_v2_300_eci
```

---

Quick Start
-----------

[](#quick-start)

Use `ColorService` when you receive colors as strings and want the full result with profiles, perception preview, and names.

```
use wwaz\ColorService\ColorService;

$service = new ColorService(
    rgbProfile: 'sRGB_v4_ICC_preference',
    cmykProfile: 'ISOcoated_v2_300_eci',
);

$result = $service->ICCConvert('255,0,0');

echo $result->hex();        // e.g. "#FF0000"
echo $result->rgb();        // "255,0,0"
echo $result->cmyk();       // profiled CMYK values
echo $result->perception(); // screen preview after the ICC roundtrip
echo $result->name();       // closest color name
```

Accepted string formats:

- HEX: `f00`, `#ff0000`, `009EE3`
- RGB: `255,0,0`
- CMYK: `0,100,100,0`

You can also pass color objects:

```
use wwaz\ColorService\Color\CMYK;

$result = $service->ICCConvert(new CMYK('0,100,100,0'));
```

---

Use Cases
---------

[](#use-cases)

### 1. Convert Screen RGB to Print CMYK

[](#1-convert-screen-rgb-to-print-cmyk)

```
$result = $service->ICCConvert('255,0,0');

echo $result->cmyk();
echo $result->perception();
```

### 2. Convert Print CMYK Back to Screen RGB

[](#2-convert-print-cmyk-back-to-screen-rgb)

```
$result = $service->ICCConvert('53,0,60,29');

echo $result->rgb();
echo $result->hex();
echo $result->name();
```

### 3. Convert Multiple Colors

[](#3-convert-multiple-colors)

```
$results = $service->ICCConvertBatch([
    'f00',
    '255,255,0',
    '100,0,0,0',
    '009EE3',
]);
```

### 4. Generate Color Schemes

[](#4-generate-color-schemes)

Generate complementary, triadic, analogous, square, tetradic, tint, shade, tone, and hue palettes.

```
$schemes = $service->schemes('0,158,227');

$complementary = $schemes['complementary'];
$firstSwatch = $complementary[0];

echo $firstSwatch['hex'];
echo $firstSwatch['rgb'];
echo $firstSwatch['cmyk'];
```

To read one named scheme:

```
$tints = $service->schema('0,158,227', 'tint');
```

### 5. Text Color and Lightness Helpers

[](#5-text-color-and-lightness-helpers)

```
$service->isLight('ffffff');                     // true
$service->isDark('000000');                      // true
$service->getReadableTextColor('009EE3');            // "#000000" or "#FFFFFF"
$service->getReadableTextColorKeepingHue('009EE3', 2.1); // adjusted HEX text color
```

---

Lower-Level Conversion
----------------------

[](#lower-level-conversion)

Use `ColorConversionService` when you already have a color model and need control over DTO version, profiles, intent, or scheme inclusion.

```
use wwaz\ColorService\Color\RGB;
use wwaz\ColorService\Processing\ColorConversionService;

$conversion = new ColorConversionService(new RGB('255,0,0'));
$conversion->setProfile('rgb', 'sRGB_v4_ICC_preference');
$conversion->setProfile('cmyk', 'ISOcoated_v2_300_eci');
$conversion->setIntent('perceptual');

$result = $conversion->convert();
```

Include schemes directly in the V2 result:

```
$result = (new ColorConversionService(new RGB('0,158,227')))
    ->withIncludeSchemes()
    ->profiled(
        rgbProfile: 'sRGB_v4_ICC_preference',
        cmykProfile: 'ISOcoated_v2_300_eci',
    );

$data = $result->toArray();
```

Return the legacy V1 DTO shape:

```
$conversion->setAcceptICCConversionDTO('v1');
$legacyResult = $conversion->convert();
```

---

ICC Conversion Only
-------------------

[](#icc-conversion-only)

Use `IccColorConverter` when you only need RGB ↔ CMYK conversion, without names, DTOs, metrics, or schemes.

```
use wwaz\ColorService\Color\CMYK;
use wwaz\ColorService\Color\RGB;
use wwaz\ColorService\Processing\IccColorConverter;

$converter = new IccColorConverter();
$converter->setProfile('rgb', 'sRGB_v4_ICC_preference');
$converter->setProfile('cmyk', 'ISOcoated_v2_300_eci');

$cmyk = $converter->rgbToCmyk(new RGB('255,0,0'));
$rgb = $converter->cmykToRgb(new CMYK('0,100,100,0'));
```

Batch helpers are available:

```
$cmyks = $converter->rgbToCmykBatch([
    new RGB('255,0,0'),
    new RGB('0,158,227'),
]);
```

---

Main Classes
------------

[](#main-classes)

ClassWhen to use`ColorService`String-friendly facade for apps, controllers, and APIs`ColorConversionService`Full conversion workflow for color model objects`IccColorConverter`Low-level RGB ↔ CMYK conversion only`ColorMetrics`Lightness, contrast, and readable text color helpers`ICCConversionResultV2`Default slim conversion result`ICCConversionResultV1`Legacy detailed conversion result---

Rendering Intent
----------------

[](#rendering-intent)

The rendering intent tells the ICC engine how to map colors when the source and target profile cannot represent the same colors.

Supported values:

- `relative` (default)
- `perceptual`
- `saturation`
- `absolute`

```
$service = new ColorService(
    rgbProfile: 'sRGB_v4_ICC_preference',
    cmykProfile: 'ISOcoated_v2_300_eci',
    intent: 'perceptual',
);
```

### Which Intent Should I Use?

[](#which-intent-should-i-use)

IntentBest forWhat it does in practice`relative`Everyday print prep, logos, layouts, brand colorsKeeps neutral grays stable and adjusts other colors relative to white. Usually the safest default.`perceptual`Photos, gradients, images, smooth backgroundsCompresses the whole color range so the image still looks natural.`saturation`Charts, infographics, bold graphicsTries to keep vivid colors strong, even if hue and lightness shift a bit.`absolute`Proofing and strict simulationMaps colors more literally to the destination profile. Useful for color-accurate previews.If no ICC profiles are set on the lower-level services, the library falls back to math conversion and the intent has no visible effect.

---

Result Structures
-----------------

[](#result-structures)

### Default V2 Result

[](#default-v2-result)

`ICCConversionResultV2::toArray()` returns a slim payload:

```
[
    'given' => [
        'colorSpace' => 'rgb',
        'representation' => 'rgb',
        'value' => '255,0,0',
    ],
    'hex' => '#FF0000',
    'rgb' => '255,0,0',
    'cmyk' => '0,100,100,0',
    'perception' => '#EF0000',
    'name' => 'Red',
    'schemes' => [], // only when requested
]
```

Helper methods:

```
$result->hex();
$result->rgb();
$result->cmyk();
$result->perception();
$result->name();
$result->toArray();
```

### Legacy V1 Result

[](#legacy-v1-result)

Pass `acceptICCConversionDTO: 'v1'` to `ColorService` or call `setAcceptICCConversionDTO('v1')` on `ColorConversionService`.

The V1 payload includes `values`, `perception`, `profiled`, `inField`, `colorWorkSpace`, `intent`, and `conversionStack`.

```
$service = new ColorService(
    rgbProfile: 'sRGB_v4_ICC_preference',
    cmykProfile: 'ISOcoated_v2_300_eci',
    acceptICCConversionDTO: 'v1',
);

$result = $service->ICCConvert('255,0,0');

echo $result->hexPerception();
echo $result->givenValue();
```

---

Error Handling
--------------

[](#error-handling)

- Unknown profile name: `InvalidArgumentException`
- Unknown color type: `InvalidArgumentException`
- Unknown scheme name: `InvalidArgumentException`
- Invalid color values: validated by `wwaz/colormodel-php`

---

Important Note About Concurrency
--------------------------------

[](#important-note-about-concurrency)

`IccColorConverter` uses the global engine state from `wwaz/colorconvert-php`. For parallel work, use one converter instance per request or workflow.

---

Tests
-----

[](#tests)

```
composer install
vendor/bin/colorprofile init
vendor/bin/colorprofile install sRGB_v4_ICC_preference ISOcoated_v2_300_eci
composer test
```

When running inside the cooler monorepo, existing root profiles are picked up automatically.

---

Laravel
-------

[](#laravel)

For a ready-made Laravel integration, see [`wwaz/cooler`](https://github.com/WWAZ/cooler).

The library itself has no `config()` or `env()` calls. Pass profile names and intent explicitly through `ColorService` or configure them on `ColorConversionService`.

---

License
-------

[](#license)

MIT, see [LICENSE](LICENSE).

###  Health Score

38

—

LowBetter than 83% of packages

Maintenance90

Actively maintained with recent releases

Popularity1

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity46

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

Unknown

Total

1

Last Release

49d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/25566288?v=4)[WWAZ](/maintainers/WWAZ)[@WWAZ](https://github.com/WWAZ)

---

Top Contributors

[![WWAZ](https://avatars.githubusercontent.com/u/25566288?v=4)](https://github.com/WWAZ "WWAZ (3 commits)")

---

Tags

colorrgbcmykcolor-profileicccolor-schemescolor-service

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/wwaz-colorservice-php/health.svg)

```
[![Health](https://phpackages.com/badges/wwaz-colorservice-php/health.svg)](https://phpackages.com/packages/wwaz-colorservice-php)
```

###  Alternatives

[spatie/color

A little library to handle color conversions

38222.1M40](/packages/spatie-color)[ozdemirburak/iris

PHP library for color manipulation and conversion.

1221.9M24](/packages/ozdemirburak-iris)[tecnickcom/tc-lib-color

PHP library to manipulate various color representations

248.3M32](/packages/tecnickcom-tc-lib-color)[ssnepenthe/color-utils

A PHP library for performing SASS-like color manipulations.

631.2M17](/packages/ssnepenthe-color-utils)[fjw/color-compare

A library for converting colors (Hex, RGB, HSL, CIELAB (LAB), DIN-99) and calculating color distances based on DIN-99.

1311.1k](/packages/fjw-color-compare)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)