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

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

wwaz/colorname-php
==================

Load and find color names by RGB value

v1.0.0(today)010↑2600%MITPHPPHP ^8.2CI passing

Since Jul 1Pushed todayCompare

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

READMEChangelogDependencies (1)Versions (2)Used By (0)

colorname-php
=============

[](#colorname-php)

Find a human-friendly color name for a hex or RGB color value.

This package is useful when your app stores colors as technical values, but you want to show readable names to users.

Practical Use Cases
-------------------

[](#practical-use-cases)

### 1. Show a readable color name in a UI

[](#1-show-a-readable-color-name-in-a-ui)

```
use wwaz\Colorname\ColornameService;

$colors = new ColornameService();

echo $colors->fromHex('#f00'); // Red
```

You can use this in design tools, admin panels, product editors, theme builders, or any place where users pick colors.

### 2. Match a color against your own catalog

[](#2-match-a-color-against-your-own-catalog)

```
use wwaz\Colorname\ColornameService;

$colors = new ColornameService('/path/to/your/colornames.json');

echo $colors->fromHex('#f00'); // Brand Red
```

This is helpful when you need localized color names or a product-specific list of approved color names.

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

[](#installation)

Install the package with Composer:

```
composer require wwaz/colorname-php
```

The package requires PHP 8.2 or newer.

Basic Usage
-----------

[](#basic-usage)

Use `ColornameService` for the common case:

```
use wwaz\Colorname\ColornameService;

$colors = new ColornameService();

$name = $colors->fromHex('#f0f8ff');

echo $name; // Alice Blue
```

The service accepts short and long hex values, with or without `#`:

```
$colors->fromHex('f00');
$colors->fromHex('#f00');
$colors->fromHex('ff0000');
$colors->fromHex('#ff0000');
```

Custom Catalogs
---------------

[](#custom-catalogs)

Create a catalog from an array:

```
use wwaz\Colorname\ColornameService;

$catalog = [
    ['name' => 'Brand Red', 'hex' => '#ff0000'],
    ['name' => 'Brand Blue', 'rgb' => [0, 0, 255]],
];

$colors = new ColornameService($catalog);

echo $colors->fromHex('#f00'); // Brand Red
```

Or load a catalog from a JSON file:

```
use wwaz\Colorname\ColornameService;

$colors = new ColornameService('/path/to/your/colornames.json');
```

Custom catalog file paths should be absolute.

The JSON file should contain a list of entries:

```
[
  {
    "name": "Brand Red",
    "hex": "#ff0000"
  },
  {
    "name": "Brand Blue",
    "rgb": [0, 0, 255]
  }
]
```

Each entry needs a `name` and either `hex` or `rgb`. If both are present, `hex` is used.

RGB Matching
------------

[](#rgb-matching)

The service also accepts RGB values:

```
use wwaz\Colorname\ColornameService;

$colors = new ColornameService();

echo $colors->fromRgb('255,0,0'); // Red
echo $colors->fromRgb([255, 0, 0]); // Red
```

`fromRgb()` accepts:

- An RGB string like `255,0,0`
- An RGB array like `[255, 0, 0]`
- An object with a `toArray()` method that returns RGB values

How Matching Works
------------------

[](#how-matching-works)

The package compares the input color with every color in the selected catalog.

It returns the color name with the smallest RGB distance. This means exact matches work, and near matches return the closest available name.

Development
-----------

[](#development)

Install dependencies:

```
composer install
```

Run the test suite:

```
composer test
```

License
-------

[](#license)

MIT

###  Health Score

42

—

FairBetter than 88% of packages

Maintenance100

Actively maintained with recent releases

Popularity7

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 (4 commits)")

---

Tags

colorrgbhexcolor-name

###  Code Quality

TestsPHPUnit

### Embed Badge

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

```
[![Health](https://phpackages.com/badges/wwaz-colorname-php/health.svg)](https://phpackages.com/packages/wwaz-colorname-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)[ssnepenthe/color-utils

A PHP library for performing SASS-like color manipulations.

631.2M16](/packages/ssnepenthe-color-utils)[tecnickcom/tc-lib-color

PHP library to manipulate various color representations

247.9M24](/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.8k](/packages/fjw-color-compare)

PHPackages © 2026

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