Statamic Aida Laravel Package

Getting Started

Install the addon and pull down its config scaffold:

composer require 21stdigital/statamic-aida
php artisan vendor:publish --tag=statamic-aida-config

Check the version matrix before you install. As of 2.2.0 (2025-09-12) the addon officially supports Statamic v6. That support landed in a minor release, which usually means the statamic/cms constraint in composer.json was widened or rewritten rather than a clean additive change — so run composer why-not 21stdigital/statamic-aida (or read the addon's composer.json on the tag) and confirm the released version actually matches your Statamic major. On Statamic 4/5 you may need to stay on the 2.1.x line; on v6 you need 2.2.0 or later.

Then add your AI provider credentials to .env (typically OPENAI_API_KEY or whichever provider the addon is configured to talk to). Check the published config/statamic-aida.php first — that file is the source of truth for provider selection, model name, prompt template, and which asset containers the addon is allowed to touch.

First useful thing to try: create or upload a single image into an assets container that is listed in the addon's config, save it, and watch whether alt gets populated on the asset's metadata. That confirms three things at once — API key wiring, container allowlisting, and whatever event hook the addon uses (asset save vs. separate queue job). Do this smoke test again after moving to Statamic v6; asset saving, metadata and the event pipeline are exactly the surfaces a major CMS bump is most likely to perturb.

Before enabling it broadly, run the batch/backfill command (usually php artisan statamic-aida:generate or similar — check php artisan list | grep aida) with a --limit=5 style flag if available, or on a throwaway container. This gives you a safety net: you'll see the actual prompt output and cost profile on your real content before touching production assets.

Implementation Patterns

Auto-generate on upload, backfill on demand. The natural workflow is to let new uploads get alt text automatically via the addon's listener, and reserve the CLI command for one-off backfills of an existing library. Keep those two paths in separate mental buckets — new content should "just work", old content gets a deliberate migration pass.

Scope by asset container, not globally. Point the addon only at containers that hold genuine editorial imagery (heroes, article thumbnails, product shots). Skip containers holding decorative icons, SVG logos, or brand marks — AI-generated alt text for those is either wrong or actively worse than alt="".

Wire it into your asset blueprint rather than fighting it. If your team edits alt text manually as part of publishing, expose the alt field in the blueprint and let the addon seed it. Editors then correct rather than write from scratch. This is the highest-ROI pattern in practice — treat AI output as a draft, not a final answer.

Queue the work. Anything that hits an external AI API should not run synchronously on asset save if you have editors uploading batches. Check whether the addon already dispatches a job; if not, wrap the generation call in your own listener/job so a 40-image upload doesn't turn into a 40-second save spinner.

Front-end template use is unchanged. Once alt is populated on the asset, your existing Antlers/Blade is fine — {{ image:alt }} or $asset->alt() just works. No template changes required, which is the main selling point of doing this at the asset-metadata layer. (Re-verify this on v6: asset/fieldtype rendering has shifted between majors before.)

Pair it with a review step in CP. A small custom widget, report, or even a Statamic "list" of assets missing alt text gives editors somewhere to spot-check AI output. Blindly trusting generated alt text across hundreds of images is how you end up with confidently-wrong descriptions of the wrong subject.

Treat the Statamic major upgrade as its own task. Don't fold the 2.1.x → 2.2.0 bump into an unrelated feature branch alongside a Statamic v6 upgrade. Move the CMS, pin the addon version, run the single-image smoke test, run a --limit backfill on a scratch container, and only then re-enable the listener broadly. If alt text silently stops generating after a v6 upgrade, you'll want a clean diff to bisect against.

Gotchas and Tips

• Statamic v6 support is the headline of 2.2.0 — and it's a compatibility surface, not a feature. The release contains exactly one change (support statamic v6, #47). That means the v6 path is fresh: no subsequent patch has shipped yet to shake out v6-specific issues. Budget time for the smoke test and watch the issue tracker for v6 regressions in the weeks after upgrading.
• Constraint changes hide in minors. The 2.1.1 → 2.2.0 diff is a minor version, but a "support v6" change very often also drops or narrows support for older Statamic releases. Read the statamic/cms requirement on the tag before running composer update, and if you're staying on Statamic 5, pin explicitly to the last 2.1.x release so a routine update doesn't try to pull in a v6-only build.
• Idempotency is on you. Most addons of this shape will happily overwrite hand-written alt text if you re-run the backfill. Check whether there's an "only if empty" flag; if not, add a guard or take a DB/metadata snapshot before batch runs.
• Queue worker required. If generation is queued, php artisan queue:work (or Horizon) must actually be running in every environment, including staging. Silent no-op alt text in staging is almost always a dead queue.
• Token and size limits. Very large images can blow past the model's input limit, and the addon may or may not resize before sending. If you see sporadic failures on high-res hero images, that's the first place to look.
• Cost visibility. Batch backfilling a 5,000-image library is a real invoice. Run the CLI on a small container first, note the per-image token cost, and extrapolate before pointing it at the full library.
• Prompt config is the main extension point. Alt text quality lives or dies on the prompt in the config file. Tune it for your domain ("product photography on white background" vs. "editorial news photography") — generic prompts produce generic alt text that fails WCAG's "equivalent purpose" bar.
• Language handling. If you run a multilingual Statamic site, confirm the addon passes the site locale into the prompt, or you'll get English alt text on French assets. This is a common gap in v1/v2 addons, and a v6 compatibility release is not the moment to assume it was fixed.
• Debugging API failures. Errors are usually swallowed into a log line. Tail storage/logs/laravel.log during your first few uploads — auth errors, quota errors, and model-not-found errors all look the same from the CP. After a v6 upgrade, also watch for errors that look like missing services or changed method signatures rather than API failures; they surface in the same place.
• Decorative images need alt="", not AI text. The addon can't know intent. Whatever container-level or per-asset exclusion the package offers, use it — otherwise screen readers get noise on every spacer GIF in your theme.
• Version pin. With 2.2.0 released 2025-09-12 and the project still small, pin the exact version in composer.json ("21stdigital/statamic-aida": "2.2.0") and read the changelog before updating. Config keys have been known to move between minors in addons this size — and the next release is the most likely place for v6 follow-up fixes.