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: post-morph rebinding. The editor's JS subscribes through Livewire.hook('morphed', scheduleRebind) — morphed fires once per component after its subtree is fully morphed, in both v3 and v4 — with a document.addEventListener('livewire:update', scheduleRebind) fallback for environments where the hook is unavailable. The two are coalesced, so when both fire for one update only a single rebind runs.

Supported matrix

CI runs the full test suite on every combination of PHP 8.2 / 8.3 / 8.4 × Laravel 11 / 12 × the two version pairs (Filament 4 + Livewire 3, Filament 5 + Livewire 4), minus the PHP 8.2 + Laravel 12 pair — 10 combinations:

PHP	Laravel	Filament	Livewire
8.2	11.x	4.x	3.x
8.2	11.x	5.x	4.x
8.3	11.x	4.x	3.x
8.3	11.x	5.x	4.x
8.3	12.x	4.x	3.x
8.3	12.x	5.x	4.x
8.4	11.x	4.x	3.x
8.4	11.x	5.x	4.x
8.4	12.x	4.x	3.x
8.4	12.x	5.x	4.x

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

Static analysis runs separately, in two legs (both on PHP 8.3): PHPStan on F4 + L3 is the strict gate; the F5 + L4 leg runs continue-on-error until upstream Pest 4 / Livewire 4 stubs propagate their generics correctly.

The package's Composer constraints also allow illuminate/*: ^11 || ^12 || ^13, so a Laravel 13 host resolves without a package update.

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.