Filament upgrade: van Filament 3 naar 4 of 5 in 7 stappen

Een Filament upgrade van v3 naar v4 is grotendeels geautomatiseerd: het officiële filament/upgrade-package herschrijft je code met Rector. Daarna volgt v5 met dezelfde API, alleen op Livewire 4. Het echte werk zit in custom themes (Tailwind v4), plugins en testen. Sinds 1 augustus 2026 krijgt v3 geen bugfixes meer.

Moet je nu upgraden van Filament 3?

Ja, plan het in. Volgens het officiële version support policy van Filament stopten de bugfixes voor v3 op 1 augustus 2026. Security fixes lopen nog tot 1 januari 2028.

Dat klinkt als ruim de tijd. De eerlijke versie: elke maand wachten maakt de sprong groter. Plugins droppen v3-support, nieuwe Laravel-releases worden niet meer getest tegen v3, en Filament waarschuwt zelf dat onderliggende dependencies (PHP, Laravel, Livewire) eerder uit support kunnen lopen dan Filament zelf.

Let op: ook v4 heeft al een einddatum voor bugfixes. Wie nu van v3 vertrekt, kan dus het beste direct doorstomen naar v5.

Filament 3 naar 4 of direct naar 5?

Ga naar v5, maar via v4. Filament 5 heeft dezelfde API als v4; het verschil is Livewire 4-support. Alle inhoudelijke breaking changes zitten in de stap van v3 naar v4.

Daarom adviseren wij twee aparte stappen:

1. v3 → v4: het grote werk. Schemas, unified actions, Tailwind v4, nieuwe defaults.
2. v4 → v5: klein. Upgrade-script draaien en Livewire 4 bijwerken volgens de Livewire upgrade guide.

Elke stap apart committen, testen en eventueel deployen. Als er iets breekt, weet je dan in welke laag het zit. Wat er per versie nieuw is, lees je in Filament 4 en 5: wat is er nieuw.

Wat zijn de vereisten voor Filament 4 en 5?

PHP 8.2+, Laravel 11.28+ en Tailwind CSS v4 (als je een custom theme hebt). Voor v5 komt Livewire 4 erbij.

Draai je nog op Laravel 10? Dan is dat stap nul. Eerst Laravel upgraden, dan pas Filament. Niet tegelijk. Twee frameworks tegelijk upgraden maakt debuggen onnodig zwaar.

Hoe werkt het officiële upgrade-script?

Filament levert een eigen package, filament/upgrade, dat met Rector v2 je codebase herschrijft. Het team noemt het zelf "Laravel Shift, maar dan voor Filament". Het vangt de meeste breaking changes af, maar niet alle.

De commando's voor v3 → v4, letterlijk uit de officiële upgrade guide:

composer require filament/upgrade:"^4.0" -W --dev
vendor/bin/filament-v4

# Voer daarna de commando's uit die het script zelf print
# (die zijn per applicatie anders), bijvoorbeeld:
composer require filament/filament:"^4.0" -W --no-update
composer update

Twee valkuilen uit de docs:

• PHPStan-versie. Rector v2 vereist PHPStan v2 of hoger (of Larastan v3+). Faalt de installatie van het upgrade-package, check dit eerst.
• PowerShell. Op Windows gebruik je ~4.0 in plaats van ^4.0.

Na het script: review elke gewijzigde file. Rector kan formatting omgooien en klassen gebruiken die nog niet geïmporteerd zijn. Draai PHPStan om kapotte class-referenties te vinden en Pint om de code style weer recht te trekken.

Directorystructuur: optioneel

v4 introduceert een nieuwe mapstructuur voor resources en clusters. Je mag de oude houden. Wil je migreren:

php artisan filament:upgrade-directory-structure-to-v4 --dry-run
php artisan filament:upgrade-directory-structure-to-v4

Altijd eerst --dry-run. Daarna composer remove filament/upgrade --dev.

Daarna v4 → v5

composer require filament/upgrade:"^5.0" -W --dev
vendor/bin/filament-v5
composer require filament/filament:"^5.0" -W --no-update
composer update
composer remove filament/upgrade --dev

Volg daarna de Livewire 4 upgrade guide voor je eigen Livewire-componenten. Volgens de v5 upgrade guide is dat het grootste deel van deze stap.

Welke breaking changes raken je in Filament 4?

De grootste wijzigingen: Schemas vervangen Form en Infolist, alle actions zitten in één namespace, en een reeks defaults is omgedraaid. Het script vangt de namespaces af; de gedragswijzigingen moet je zelf controleren.

