Color Extractor Laravel Package

Technical Evaluation

Architecture fit. league/color-extractor is a small, framework-agnostic, pure-PHP library with three public classes (Palette, ColorExtractor, Color) and no Laravel coupling. That is a good architectural fit precisely because it makes no architectural claims: it belongs behind a thin application-owned service (e.g. App\Services\Image\PaletteExtractor) rather than being called from controllers. The natural placement is an asynchronous boundary — a queued job or a batch command — which matches Laravel's existing queue and scheduler primitives. It does not introduce a new datastore, network dependency, or service to operate. From a TPM lens, this is an enabler dependency, not a platform bet: one integration seeds several roadmap items (shop-by-color, auto-theming from a logo, dominant-hue sorting, blur-up placeholders), all sharing the primitive "image → structured color data."

Integration feasibility. Composer-installable, MIT-licensed, PHP 8 supported, with Palette::fromFilename(), fromContents(), and fromUrl() covering the realistic input paths (local disk, raw bytes from an upload, remote URL). Output is trivially persistable: colors as 0xRRGGBB integers plus pixel counts, convertible via Color::fromIntToHex(). A first vertical slice is genuinely small — add "ext-gd": "*" to composer.json, bind the extractor in a service provider, dispatch a job on upload, write dominant_hex and a palette JSON column. Effort is roughly one sprint for the internal version, not a program.

Technical risk. Three real risks, none disqualifying:

1. Runtime extension dependency (highest). GD is required; 0.6.0 added Imagick support, so there is a path off GD, but either way the image driver is a hard runtime prerequisite. Standard php:8.x-cli Docker images ship without GD, and shared/serverless PHP runtimes often omit it. This must be verified in every target environment before commitment, and enforced at deploy time rather than discovered in production.
2. Ecosystem signal is thin. ~1.3k stars but 0 dependents recorded and a small maintainer surface. That is tolerable because the API is three classes and MIT — the exit cost is a vendor copy or a swap behind our wrapper — but it argues against building a deep abstraction on top of it or assuming long-term upstream feature velocity. 0.5.0 and 0.6.0 are largely maintenance and CI/hygiene releases; treat upstream as stable-but-quiet.
3. It is a heuristic, not a vision model. It knows which colors are present and in what proportion. It does not know a shoe is "white with a red sole," does not classify patterns, and does not produce human-readable names. Any feature that implies semantic understanding ("find red sneakers") requires an additional hex→name mapping and dominance rules that we own and QA. Scope that as a separate work item so it isn't silently assumed into this one.

Also note the transparency default is a product decision disguised as a default: any pixel with alpha > 0 is discarded unless a blend background is supplied. For logos and cut-out PNGs, blending against white (or the page background) is usually correct — but it must be decided explicitly, per asset class, not inherited.

Key questions.

• Is ext-gd (or Imagick) present and guaranteed in dev, CI, staging, queue workers, and any serverless/image-processing runtime we use? Who owns that guarantee?
• What is the degraded behavior when extraction fails or the format is unsupported — null column, retry, or a "needs manual color" admin state?
• Do we downscale before extraction? (We should; 4K inputs burn CPU for no accuracy gain.)
• What transparency background do we use for each asset class — photography vs. logos vs. cut-outs?
• What is the acceptance threshold for "correct enough," measured on a real sample of the catalog, before anything user-facing ships?
• Do we need color names or contrast/WCAG math? If yes, that is a separate layer, not this package.

Integration Approach

Stack fit. Laravel-native by absence of opinion. Recommended shape:

• config/image-palette.php for driver selection, downscale target (e.g. max 512px edge), default transparency background, and palette size (n in extract(n)).
• A container-bound PaletteExtractor service wrapping the package so call sites never touch League\ColorExtractor\* directly. This is the single most valuable engineering decision here: it caps the cost of replacing or vendoring the library later.
• A queued job (ExtractImagePalette) dispatched on upload, ideally afterCommit() so we never process a file whose DB row rolled back.
• Persistence as dominant_hex (string, nullable) plus palette (JSON cast to array) plus palette_extracted_at and palette_source/version for cache-busting when we change extraction parameters.
• A scheduled palette:backfill command with chunking, idempotency, and a --dry-run/--limit for staged rollout.

Storage access should go through Laravel's Storage facade into a temp path or Palette::fromContents(), keeping S3/disk abstraction intact rather than assuming local paths.

