- What does league/color-extractor do?
- league/color-extractor is a framework-agnostic PHP library that builds a Palette from an image, an iterator of color integers keyed to pixel counts and sorted by pixel count, plus a ColorExtractor that returns the most representative colors. It also ships helpers such as getMostUsedColors(), getColorCount(), and Color::fromIntToHex() for hex output. It performs only RGB integer manipulation, with no LAB/HSL color science or contrast calculations.
- How do I install league/color-extractor in a Laravel project?
- You install it with composer require league/color-extractor; it has no Laravel service provider, config file, or facade. Use the Palette and ColorExtractor classes directly, or wrap them in a small application-level service such as ColorPaletteService so you can mock it in tests and swap implementations later. Make sure ext-gd is enabled in your local, CI, and production environments before committing.
- Does league/color-extractor work with Laravel 10 and 11?
- Yes. Because it is framework-agnostic and depends only on PHP and ext-gd, it works in Laravel 8, 9, 10, 11, and newer without version constraints. Its PHP floor of 7.3+ is below current Laravel LTS requirements, so it will not block framework upgrades. The package has PHP 8.x support, typed returns, a recent release, and CI coverage.
- What are the requirements for league/color-extractor?
- The hard runtime requirement is ext-gd; the package will not work without it. GD is present in most official php:8.x-fpm images, but WebP and AVIF support depend on how GD was compiled, and minimal containers or shared hosting may lack it. Verify GD and the specific image formats you need in CI and staging before adopting it.
- Why are transparent pixels missing from my extracted palette?
- By default, any pixel with an alpha value greater than zero is discarded when the palette is built, so transparent areas of logos or PNGs can be missing from the results. Pass a background color integer as the second argument to Palette::fromFilename or fromContents, and transparent pixels will be blended against it before being counted. For example, a white background turns 50 percent transparent red into #FF8080.
- What is the difference between Palette and ColorExtractor::extract()?
- Palette gives you deterministic, explainable facts: every distinct color as an integer key mapped to its exact pixel count, which is ideal for color-based filtering, search, and cacheable results. ColorExtractor::extract(n) returns the n most representative colors from that palette, which is better suited to theming and design features. Both are built from the same Palette, so you can use one for storage and the other for presentation.
- How do I avoid memory and performance problems with large images?
- Extraction is CPU-bound and its memory use scales with the number of distinct colors, not the file size, so a large noisy photo can produce hundreds of thousands of keys. Downscale images to roughly 200 to 500 pixels on the long edge before calling the package, which also tends to produce better perceptual results. Run extraction in queued or batch jobs rather than synchronously in a request path, and cache the resulting palette.
- Which image formats does league/color-extractor support?
- Format support is limited by GD: JPEG, PNG, and GIF generally work, WebP depends on the GD build, AVIF is usually unavailable, and SVG is out of scope entirely. Modern catalog imagery often arrives as WebP, so silently failing on some uploads is a realistic risk. Validate and normalize formats on ingest, and reject unsupported files with a clear error.
- Is Palette::fromUrl() safe to use with user-supplied URLs?
- Palette::fromUrl() performs an outbound HTTP request, so if any part of the URL is user-influenced it becomes an SSRF primitive. Prefer fromFilename() or fromContents() against files in Laravel Storage, or restrict fromUrl() to a hard allowlist of trusted hosts. Treat URL fetching as a security decision rather than a convenience.
- Is league/color-extractor actively maintained, and what are the alternatives?
- Yes; it is a thephpleague package under the MIT license with a credible maintenance record, PHP 8.x support, typed returns, a recent release, and CI badges. It is not a full color-science toolkit, so perceptual distance, LAB/HSL conversion, and WCAG contrast checks must be built on top. If you later need Imagick, AVIF, or a cloud service, wrapping the package behind an interface gives you a cheap swap point.