Statamic Color Extractor Laravel Package

Getting Started

• Install with composer require aryehraber/statamic-color-extractor. The addon is auto-discovered by Statamic (no manual provider registration needed on Statamic 3+).
• Publish the config before doing anything else: php artisan vendor:publish and pick the color-extractor tag (or copy vendor/aryehraber/statamic-color-extractor/config/color-extractor.php manually). This file is where extraction behaviour lives.
• Look first at: the README usage section, config/color-extractor.php, src/Listeners (new in v2.1.0), and src/Commands. Those four cover ~90% of day-to-day questions.
• Confirm the command signature in your install with php please list — the addon exposes an extraction command, and v2.1.0's headline feature is that you no longer have to call it for new uploads.
• First use case: add a color field to an asset container's blueprint so the extracted value is visible/editable in the CP, upload an image, then output it in Antlers: {{ hero_image:color }}. Typical first win is a CSS custom property or an inline background-color behind a lazy-loaded image.
• If you're upgrading an existing site, the first real task is not code — it's running the extraction command once to backfill every asset that predates v2.1.0.

Implementation Patterns

Placeholder / blur-up pattern. Store the extracted hex as a CSS variable and paint it behind the <img> so layout and colour are correct before the image loads:

<div style="background-color: {{ hero_image:color }}">
  <img src="{{ hero_image:url }}" loading="lazy" alt="">
</div>

Auto-extraction as the default path (v2.1.0). With the event listener enabled, colours are computed when an asset is uploaded/saved, so templates can assume :color exists for new content. Keep the command in your deploy or content-import scripts for anything that bypasses the CP (migrations, imports, syncs, seeders).

Backfill as a one-off job. For an existing asset library, run the command once after deploy. On a large library, prefer running it in a queued context or per-container rather than in a request — and clear the Stache afterwards so templates see the new meta.

Reacting to extraction. Rather than duplicating extraction logic, subscribe to the addon's event (or bind your own listener alongside the built-in one) to derive complementary colours, compute contrast text colour, or push the value into a search index. This keeps you upstream-compatible.

Manual override workflow. If editors occasionally need to correct a colour, treat the extractor as a default-filler: either disable the listener for those containers in config, or guard your own listener so it only writes when the field is empty. This is a policy decision to make explicitly — see Gotchas.

Container-by-container rollout. Roll out to one asset container at a time, verify CP output and template behaviour, then widen. Colours on a 5,000-image library are a different operational problem from colours on a logo folder.

Gotchas and Tips

• Config drift on upgrade. v2.0.0 → v2.1.0 is additive, but the listener almost certainly introduces new config keys. A previously published config/color-extractor.php will not pick them up. Diff your published config against the vendor copy after every minor bump, or you'll silently run on defaults.
• Auto-extraction is (probably) synchronous. If the listener runs inline on save, uploading large images in the CP gets slower. Check the config for a queue/defer option; if there isn't one, disable the listener for heavy containers and drive extraction from a queued job instead.
• Existing assets are not retroactively processed. The listener only fires on new events. Everything already in the library needs the command. This is the single most common "it's broken" report after this release.
• Caches lie. Asset meta is served from the Stache; static/full-page caches may hold the pre-backfill markup. After running extraction, clear caches (php please stache:clear, php please clear:cache, plus any CDN/page cache) before concluding it didn't work.
• Manual edits vs. the listener. If the listener re-extracts on every save, an editor's hand-picked colour can be overwritten the next time the asset is touched. Decide whether color is derived or editorial, and enforce it in config or in your own listener.
• Unsupported / awkward inputs. SVGs can't be rasterised for colour without extra tooling; fully transparent PNGs, animated GIFs, and greyscale-heavy images can yield surprising or empty results. Always render with a template fallback ({{ hero_image:color or="#eeeeee" }} or an ?? equivalent in Blade).
• Remote disks. On S3/Spaces the file isn't local; extraction has to fetch it. Expect extra latency and occasional failures on private disks — check that the disk is readable by the process running the command.
• A throwing listener can break CP saves. If extraction fails on a corrupt image, wrap the listener logic defensively (or check storage/logs/laravel.log first when "uploading this one image errors" is reported).
• Multi-site. Asset meta is per-site in Statamic; colours extracted for one site aren't guaranteed to be populated on others. Run the command per site or confirm the addon writes site-agnostically.
• Extension points worth knowing: the published config (containers, enable/disable listener, extractor settings), the addon's extraction event for fan-out logic, and the container binding for the extractor itself if you want to swap the underlying colour library. Binding a custom extractor in a service provider is cleaner than forking.