ksubileau/color-thief-php

Releases

1. ▸▾v3.0.026 Jun 2026Security2 sources agree

   URL fetching was removed because it can introduce Server-Side Request Forgery (SSRF) vulnerabilities if the URL is not validated before being passed t…

   New features

   • Add support for PHP 8.5 (see #62, thank @joeworkman).
   • Modernize codebase with PHP 8.2+ features: readonly classes, enums, named arguments, ... (see #62, thank @joeworkman).
   • Add getSwatches() method that classifies a palette into semantic swatch roles: vibrant, muted, darkVibrant, darkMuted, lightVibrant, lightMuted.
   • Add population and proportion to all color objects: each extracted color now carries the number of pixels it represents and its share of the analyzed area.
   • Add configurable pixel filtering with new whiteThreshold, alphaThreshold, and minSaturation options.
   • Add OKLCH quantization support via a new colorSpace option. OKLCH produces more perceptually uniform palettes and is now the default.
   • Add ImageRegion class to restrict color extraction to a rectangular region of the image, replacing the previous $area array parameter.
   • Add rich API on output color objects:
     • Colorspace conversions: toRgb(), toHsl(), toHsv(), toOklch(), toCmyk().
     • Format exports: CSS notation (toCss()), hex string (toHex()), packed integer (toInt()), component array (toArray()).
     • WCAG 2.x accessibility helpers: luminance(), isDark(), isLight(), textColor().

   Bug fixes

   • Validate getimagesize return value in GdAdapter::loadFromPath (see #62, thank @joeworkman).
   • Add null check after array_shift in GmagickAdapter::getPixelColor (see #62, thank @joeworkman).

   Breaking changes

   • Drop support for PHP 7.x, 8.0, and 8.1; now requires 8.2+.
   • ColorThief is now an instantiable readonly class. Static method calls (ColorThief::getColor(), ColorThief::getPalette()) are no longer supported; create an instance instead.
   • Configuration options quality and preferredAdapter are now constructor parameters. The $quality and $adapter positional arguments previously accepted by getColor() and getPalette() have been removed.
   • The $outputFormat parameter has been removed. getColor() now always returns an RgbColor object (or null) and getPalette() always returns a ColorPalette<RgbColor>. Use the conversion methods on the returned objects to get the format you need.
   • The $area array parameter has been replaced by a typed ImageRegion object passed as the $region named argument.
   • getRed(), getGreen(), and getBlue() on the color object have been replaced by red(), green(), and blue() methods.
   • The maximum number of colors that can be extracted is now 20 instead of 256.
   • Drop support for loading images from URLs. Passing a URL to getColor() or getPalette() now throws a NotReadableException.
     URL fetching was removed because it can introduce Server-Side Request Forgery (SSRF) vulnerabilities if the URL is not validated before being passed to the library; responsibility for fetching remote images now lies with the caller.
     Fetch the image yourself and pass the binary content instead.

     // Before
     $color = ColorThief::getColor('https://example.com/image.jpg');
     
     // After
     use ColorThief\ColorThief;
     
     $thief = new ColorThief();
     $data = file_get_contents('https://example.com/image.jpg'); // Ensure you implement appropriate security controls when fetching the image
     $color = $thief->getColor($data);

   • OKLCH is now the default quantization color space. Palette output will differ from previous versions. Set colorSpace: ColorSpace::Rgb to restore the previous behavior.
   • Behavior change for degenerate images: fully transparent, fully white, and single-color images no longer throw an exception; they now return a palette with a single representative color.