Filament Image Meta Laravel Package

Getting Started

Install the package with Composer and follow its README to register the Filament plugin/assets and publish any config you need to override. The first place to look is the package config for disk, locale/fallback behaviour, and the field’s documented state/meta storage; then inspect the ImageMeta helpers if you need to render alt/caption/title outside the form.

Start with the simplest replacement for a plain upload: a single image field, optionally requiring alt text.

// Use the package’s field class namespace as documented.
ImageUpload::make('cover')
    ->disk('public')
    ->requireAlt()
    ->locales(['en', 'fr']);

First use case: a cover/hero image where editors must supply alt text. Add the field to the form, save one record, then render the stored alt text in Blade using the package’s metadata helpers. As of v1.0.2, requireAlt() also validates images already stored on the record, not just files uploaded in the current request.

Implementation Patterns

• Single image with required alt text. Use ->requireAlt() on the field. The details panel is part of the form, so missing alt text blocks saving both new and existing records. If a record already has an image with no alt text, expect validation on the panel rather than a silent save.

• Locale-aware alt text. When using ->locales([...]), treat each required language as needing its own alt text, or a language-less alt. fallback_locale is for rendering only: it no longer makes the badge say “Alt text set” and does not satisfy requireAlt. If you render language-specific alt text, use ImageMeta::ownAlt() / hasOwnAlt() rather than assuming the fallback locale is valid for validation.

• Repeater and Builder uploads. Uploads stored inside JSON items work in both Repeater and Builder items. The package keeps the stored snapshot in the details panel’s own state under the reserved _stored key, signed with the app key and bound to the field name. Do not read or write _stored in application code; treat missing or forged values as “nothing stored.”

• Editing existing images in the modal. Clearing alt text in the details modal for an existing image now fails validation when requireAlt() is on. For locale-aware fields, ensure the required locale’s alt text is filled after modal edits; the panel error appears in the field wrapper.

• Remote disks. The panel reads upload metadata once per state instead of on every render, rule run, and modal open. requireAlt no longer asks the disk for anything. This is important for S3/remote disks with many files; keep your own accessors from adding repeated disk calls.

• Rendering metadata. Use the package’s ImageMeta API for alt/caption/title rather than parsing the stored JSON by hand. For localized values, prefer ownAlt()/hasOwnAlt() when deciding whether the current language has its own alt text. Keep your own fallback logic for display only.

• Backfilling before enabling requireAlt. If you are adding requireAlt() to an existing form, backfill alt text for stored images first. Otherwise editors will hit validation failures when saving unrelated changes to records that contain undescribed images.

Gotchas and Tips

• v1.0.2 changes validation behaviour. requireAlt now checks images already stored on the record. Existing records with missing alt text will no longer save silently. Test upgrades against real records, both local and remote storages, before deploying.

• _stored is reserved and HMAC-signed. Do not write to _stored, do not trust client-supplied _stored, and do not use it as a custom state bucket. Missing or forged snapshots count as “nothing stored.” If you rename the field, expect the stored snapshot binding to be affected; treat that as a data migration concern.

• Repeater/Builder state paths are not stable. A Repeater re-keys items after hydration, so never bind custom logic to the state path. The package uses the field name for the signed snapshot. Keep field names stable, especially in JSON-backed Repeater/Builder items.

• fallback_locale is not a validation fallback. A required language counts as described only with its own alt text or a language-less alt. The badge and alt text under the file name are shown in a managed language (interface language, else the first required one), so do not assume fallback-locale text satisfies required-locale validation.

• Extensionless and non-standard images. requireAlt recognises stored images with extensions such as heic and tif; with no extension, it asks the upload’s mime type. If you use unusual files on remote disks, verify mime detection works with your disk configuration.

• Locale-less fields no longer collapse per-language maps. Applying the modal to a field without locales keeps unedited alt/caption/title maps intact instead of flattening them to one string. If custom code expects a string from field state, check for a map first.

• Errors appear on the details panel. The panel now sits inside the field wrapper. In Repeaters/Builders, look at the item’s panel wrapper for the requireAlt error rather than only the top-level field.

• With requireAlt off, no empty rule is sent. The package avoids adding an empty rule to the validator, so you should not see the previous PHP deprecation per upload. Do not manually add empty rules to mimic old behaviour.

• Performance still depends on form size. The package avoids repeated disk reads per render/rule/modal, but large Repeaters with many images still create many panels. Profile large forms and consider limits on item counts where appropriate.

• Test the upgrade paths. Add tests for: existing record save with missing alt, alt cleared in the modal, required locale with only fallback alt, Repeater/Builder item save preserving stored details, and forged/missing _stored state.