Schemas: Form en Infolist samengevoegd

In v4 vervangt Filament\Schemas\Schema de oude Filament\Forms\Form en Filament\Infolists\Infolist. Een resource-form ziet er zo uit:

use Filament\Schemas\Schema;
use Filament\Forms\Components\TextInput;

public static function form(Schema $schema): Schema
{
    return $schema->components([
        TextInput::make('title')->required(),
    ]);
}

Layout-componenten als Section en Grid horen nu bij Schemas. Daardoor kun je form fields, infolist entries en layout vrij combineren.

Unified actions

In v3 importeerde je per context een andere Action-klasse: Filament\Tables\Actions\EditAction, Filament\Forms\Components\Actions\Action, enzovoort. In v4 zit alles in Filament\Actions. Het upgrade-script herschrijft de imports. Eigen action-klassen die van een oude base class erven, moet je wel nalopen.

Gedragswijzigingen die het script niet oplost

Dit zijn de "high impact"-wijzigingen uit de officiële guide. Ze breken je code niet, maar veranderen wat gebruikers zien:

Vooral de file visibility verrast teams. Een productafbeelding die gisteren zichtbaar was, geeft na deploy een 403. Draai je multi-tenant? Lees dan ook Filament multi-tenancy voor SaaS voordat je de upgrade live zet.

Wat betekent Tailwind v4 voor je custom theme?

Heb je een custom theme of gebruik je Tailwind-classes in eigen Blade-views binnen het panel, dan moet je naar Tailwind v4. Zonder custom theme raakt dit je nauwelijks.

Filament v4 levert zijn eigen styling als CSS-bestanden. Tailwind-utilities in je eigen views worden daardoor niet meer automatisch meegebouwd. De oplossing volgens de docs: een custom theme aanmaken en je views daarin laten scannen.

Voor bestaande themes adviseert Filament de officiële Tailwind upgrade tool:

npx @tailwindcss/upgrade

Die zet je configuratie om naar de v4-opzet en vervangt de v3-packages. Controleer daarna visueel. Tailwind v4 heeft andere defaults voor onder meer borders en ring-kleuren. Dat zie je niet in een diff, wel in de browser.

Hoe check je of je plugins compatibel zijn?

Per plugin: kijk in de composer.json van de plugin welke filament/filament-versies hij ondersteunt. Geen v4- of v5-constraint betekent: nog niet klaar.

De officiële guide is daar nuchter over: plugins die nog geen v4-support hebben, haal je tijdelijk uit je composer.json tot ze bijgewerkt zijn. Dat werkt voor een nice-to-have. Niet voor een plugin waar je hele rechtenmodel op draait.

Zo pak je het aan:

1. Inventariseer. composer show | grep -i filament geeft alle Filament-gerelateerde packages.
2. Classificeer. Kritiek (rechten, multi-tenancy, media), belangrijk, of nice-to-have.
3. Check constraints. Ondersteunt de laatste release ^4.0 of ^5.0?
4. Besluit per plugin. Wachten, vervangen, of zelf bouwen.

Betaalde plugins van derden volgen vaak een eigen release-ritme. Een plugin die v4 ondersteunt, ondersteunt niet automatisch v5. Bij v5 moet de plugin ook Livewire 4 aankunnen. Welke plugins wij in de praktijk inzetten, staat in de beste Filament plugins.

Hoe test je een Filament upgrade?

Met geautomatiseerde tests vóór de upgrade, plus een handmatige rondgang door elk panel na de upgrade. Tests die je pas na de upgrade schrijft, bewijzen niets over regressies.

Vóór de upgrade

• Schrijf Pest- of PHPUnit-tests voor elke resource: list-pagina laadt, create en edit slaan op, validatie werkt.
• Test custom actions en hun autorisatie.
• Leg een screenshot vast van elke kritieke pagina. Saai, maar het vangt layoutverschuivingen.

Hoe je Filament-resources met Pest test, lees je in Filament testen met Pest.

Na de upgrade

• Draai de volledige testsuite. Fouten in namespaces en signatures komen hier direct boven.
• Draai PHPStan op het hoogste level dat je codebase aankan.
• Loop elk panel handmatig door, met de tabel uit de vorige sectie als checklist.
• Test file uploads en downloads op je echte storage-driver, niet alleen lokaal.
• Test als verschillende rollen. Policies en tenancy-scoping gedragen zich anders dan je denkt.

