README

A modern PHP library to extract the dominant color palette from images.

Features

Extract dominant colors from any image format supported by GD
Configurable number of colors to extract
Adjustable granularity for performance vs. accuracy tradeoff
Fluent interface for easy chaining
Type-safe with strict PHP 8.3+ type declarations
Full PHPStan level max compliance
100% test coverage

Requirements

PHP 8.3 or 8.4
GD extension

Installation

Install via Composer:

composer require bensquire/php-color-extractor

Usage

Basic Example

<?php

use PHPColorExtractor\PHPColorExtractor;

$extractor = new PHPColorExtractor();
$extractor->setImage('/path/to/image.jpg');
$palette = $extractor->extractPalette();

// Returns array of hex colors, e.g., ['CC6666', 'FF9933', '66CC99', ...]
print_r($palette);

Advanced Usage with Fluent Interface

<?php

use PHPColorExtractor\PHPColorExtractor;

$extractor = new PHPColorExtractor();
$palette = $extractor
    ->setImage('/path/to/image.jpg')
    ->setTotalColors(5)        // Extract 5 colors (default: 10)
    ->setGranularity(10)        // Check every 10th pixel (default: 5)
    ->extractPalette();

foreach ($palette as $color) {
    echo "#{$color}\n";
}

Configuration Options

`setImage(string $image): self`

Set the path to the image file to analyze.

Throws: Exception if the file doesn't exist.

`setTotalColors(int $totalColors = 10): self`

Set the number of dominant colors to extract.

Default: 10 Throws: Exception if the value is less than or equal to 0.

`setGranularity(int $granularity = 5): self`

Set the sampling granularity. Higher values = faster but less accurate. Lower values = slower but more accurate.

Default: 5 Throws: Exception if the value is less than or equal to 0.

`extractPalette(): array<int, string>`

Extract and return the color palette as an array of hex color strings.

Returns: Array of hex color strings (without # prefix) Throws: Exception if no image has been set or if image processing fails.

Examples

Web Color Palette Display

<?php

use PHPColorExtractor\PHPColorExtractor;

$extractor = new PHPColorExtractor();
$palette = $extractor
    ->setImage('uploaded-image.jpg')
    ->setTotalColors(8)
    ->extractPalette();

echo '<div class="palette">';
foreach ($palette as $color) {
    echo sprintf(
        '<div class="color" style="background-color: #%s;"></div>',
        $color
    );
}
echo '</div>';

Fast Preview (Low Accuracy)

<?php

use PHPColorExtractor\PHPColorExtractor;

// Quick extraction for thumbnails or previews
$palette = (new PHPColorExtractor())
    ->setImage('large-image.jpg')
    ->setTotalColors(3)
    ->setGranularity(20)  // Sample every 20th pixel for speed
    ->extractPalette();

High Accuracy Analysis

<?php

use PHPColorExtractor\PHPColorExtractor;

// Detailed extraction for color analysis
$palette = (new PHPColorExtractor())
    ->setImage('artwork.jpg')
    ->setTotalColors(15)
    ->setGranularity(1)   // Sample every pixel for maximum accuracy
    ->extractPalette();

Development

Running Tests

composer install
vendor/bin/phpunit

Running Static Analysis

vendor/bin/phpstan analyse

Running All Quality Checks

vendor/bin/phpstan analyse && vendor/bin/phpunit

How It Works

The library samples pixels from the image at intervals determined by the granularity setting. It then:

Rounds RGB values to reduce similar colors
Counts occurrences of each color
Sorts by frequency
Returns the most common colors

This approach is based on this Stack Overflow answer.

Contributing

Contributions are welcome! Please ensure:

All tests pass (vendor/bin/phpunit)
PHPStan analysis passes at max level (vendor/bin/phpstan analyse)
Code follows PSR-4 autoloading standards
New features include tests

License

This library is licensed under the MIT License. See LICENSE for details.

Credits

Ben Squire - Original author
Inspired by Stack Overflow community

Changelog

See CHANGELOG.md for version history and changes.

bensquire / php-color-extractor

Maintainers

Details