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

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

wwaz/colorbridge-php
====================

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

v1.0.0(today)00MITPHPPHP ^8.2CI passing

Since Jul 1Pushed todayCompare

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

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

Color Bridge PHP
================

[](#color-bridge-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** (what the color may look like after a print roundtrip), a color name, and optional color schemes.

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

---

Use cases
---------

[](#use-cases)

### 1. Turn a screen color into print-ready CMYK

[](#1-turn-a-screen-color-into-print-ready-cmyk)

You have an RGB color from a website or design tool. You need CMYK values for a print workflow.

```
use wwaz\ColorBridge\Color\RGB;
use wwaz\ColorBridge\Bridge\Bridge;

$bridge = new Bridge(new RGB('255,0,0'));

$result = $bridge->profiled(
    rgbProfile: 'sRGB_v4_ICC_preference',
    cmykProfile: 'ISOcoated_v2_300_eci',
);

echo $result->cmyk();           // e.g. "0,100,100,0"
echo $result->hexPerception();  // how it may look on screen after conversion
```

### 2. Convert a print color back to RGB for the screen

[](#2-convert-a-print-color-back-to-rgb-for-the-screen)

A designer gives you CMYK values from a print proof. You want to show them on a website.

```
use wwaz\ColorBridge\Color\CMYK;
use wwaz\ColorBridge\Bridge\Bridge;

$bridge = new Bridge(new CMYK('53,0,60,29'));
$bridge->setProfile('rgb', 'sRGB_v4_ICC_preference');
$bridge->setProfile('cmyk', 'ISOcoated_v2_300_eci');

$data = $bridge->convert()->toArray();

echo $data['perception']['hex']; // screen preview
echo $data['name'];              // closest color name
```

### 3. Build a color picker API from request strings

[](#3-build-a-color-picker-api-from-request-strings)

You receive color type, value, and profile names from an HTTP request. Pass explicit values, or rely on `BridgeConfig` defaults.

```
use wwaz\ColorBridge\BridgeConfig;
use wwaz\ColorBridge\BridgeService;

$config = BridgeConfig::fromArray([
    'workingColorSpaces' => [
        'rgb' => 'sRGB_v4_ICC_preference',
        'cmyk' => 'ISOcoated_v2_300_eci',
    ],
    'defaultIntent' => 'relative',
]);

$service = new BridgeService(
    colortype: 'hex',
    colorvalue: 'f00',
    rgbProfile: 'sRGB_v4_ICC_preference',
    cmykProfile: 'ISOcoated_v2_300_eci',
    intent: 'relative',
    config: $config,
);

$response = $service->convert()->toArray();
```

Or omit profiles entirely and use library defaults:

```
$service = new BridgeService(colortype: 'hex', colorvalue: 'f00');
```

### 4. Return color schemes for a brand color

[](#4-return-color-schemes-for-a-brand-color)

Generate complementary, triadic, tint, shade, and other palettes — with ICC-aware values when profiles are set.

```
use wwaz\ColorBridge\Color\RGB;
use wwaz\ColorBridge\Bridge\Bridge;

$bridge = new Bridge(new RGB('0,158,227'));
$bridge->setProfile('rgb', 'sRGB_v4_ICC_preference');
$bridge->setProfile('cmyk', 'ISOcoated_v2_300_eci');

$bridge->convert();
$schemes = $bridge->schemes(profiled: true);

// $schemes['complementary'], $schemes['triadic'], $schemes['tint'], ...
```

Or include schemes directly in the convert response:

```
$data = $bridge->profiled(
    'sRGB_v4_ICC_preference',
    'ISOcoated_v2_300_eci',
    includeSchemes: true,
)->toArray();
```

### 5. Low-level ICC conversion only

[](#5-low-level-icc-conversion-only)

You only need RGB ↔ CMYK conversion, without names or schemes.

```
use wwaz\ColorBridge\Color\CMYK;
use wwaz\ColorBridge\Color\RGB;
use wwaz\ColorBridge\Bridge\ProfileConverter;

$converter = new ProfileConverter();
$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'));
```

---

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

[](#installation)

```
composer require wwaz/colorbridge-php
```

Dependencies (all on Packagist):

- `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 profiles once:

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

---

Main classes
------------

[](#main-classes)

ClassWhen to use`Bridge`Full conversion with perception, names, and schemes`BridgeService`String-based input — good for APIs and controllers`ProfileConverter`RGB ↔ CMYK only`BridgeResult`Structured result with helper methods---

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. Think of it as a strategy for handling out-of-gamut colors.

Supported values:

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

```
$bridge->setIntent('perceptual');
```

### Which intent should I use?

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

IntentBest forWhat it does in practice`relative`**Everyday print prep** — logos, layouts, brand colors, most web-to-print workflowsKeeps neutral grays stable and adjusts other colors relative to white. Usually the safest default when you are not sure.`perceptual`**Photos, gradients, images, smooth backgrounds**Compresses the whole color range so the image still looks natural, even if some bright or saturated colors become less vivid. Good when preserving overall appearance matters more than exact individual swatches.`saturation`**Charts, infographics, bold graphics, business colors**Tries to keep vivid colors strong, even if hue and lightness shift a bit. Useful when punchy colors are more important than exact tone.`absolute`**Proofing, simulation, strict color matching to a known print condition**Maps colors in a more literal way to the destination profile. Useful for color-accurate previews, not usually the best choice for general design work.### Quick decision guide

[](#quick-decision-guide)

- Picking a brand color for a flyer or business card? → start with **`relative`**
- Converting a product photo for a catalog? → try **`perceptual`**
- Building a presentation with strong chart colors? → try **`saturation`**
- Checking how a print proof should look on screen? → consider **`absolute`**

If the result looks too dull or too aggressive, switch intent and compare the `profiled` and `perception` values in the response.

If no ICC profiles are set, the library falls back to simple math conversion and the intent has no effect.

---

Result structure
----------------

[](#result-structure)

`BridgeResult::toArray()` returns:

KeyDescription`given`Original input (type, color space, value)`values`Direct color values (rgb, hex, cmyk)`perception`Screen preview after ICC roundtrip`profiled`Profiled target values`inField`In-field / proofing values`name`Closest color name`intent`Rendering intent used`schemes`Color schemes (only when requested)Helper methods on `BridgeResult`:

```
$result->hex();
$result->cmyk();
$result->name();
$result->givenValue();
```

Available scheme types: `complementary`, `triadic`, `analogous`, `square`, `tetradic`, `tint`, `shade`, `tone`, `hue`.

---

Error handling
--------------

[](#error-handling)

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

---

Important note about concurrency
--------------------------------

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

`ProfileConverter` 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 (routes, views, API), see [`wwaz/cooler`](https://github.com/WWAZ/cooler).

Cooler merges all bridge-related settings into `config/cooler.php` and reads them via `CoolerSettings`. The library itself has no `config()` or `env()` calls — pass explicit constructor arguments or an optional `BridgeConfig`.

---

License
-------

[](#license)

MIT — see [LICENSE](LICENSE).

###  Health Score

39

—

LowBetter than 85% of packages

Maintenance100

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity45

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

0d 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 (2 commits)")

---

Tags

colorrgbcmykcolor-profileicccolor-schemescolor-bridge

###  Code Quality

TestsPHPUnit

### Embed Badge

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

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

###  Alternatives

[spatie/color

A little library to handle color conversions

38221.2M35](/packages/spatie-color)[ozdemirburak/iris

PHP library for color manipulation and conversion.

1201.9M21](/packages/ozdemirburak-iris)[tecnickcom/tc-lib-color

PHP library to manipulate various color representations

247.9M24](/packages/tecnickcom-tc-lib-color)[ssnepenthe/color-utils

A PHP library for performing SASS-like color manipulations.

631.2M16](/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.

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

PHPackages © 2026

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