Migration path. Additive and reversible by design: nullable columns, a feature flag, and no changes to existing image handling. There is no schema rewrite, no data migration on write paths, and no new infrastructure. Rollback is "stop dispatching the job; columns go unused." That low blast radius is the main argument for proceeding despite thin vendor signal.

Compatibility. PHP 8.x is supported (support for ≤7.2 was dropped in 0.4.0), so modern Laravel versions are fine. The compatibility surface to check is not Laravel — it's the image driver and the input formats users actually upload. GD's format coverage is narrower than user reality (HEIC from iPhones, some CMYK JPEGs, TIFF, SVG). SVG in particular is common for merchant logos and is not a raster format the library handles — we must rasterize first or exclude it explicitly. Treat "unsupported image" as a designed product state with an admin-visible UI, not an exception log.

Sequencing. Deliberately invisible-before-visible:

1. Environment verification (ext-gd/Imagick in all runtimes) and CI enforcement.
2. Thin wrapper service + queued job + nullable columns, behind a flag, on new uploads only.
3. Batch backfill of the existing catalog to measure accuracy on real assets — this is the gate, not a formality.
4. Internal admin display of extracted palettes with merchandiser override; persist overrides as the source of truth and use them as free labeled data to tune dominance thresholds.
5. Only then expose any user-facing filter or sort, and only for asset classes that passed step 3.

Do not parallelize steps 3 and 5. The visible feature should be paid for by evidence from the invisible one.

Operational Impact

Maintenance. Low ongoing maintenance, which is the package's main operational virtue. No network calls, no API keys, no rate limits, no vendor SLA, no data leaving our infrastructure — relevant if images are user content or unreleased product shots. Two maintenance obligations we own: keeping the image extension present in every runtime, and keeping our wrapper (not the library) as the place where behavior lives. Given the thin dependents signal, assume upstream could go quiet; the mitigation is a pinned version and a wrapper thin enough to reimplement in a day.

Support. Support burden concentrates on data quality, not uptime. Expect merchant/merchandiser tickets of the form "this item is tagged wrong" — a black product shot on a white background being labeled white is the canonical failure. The mitigation is organizational, not technical: the override workflow must exist before customer exposure, and the admin UI must show the extracted palette and pixel proportions so the override is a one-click correction rather than a debugging session. Budget for a small amount of merchandising QA time per batch.

Scaling. Extraction is CPU-bound and linear in pixel count, so the first optimization is downscaling, not horizontal scaling — capping input dimensions typically removes an order of magnitude of work for negligible accuracy loss. Run it exclusively on queue workers with their own queue name and concurrency limit so image processing cannot starve transactional jobs; on a backfill of a large catalog this is the difference between a smooth rollout and an incident. Cache results on the record and never extract in the request/response cycle. Per-image cost is small but non-zero; a catalog-wide backfill should be sized and scheduled off-peak rather than fired at once.

Failure modes. Enumerate and design for each:

• Missing image extension → hard failure at runtime. Mitigate by requiring ext-gd in composer.json so deploys fail loudly, and by an explicit health check.
• Unsupported or corrupt format (HEIC, SVG, CMYK) → the package throws; the job must classify this as a terminal, non-retryable outcome and write a palette_status = unsupported marker rather than retrying forever.
• Transparent PNG / logo → silent, plausible-but-wrong output (all alpha pixels dropped) unless a blend background is configured. This is the most dangerous mode because it looks like success.
• CPU/timeout on oversized images → job timeout or worker exhaustion; mitigate with pre-downscale and an explicit max-dimension guard.
• Silent accuracy drift when we change n, downscale target, or background — mitigate with a palette_version column and a targeted re-backfill rather than an untracked global change.
• Queue backlog during backfill → isolate the queue and cap concurrency.

Each of these should be observable: log extraction outcomes by status and emit a metric for success/unsupported/failed, so the accuracy conversation in step 3 of the sequencing is driven by data rather than anecdotes.

Ramp-up. Very shallow for a Laravel developer — three classes, one required extension, a documented first use case of roughly twenty lines. The real ramp-up cost is on the product side, not engineering: agreeing on transparency semantics per asset class, defining the dominance threshold that turns a palette into a single tag, deciding whether color names are in scope, and building the override workflow. Allocate the TPM attention there. Engineering onboarding is an afternoon; the product decisions around what we claim the color means are where the schedule risk lives.