Laravel Seo Filament Laravel Package

Getting Started

This release is a bug-fix + hardening release for the Lara Zeus translatable integration in Filament, not a new API surface. Start here:

1. Check your constraint. Confirm which Filament/Lara Zeus pair you are on — the release is validated against Filament 4.13.1 + Lara Zeus 1.0.4 and Filament 5.8.1 + Lara Zeus 2.0.1. Pin both in composer.json before upgrading so the translatable plugin and Filament don't drift apart.
2. Read the migration note first. The trait imports for your Edit/Create pages have changed. If you use the optional Edit/Create adapters, replace those imports as documented before running the app — the old import path will not pick up the draft-retention and transactional-save behaviour.
3. Audit content, not code. The most important line in the notes: "Existing overwritten values cannot be reconstructed automatically." If you were on a version before 1.12.0 and editors switched languages in the form, some locale's SEO metadata (title/description), schema, or upload drafts may already have been clobbered. Take a database backup and diff per-locale metadata columns for high-value content before you start editing again.
4. First use case to verify: open a resource with per-locale title/description, type a new English title, switch to French without saving, then switch back. The English input must still be there and the French metadata must be untouched. That is the exact regression this release fixes — smoke-test it on one resource class in staging.

Where to look in the repo: the package config (locales list, field definitions), the Edit/Create page traits, and the changelog/docs section covering the adapter migration.

Implementation Patterns

Trait-per-page, not per-model. The translatable behaviour lives on the Filament Edit and Create page classes. Apply it to every page that edits localized content — an un-instrumented custom page will silently bypass validation and transactional saving.

Adapter pattern for Edit/Create (optional but recommended here). The new adapters retain the parent record, SEO metadata, schema, and in-flight uploads as drafts across the language switcher. If you have custom Create pages that mutate $this->data in mount() or mutateFormDataBeforeCreate(), move that logic where it runs after the adapter has resolved the parent, otherwise you'll re-introduce the parent-loss bug the adapter was written to fix.

Validate on all visited locales. The release validates every language the editor has touched before saving, rather than only the currently active one. Design your form rules accordingly: a required rule on a translated field means "required in each visited locale," which will surprise editors who only filled in the default language. Prefer required on the default locale and nullable-with-fallback elsewhere, or accept that a save can now fail on a tab the editor isn't looking at — surface those errors clearly in the notification.

Transactional saves. Multi-locale writes now commit atomically. Keep them atomic: avoid dispatching jobs, sending mail, or calling external APIs from observers on the translated model, because those side effects will fire inside the transaction and cannot be rolled back. Move them to DB::afterCommit() or queued listeners.

Rapid Livewire 3 switching. The fix specifically preserves the newest title/description keystrokes during fast switches. Don't counteract it by adding your own aggressive wire:model.live.debounce on translated inputs or by resetting form state in updatedActiveLocale(). Test with throttled network in the browser — the failure mode is a race, so a fast local dev machine will not reproduce it.

Upload drafts. Per-locale uploads and metadata are retained as drafts until save. If you have a custom saveUploadedFiles() or a FileUpload with ->saveUploadedFileUsing() hitting S3, verify it behaves when the same file is staged, the locale is switched, and the form saved later — the draft retention assumes the temporary file survives the switch.

AI proposal/apply flow. Browser validation covers "offline AI proposal/apply," i.e. the flow works without paid calls. Treat AI-generated titles/descriptions as drafts requiring human acceptance; the transactional save and visited-locale validation apply to them too, so a proposed value in a locale the editor never opened will not sneak into the database.

Integration tip: if you have your own locale switcher UI (a custom header action rather than the package's), switch it to the package's locale-changing path. Hand-rolled $this->activeLocale = $locale assignments are exactly how the clobbering bug was reachable.

Gotchas and Tips

• Treat 1.12.0 as a data-integrity upgrade, not a routine patch. The bug it fixes corrupted content silently and irreversibly. Upgrade promptly, then audit.
• Import change is the breaking bit. Nothing in the notes suggests a removed feature, but stale imports are the likely cause of "it still overwrites." After changing imports, run composer dump-autoload and php artisan filament:optimize-clear (or optimize:clear) so cached class maps pick up the new traits.
• Do not assume old data heals. Overwritten values stay overwritten. If SEO metadata matters, restore from backups or re-enter manually; no artisan command will recover it.
• Unvisited locales are a blind spot. Validation covers visited languages only — that is intentional for UX, but it means a locale nobody opened this session keeps whatever was there. For compliance-sensitive metadata, add a scheduled job or a dedicated "validate all locales" action that walks every configured locale.
• Config cache quirks. Changing the locales array has no effect until php artisan config:clear. Adding a locale to config does not retroactively backfill existing records — expect nulls in the new locale and handle fallbacks in your accessors.
• Version pinning. The compatibility matrix in the notes is specific (Filament 4.13.1 / Lara Zeus 1.0.4, Filament 5.8.1 / Lara Zeus 2.0.1). Don't leapfrog Filament minor versions in the same deploy as this upgrade; separate the two so a failure is attributable.
• The plugin stays optional. If you don't use the Edit/Create adapters, you can keep the previous wiring for now — but you forgo draft retention, which is the fix's main benefit. If you don't use the AI proposal feature at all, ensure no paid provider credentials are configured in production.
• Debugging fast-switch bugs. Log the active locale and the full translated payload on every updated hook in staging, reproduce with network throttling, and inspect the Livewire payload in the browser devtools. Symptoms of the old bug — a locale's fields reverting to another locale's values — should now be gone; if they reappear, check that every relevant page has the updated trait.
• Extension points. The adapters are the intended seam for custom behaviour (retaining extra attributes across switches). Prefer subclassing/overriding the adapter over patching the trait, so future upgrades don't conflict.
• Watch the next release. A change to trait imports plus a stateful draft model is a common precursor to further API churn; keep an eye on the changelog and treat this package as one to upgrade deliberately, with a staging smoke test per release.