Deploy eerst naar staging met een kopie van productiedata. Pas dan productie.

Hoeveel werk is een Filament upgrade?

Dat hangt af van vier factoren, niet van het aantal resources. Een panel met vijftig standaard-resources is sneller klaar dan een panel met vijf zwaar aangepaste.

Vuistregel: staat alles links, dan is het script draaien, reviewen en testen het grootste deel van het werk. Staat er één factor rechts, dan bepaalt die factor de planning. Staan er meerdere rechts, splits het dan op. Eerst Laravel, dan tests, dan Filament.

Wat niemand je vertelt: de grootste tijdvreter is zelden de code. Het is de vraag "werkt dit nog zoals de gebruiker het gewend is?" Filters die nu een Apply-knop hebben, layouts die net anders vallen. Dat vraagt afstemming met de mensen die er dagelijks in werken.

Onze eigen backoffice draait op Filament 3 en staat zelf ook op de upgradelijst. Verwacht hetzelfde patroon als bij elke upgrade die het script grotendeels automatiseert: het controleren daarna is het eigenlijke werk.

Stappenplan: Filament 3 upgraden naar 5

1. Laravel op 11.28+, PHP op 8.2+. Eerst, los van Filament.
2. Tests schrijven voor elke resource en custom action.
3. Plugins inventariseren en per plugin een besluit nemen.
4. v3 → v4 met filament/upgrade. Script draaien, geprinte commando's uitvoeren, alles reviewen.
5. Tailwind v4 en custom theme bijwerken, visueel controleren.
6. Gedragswijzigingen nalopen: file visibility, deferred filters, layout spans, enums, tenancy.
7. v4 → v5 met het v5-script en de Livewire 4 upgrade guide. Opnieuw testen.

Samengevat

• Filament 3 krijgt sinds 1 augustus 2026 geen bugfixes meer; security fixes tot 1 januari 2028.
• Het officiële filament/upgrade-package gebruikt Rector v2 en vangt de meeste breaking changes af.
• Alle inhoudelijke breaking changes zitten in v3 → v4. v4 → v5 draait om Livewire 4.
• Grootste risico's: custom themes (Tailwind v4), plugins zonder v4/v5-support, en gewijzigde defaults zoals private file visibility.
• Tests vóór de upgrade schrijven. Anders test je niets.

Meer over Filament als platform voor backoffices en portalen lees je op onze Filament-pagina. Bredere Laravel-trajecten staan op Laravel maatwerk.

Veelgestelde vragen

Kan ik direct van Filament 3 naar 5 upgraden?

Technisch heeft Filament voor elke major een eigen upgrade-script: filament-v4 en filament-v5. Wij draaien ze na elkaar, met een test- en reviewmoment ertussen. Zo weet je bij een fout of die uit de v4-wijzigingen komt of uit Livewire 4.

Gebruikt de Filament upgrade Rector?

Ja. Het filament/upgrade-package gebruikt Rector v2, dat PHPStan v2 of hoger vereist. Het script herschrijft namespaces en signatures automatisch, maar kan formatting wijzigen en imports missen. Draai daarna PHPStan en Pint.

Is Filament 3 nog veilig te gebruiken?

Voorlopig wel: Filament levert security fixes voor v3 tot 1 januari 2028. Bugfixes zijn op 1 augustus 2026 gestopt. Filament waarschuwt zelf dat PHP, Laravel of Livewire eerder uit support kunnen raken, en dan loop je via die dependencies risico.

Moet ik mijn resources herschrijven voor Filament 4?

Meestal niet. Het upgrade-script past Form en Infolist aan naar Schema en zet actions in de Filament\Actions-namespace. Handwerk zit vooral in custom componenten, eigen views en de gewijzigde defaults zoals deferred filters en private file visibility.

Wat als een plugin Filament 4 of 5 nog niet ondersteunt?

De officiële guide adviseert de plugin tijdelijk uit composer.json te halen tot er een compatibele versie is. Voor kritieke plugins is dat geen optie. Dan wacht je met upgraden, vervang je de plugin of bouw je de functionaliteit zelf.

Moet ik de nieuwe directorystructuur van v4 gebruiken?

Nee. De migratie naar de nieuwe structuur voor resources en clusters is optioneel. Wil je het toch, draai dan eerst php artisan filament:upgrade-directory-structure-to-v4 --dry-run en bekijk wat er verplaatst wordt.

Twijfel je of je panel in één keer naar v5 kan, of wil je dat iemand meekijkt naar de plugins? Neem contact op.