Dual Version Support

FilamentCraft installs cleanly on either Filament 4 + Livewire 3 or Filament 5 + Livewire 4 — the same codebase, picked automatically by Composer from what the host app already has.

Why it works

Filament v5 ships zero Filament-side API changes versus v4 — the major version bump exists only to allow livewire/livewire: ^4.0. So FilamentCraft's Filament-touching code (resources, pages, schemas, the editor) needs no version-specific branching. The compatibility surface is the Livewire 3 → 4 delta, and the package's surface there is small:

• The Livewire components in src/Editor/Livewire/ use only stable v4 APIs (#[Url], #[Computed], #[Locked], #[On], dispatch()).
• No <livewire:...> tag usages in any Blade view (Livewire 4 requires self-closing tags; we don't have any).
• No wire:transition modifiers (Livewire 4 removed them).

The one real risk: livewire:morph.updated is no longer a DOM event in v4 (it's an internal hook). The editor's JS handles this by subscribing through Livewire.hook('morph.updated', cb) — an API that exists in both v3 and v4 — alongside the legacy document.addEventListener('livewire:morph.updated', cb) for older v3 builds.

Supported matrix

PHP	Laravel	Filament	Livewire	Pest	Status
8.2	11.x	4.x	3.x	3.x	✅ Strict gate
8.3	11.x	4.x	3.x	3.x	✅ Strict gate
8.3	11.x	5.x	4.x	4.x	✅ Tests green; PHPStan continue-on-error
8.3	12.x	4.x	3.x	3.x	✅ Strict gate
8.3	12.x	5.x	4.x	4.x	✅ Tests green; PHPStan continue-on-error
8.4	12.x	4.x	3.x	3.x	✅ Strict gate
8.4	12.x	5.x	4.x	4.x	✅ Tests green; PHPStan continue-on-error

Mutually-exclusive pairs (F4 + L4, F5 + L3) are explicitly excluded from CI — they don't satisfy each other's composer.json requirements.

Host installation

# Filament 4 host (existing apps)
composer require filamentcraft/filamentcraft  # resolves to F4+L3

# Filament 5 host (new or migrated apps)
composer require filamentcraft/filamentcraft  # resolves to F5+L4

Composer picks the pair that matches your installed Filament/Livewire automatically.

Migrating an existing host from Filament 4 → 5

1. Read the official Filament v5 upgrade guide first — https://filamentphp.com/docs/5.x/upgrade-guide. It ships an automated vendor/bin/filament-v5 script.
2. Bump Filament: composer require filament/filament:^5.0 livewire/livewire:^4.0 -W.
3. filament/blueprint: Blueprint v1.x caps filament/support: ^4.0. If your host depends on Blueprint, either bump to a v5-compatible Blueprint release (when available) or composer remove filament/blueprint --dev temporarily.
4. Rebuild caches: php artisan config:clear && php artisan view:clear && php artisan optimize:clear.
5. Run your test suite to catch Livewire 4's small breaking changes.

FilamentCraft itself needs no changes — composer update resolves the package's existing dual-version constraints onto the new pair.

What you can rely on

• Identical behaviour across both pairs.
• One bundle, both versions. The editor's JS (resources/dist/editor.js, resources/dist/iframe-injected.js) is the same file regardless of which version you're on — it negotiates the Livewire API at runtime.
• No runtime version-sniffing in PHP. No version_compare() checks. The intersection of APIs is the only surface used.