Filament v3 → v4 Migration: Breaking Changes Guide | Mohamed Said [ ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MH.png) Mohamed Said Laravel Backend Engineer ](https://msaied.com) [ Home ](https://msaied.com) [ Projects ](https://msaied.com/projects) [ Articles ](https://msaied.com/articles) [ Certificates ](https://msaied.com/certificates) [ Contact ](https://msaied.com#contact-section) [ ](https://github.com/EG-Mohamed) [ Home ](https://msaied.com) [ Projects ](https://msaied.com/projects) [ Articles ](https://msaied.com/articles) [ Certificates ](https://msaied.com/certificates) [ Contact ](https://msaied.com#contact-section) [ home ](https://msaied.com) [ articles ](https://msaied.com/articles) Filament v3 to v4: Breaking Changes and Practical Refactor Patterns On this page 1. [ Filament v3 → v4: Breaking Changes and Practical Refactor Patterns ](#filament-v3-v4-breaking-changes-and-practical-refactor-patterns) 2. [ 1. The Unified Schema API ](#1-the-unified-schema-api) 3. [ 2. Action Class Signatures ](#2-action-class-signatures) 4. [ 3. Column and Field extraAttributes Merge Behaviour ](#3-column-and-field-codeextraattributescode-merge-behaviour) 5. [ 4. Panel Provider Boot Order ](#4-panel-provider-boot-order) 6. [ 5. Infolist Entry Namespace Move ](#5-infolist-entry-namespace-move) 7. [ Upgrade Checklist ](#upgrade-checklist) 8. [ Key Takeaways ](#key-takeaways) ![Filament v3 to v4: Breaking Changes and Practical Refactor Patterns](https://cdn.msaied.com/261/9f6e22fb99f40a6947cdaeda527ad8c1.png) #filament #laravel #upgrade #admin-panel Filament v3 to v4: Breaking Changes and Practical Refactor Patterns ===================================================================== 21 Jun 2026 4 min read ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said Table of contents 1. [ 01 Filament v3 → v4: Breaking Changes and Practical Refactor Patterns ](#filament-v3-v4-breaking-changes-and-practical-refactor-patterns) 2. [ 02 1. The Unified Schema API ](#1-the-unified-schema-api) 3. [ 03 2. Action Class Signatures ](#2-action-class-signatures) 4. [ 04 3. Column and Field extraAttributes Merge Behaviour ](#3-column-and-field-codeextraattributescode-merge-behaviour) 5. [ 05 4. Panel Provider Boot Order ](#4-panel-provider-boot-order) 6. [ 06 5. Infolist Entry Namespace Move ](#5-infolist-entry-namespace-move) 7. [ 07 Upgrade Checklist ](#upgrade-checklist) 8. [ 08 Key Takeaways ](#key-takeaways) Filament v3 → v4: Breaking Changes and Practical Refactor Patterns ------------------------------------------------------------------ Filament v4 is not a cosmetic release. The schema-based form and infolist API is a genuine architectural shift, and several method signatures changed in ways that will silently break behaviour if you only run `composer update` and call it done. This article walks through the highest-impact changes and shows concrete before/after code so you can plan your migration sprint. --- ### 1. The Unified Schema API In v3, `form()` and `infolist()` each accepted a flat array of component objects. In v4 both methods receive a `Schema` instance, and components are registered through it. **v3** ```php public static function form(Form $form): Form { return $form->schema([ TextInput::make('name')->required(), Select::make('status')->options(Status::class), ]); } ``` **v4** ```php use Filament\Schemas\Schema; public static function form(Schema $schema): Schema { return $schema->components([ TextInput::make('name')->required(), Select::make('status')->options(Status::class), ]); } ``` The `Form` type hint is gone. If you type-hint `Form` in a v4 panel, the method simply will not be called — no exception, just a blank form. Run a project-wide search for `: Form` and `: Infolist` return types and replace them. --- ### 2. Action Class Signatures Table and page actions in v3 accepted a `Closure` for most modifiers. v4 enforces typed builder callbacks in several places and drops a handful of magic `$record`-injected closures in favour of explicit `fn (Model $record)` signatures. **v3 — implicit injection** ```php Action::make('approve') ->action(function ($record) { $record->approve(); }); ``` **v4 — explicit type** ```php Action::make('approve') ->action(function (Post $record): void { $record->approve(); }); ``` This is mostly additive, but if you relied on Filament resolving `$livewire`, `$table`, or `$form` from the closure signature, verify each one — some were removed from the resolver map. --- ### 3. Column and Field `extraAttributes` Merge Behaviour v3 merged extra HTML attributes with a simple `array_merge`, meaning later calls won. v4 uses a keyed deep-merge. If you called `extraAttributes()` twice on the same component expecting the second call to win, you now get both merged. Audit any component that chains `extraAttributes` more than once. --- ### 4. Panel Provider Boot Order v3 registered panel plugins inside `register()`. v4 moves plugin boot to a dedicated `boot()` hook on the plugin interface. If you wrote a custom plugin, implement `boot(Panel $panel): void` or your plugin's side effects (registering pages, widgets) will not fire. ```php class MyPlugin implements Plugin { public function getId(): string { return 'my-plugin'; } public function register(Panel $panel): void { // bind services } public function boot(Panel $panel): void { // register pages, widgets, nav items $panel->pages([MyPage::class]); } } ``` --- ### 5. Infolist Entry Namespace Move All infolist entry classes moved from `Filament\Infolists\Components` to `Filament\Schemas\Components\Infolists`. Your IDE will flag the missing imports, but if you have string-based component references in config files or dynamic resolution, those will fail silently at runtime. ```bash # Quick grep to find stale imports grep -r 'Filament\\Infolists\\Components' app/ --include='*.php' ``` --- ### Upgrade Checklist - Replace all `: Form` / `: Infolist` return types with `: Schema` - Change `->schema([])` calls on forms to `->components([])` - Add explicit model types to action closures - Audit double `extraAttributes()` chains - Implement `boot()` on any custom plugins - Update infolist entry namespaces - Run `php artisan filament:upgrade` (the official codemod handles ~60% of the above) - Run your Pest feature suite against a staging panel before deploying --- ### Key Takeaways - The `Schema` API is the single biggest surface-area change — fix type hints first. - Silent failures (blank forms, missing nav items) are more common than exceptions; test visually. - The official upgrade command is a starting point, not a finish line. - Custom plugins need a `boot()` method or they are effectively broken in v4. - Namespace moves are grep-able; automate the find-and-replace before manual review. Found this useful? [ ](https://twitter.com/intent/tweet?url=https%3A%2F%2Fmsaied.com%2Farticles%2Ffilament-v3-to-v4-breaking-changes-and-practical-refactor-patterns&text=Filament+v3+to+v4%3A+Breaking+Changes+and+Practical+Refactor+Patterns) [ ](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fmsaied.com%2Farticles%2Ffilament-v3-to-v4-breaking-changes-and-practical-refactor-patterns) Frequently Asked Questions ---------------------------- 3 questions Q01 Can I run Filament v3 and v4 panels side by side during migration? No. Filament v4 is a single Composer package version. You cannot mix v3 and v4 panel providers in the same application. Migrate all panels at once, or maintain a separate branch for the upgrade. Q02 Does `php artisan filament:upgrade` handle all the breaking changes automatically? It handles the most mechanical changes like form/infolist return type replacements and some namespace moves, but it cannot safely rewrite action closure signatures or plugin boot logic. Always review its diff and run your full test suite afterwards. Q03 Are third-party Filament plugins compatible with v4 out of the box? Only if the plugin author has released a v4-compatible version. Check the plugin's GitHub releases and composer.json constraints before upgrading. Many popular plugins had v4 releases within weeks of the stable launch, but niche ones may lag. Continue reading More Articles --------------- [ View all ](https://msaied.com/articles) [ ![Production AI Agents in Laravel: Streaming, Token Budgets, and Structured Output Contracts](https://cdn.msaied.com/262/4220ef4ee3875717c6384f298d891a3f.png) laravel ai llm ### Production AI Agents in Laravel: Streaming, Token Budgets, and Structured Output Contracts Ship reliable AI agents in Laravel by combining streamed responses, hard token budgets, and typed structured-o... ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said 22 Jun 2026 3 min read Read ](https://msaied.com/articles/production-ai-agents-in-laravel-streaming-token-budgets-and-structured-output-contracts) [ ![Laravel AI SDK: Tool-Calling Agents and Conversation Persistence](https://cdn.msaied.com/260/8c84f424e42da01993c9ba4b8eb19655.png) laravel ai agents ### Laravel AI SDK: Tool-Calling Agents and Conversation Persistence Build reliable tool-calling AI agents in Laravel using the Prism package. Learn how to wire tools, persist con... ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said 21 Jun 2026 3 min read Read ](https://msaied.com/articles/laravel-ai-sdk-tool-calling-agents-and-conversation-persistence) [ ![Laravel Livewire v3 Internals: Morph Markers, JS Hooks, and Alpine Integration](https://cdn.msaied.com/259/e8ce445f021c2b26ebe4dd5da50014f8.png) livewire laravel alpine ### Laravel Livewire v3 Internals: Morph Markers, JS Hooks, and Alpine Integration Go beyond the docs: understand how Livewire v3 diffs the DOM with morph markers, intercept the lifecycle with... ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said 21 Jun 2026 3 min read Read ](https://msaied.com/articles/laravel-livewire-v3-internals-morph-markers-js-hooks-and-alpine-integration) [ ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MH.png) Mohamed Said Laravel Backend Engineer ](https://msaied.com)Senior Backend Engineer specializing in Laravel, scalable SaaS platforms, APIs, and cloud infrastructure. I build secure, high-performance web applications that help businesses grow. Explore - [Home](https://msaied.com) - [Projects](https://msaied.com/projects) - [Articles](https://msaied.com/articles) - [Certificates](https://msaied.com/certificates) - [Contact](https://msaied.com#contact-section) Connect - [ hello@msaied.com ](mailto:hello@msaied.com) - [ +20 109 461 9204 ](tel:+201094619204) © 2026 Mohamed Said. All rights reserved. [ ](https://github.com/EG-Mohamed) [ ](https://www.linkedin.com/in/msaiedm/) [ ](https://wa.me/201094619204) [ ](mailto:hello@msaied.com) [ ](https://drive.google.com/file/u/0/d/1MF20IPRJyzfy32mhEutjL5EpSls0w2Q8/view)