Statamic Color Extractor Laravel Package

Technical Evaluation

aryehraber/statamic-color-extractor is a Statamic add-on that extracts dominant/accent colors from image assets and persists them as asset meta data, enabling data-driven theming (hero overlays, cards, per-record accent colors) without editors manually picking colors. v2.1.0 is an additive minor release: it introduces an artisan command plus an event listener that automatically extract color meta data. This is the single most operationally significant change so far, because it shifts the package from "a helper you call" to "a pipeline that runs on your behalf."

Architecture fit. The package sits naturally in the Statamic asset pipeline: a service provider registers the extraction logic, colors are written into asset meta, and the event listener hooks into asset lifecycle events (upload/save). That is idiomatic Laravel/Statamic — no schema changes, no custom tables, no front-end runtime dependency. It composes cleanly with Antlers/Blade templates and with static caching, provided extraction completes before a page is cached.

Integration feasibility. Low to moderate. composer require plus config publishing, then enable per asset container. The new command gives a backfill path for existing libraries, which removes the largest historical blocker (no way to populate colors on already-uploaded assets). The event listener removes the "editors must re-save assets" friction. Both are opt-in, which is the right default.

Technical risk. The dominant risk is when extraction runs, not whether it works. Image color extraction is CPU- and memory-bound; a synchronous listener on upload means an editor's upload request now includes decode + quantization of a potentially multi-megabyte image. Concrete risks:

• Synchronous execution on asset events — upload timeouts, PHP max_execution_time / memory_limit failures, and lost uploads if the listener throws.
• Remote storage latency — reads from S3/Spaces incur GET cost and latency per asset; a full backfill is a billable, rate-limited operation.
• Format coverage — HEIC, CMYK JPEGs, animated GIF, SVG, and CMYK/16-bit TIFFs are common failure points; behavior on unsupported assets must be a graceful no-op, not an exception.
• Metadata staleness — if an asset file is replaced but meta persists, colors silently drift from the image. Confirm whether replacement re-triggers extraction.
• Storage/permanence — confirm where meta is written (asset meta files vs. DB) and whether it survives Statamic's meta cache flush and multi-site propagation.
• Bus factor — single-maintainer package with a small surface area; low but non-zero abandonment risk. Pin the version and keep a fork path.

Key questions for the maintainer/team spike:

1. Does the event listener dispatch queued jobs, or execute inline? Is ShouldQueue configurable?
2. Which events fire extraction — new upload only, every save, or file replacement too?
3. Does the command support scoping (container/folder/field), batching, and --force re-extraction?
4. What are the failure semantics for unreadable/unsupported images — skip, log, or throw?
5. Is extraction idempotent and cheap to re-run?
6. Which Statamic major versions (3/4/5) and Laravel versions are supported by the constraint?
7. Is there a documented palette size / output field schema, and how is it exposed in templates?

Integration Approach

Stack fit. Statamic 3/4/5 on Laravel 9–11, PHP 8.1+, with GD or Imagick available in the runtime image. It is a pure add-on — no infrastructure, no external service, no new datastore. The only non-application dependency is the image extension, which should already exist if you're doing any asset transforms.

Migration path. Because there is no prior assessment, treat this as a greenfield adoption with an existing asset library:

1. Install in staging; publish config; enable for exactly one asset container.
2. Verify output shape — which meta keys are written, and how templates read them — before any template work.
3. Confirm the new listener is queued (or wrap/disable it) and that the backfill command can be scoped and batched.
4. Run the backfill on a small, representative slice (mixed formats, sizes, and remote assets) and measure per-asset time/memory.
5. Only then enable the listener in production and schedule the remainder of the backfill off-peak.

Compatibility. v2.0.0 → v2.1.0 is a minor bump with additive behavior; no deprecations or breaking changes are indicated. The practical compatibility question is not the package version but the Statamic major version in your app — verify the composer constraint resolves against your pinned Statamic release before merging. If you are on Statamic 3, confirm the add-on's v2 line still supports it.

Sequencing. Ship in three separable increments so each can be rolled back independently:

• Phase 1 — capability: install + config + backfill one container; no user-visible change. Colors are available in meta but unused.
• Phase 2 — automation: enable the queued listener for new uploads on that container, with a dead-letter/failed-job path. Verify upload latency is unchanged.
• Phase 3 — consumption: template/component work (CSS custom properties, contrast-safe text on extracted backgrounds, fallbacks when meta is absent), then expand to remaining containers.

Keep the event listener and the template consumption as separate releases. If extraction quality turns out to be poor for a class of imagery, you want to have shipped nothing that depends on it.

Operational Impact

Maintenance. Very low ongoing surface: one composer dependency, one config file, no migrations. The cost is concentrated in the initial backfill and in monitoring. Pin to ~2.1.0 and let patch/minor upgrades flow through normal dependency review; treat a future major as a deliberate upgrade event. Keep a short internal note on the extraction field schema so template authors aren't reverse-engineering meta keys.

Support. Community/single-maintainer support with no commercial SLA. Acceptable for a presentation-layer enhancement; not acceptable if per-record color becomes a hard requirement for brand-critical pages. Mitigation: store the derived colors as ordinary asset meta so a replacement extractor can write the same keys and templates keep working — i.e., depend on the contract (meta keys), not the package.

Scaling. Extraction cost scales with asset count × image size, not with traffic — this is a one-time-plus-incremental workload, which is the good kind. Two scaling levers matter:

• Queue concurrency. Run extraction on a dedicated queue with a bounded worker count so image decoding cannot starve transactional jobs. Cap concurrency to whatever keeps memory headroom on the smallest worker instance.
• Backfill throughput vs. object-storage cost. For remote storage, batch size and pacing are cost controls as much as performance controls. Budget the backfill as a one-off GET-request line item, and gate it behind an off-peak window.

Downstream, front-end scaling is free: colors are static meta, so they participate in Statamic's static cache normally. Ensure extraction completes before a page is cached, or the first cached render will bake in missing colors.

Failure modes to instrument.

• Upload request timeout or 5xx caused by inline extraction → alert on upload error rate during Phase 2.
• PHP memory exhaustion on oversized images → set an explicit max-dimension/size guard.
• Unsupported/corrupt formats throwing instead of skipping → confirm graceful no-op; log-and-continue is the only acceptable behavior.
• Queue backlog during backfill → monitor depth and oldest-job age; a stalled worker silently halts color coverage.
• Stale meta after asset replacement → decide whether that's a re-extraction trigger or an accepted gap, and document it for editors.
• Silent template fallback → a missing color key should render a designed default, never an empty background-color, or pages will look broken in ways nobody attributes to the add-on.

Ramp-up. Low for engineers — a half-day to install, read the config, and validate output on a sample; roughly a day to prove the queued listener and backfill in staging. The real enablement work is editorial and design: agree on which containers get colors, what the fallback palette is, and how color is used (accent only vs. full backgrounds with contrast requirements). Budget a short design review on contrast/legibility for text over extracted colors, since that is where "auto-extracted" most often produces unacceptable results.