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 v4 Migrating from v3: Breaking Changes and Refactor Patterns On this page 1. [ Filament v4: What Actually Breaks and How to Fix It ](#filament-v4-what-actually-breaks-and-how-to-fix-it) 2. [ 1. The Unified Schema Namespace ](#1-the-unified-schema-namespace) 3. [ 2. form() and infolist() Return Schema Now ](#2-codeformcode-and-codeinfolistcode-return-codeschemacode-now) 4. [ 3. Action Registration on Tables ](#3-action-registration-on-tables) 5. [ 4. Notification API ](#4-notification-api) 6. [ 5. Custom Fields and getFormattedState() ](#5-custom-fields-and-codegetformattedstatecode) 7. [ Practical Migration Checklist ](#practical-migration-checklist) 8. [ Key Takeaways ](#key-takeaways) ![Filament v4 Migrating from v3: Breaking Changes and Refactor Patterns](https://cdn.msaied.com/700/85cddaf32751d756924869323a845563.png) #filament #laravel #upgrade #filament-v4 Filament v4 Migrating from v3: Breaking Changes and Refactor Patterns ======================================================================= 25 Sep 2026 4 min read ![Mohamed Said](https://cdn.msaied.com/01M22N44A70A5MC2S599JP0MPH.webp) Mohamed Said Table of contents 1. [ 01 Filament v4: What Actually Breaks and How to Fix It ](#filament-v4-what-actually-breaks-and-how-to-fix-it) 2. [ 02 1. The Unified Schema Namespace ](#1-the-unified-schema-namespace) 3. [ 03 2. form() and infolist() Return Schema Now ](#2-codeformcode-and-codeinfolistcode-return-codeschemacode-now) 4. [ 04 3. Action Registration on Tables ](#3-action-registration-on-tables) 5. [ 05 4. Notification API ](#4-notification-api) 6. [ 06 5. Custom Fields and getFormattedState() ](#5-custom-fields-and-codegetformattedstatecode) 7. [ 07 Practical Migration Checklist ](#practical-migration-checklist) 8. [ 08 Key Takeaways ](#key-takeaways) Filament v4: What Actually Breaks and How to Fix It --------------------------------------------------- Filament v4 is not a cosmetic release. The shift to a unified Schema API, the reorganisation of form and infolist components into a single namespace, and the overhaul of action registration patterns all require deliberate refactoring. This article focuses on the changes that will actually break your application and shows you the exact patterns to fix them. --- ### 1. The Unified Schema Namespace In v3, form components lived under `Filament\Forms\Components` and infolist entries lived under `Filament\Infolists\Components`. In v4 both are unified under `Filament\Schemas\Components` (with the old namespaces aliased for a transitional period, but do not rely on aliases in new code). **v3** ```php use Filament\Forms\Components\TextInput; use Filament\Infolists\Components\TextEntry; ``` **v4** ```php use Filament\Schemas\Components\TextInput; use Filament\Schemas\Components\TextEntry; ``` Run a project-wide search for `Filament\\Forms\\Components` and `Filament\\Infolists\\Components` and replace them. Your IDE's structural search-and-replace handles this in seconds. --- ### 2. `form()` and `infolist()` Return `Schema` Now Both `form()` and `infolist()` on a Resource now return `Filament\Schemas\Schema` instead of their v3-specific types. **v3** ```php public static function form(Form $form): Form { return $form->schema([...]); } ``` **v4** ```php use Filament\Schemas\Schema; public static function form(Schema $schema): Schema { return $schema->components([...]); } ``` Note the method rename: `->schema()` becomes `->components()`. This is the single most common compile error you will hit. --- ### 3. Action Registration on Tables Table actions in v3 were registered via `->actions([])` directly on the table. In v4, header actions and row actions are separated more explicitly, and the `Action` import path changed. **v3** ```php use Filament\Tables\Actions\Action; $table->actions([ Action::make('approve')->action(fn ($record) => $record->approve()), ]); ``` **v4** ```php use Filament\Actions\Action; $table->recordActions([ Action::make('approve')->action(fn ($record) => $record->approve()), ]); ``` The `Filament\Actions\Action` class is now the single canonical action class across forms, tables, and infolists. The old `Filament\Tables\Actions\Action` is aliased but deprecated. --- ### 4. Notification API The static `Notification::make()` chaining API is unchanged, but `->send()` now requires no arguments where previously some methods accepted a `$livewire` parameter. If you passed `$this` explicitly, remove it. ```php // v3 (still works but emits deprecation) Notification::make()->title('Saved')->success()->send($this); // v4 Notification::make()->title('Saved')->success()->send(); ``` --- ### 5. Custom Fields and `getFormattedState()` If you built custom field plugins, the `getFormattedState()` method signature changed. It no longer receives `$record` as a parameter — state is resolved through the component's own `$state` property via the new `HasState` contract. ```php // v4 custom field public function getFormattedState(): mixed { return strtoupper($this->getState() ?? ''); } ``` Remove any `$record` parameter from your overrides or you will get a method signature mismatch at runtime. --- ### Practical Migration Checklist - **Namespace sweep**: replace `Forms\Components` and `Infolists\Components` with `Schemas\Components`. - **Method rename**: `->schema([])` → `->components([])` on Schema instances. - **Action import**: consolidate to `Filament\Actions\Action`. - **Table method**: `->actions()` → `->recordActions()` for row-level actions. - **Notification**: drop the `$this` argument from `->send()`. - **Custom fields**: remove `$record` from `getFormattedState()` overrides. - **Run `php artisan filament:upgrade`**: the official upgrade command patches many of these automatically, but always review its diff before committing. --- ### Key Takeaways - The unified Schema API is the conceptual core of v4; embrace it rather than leaning on aliases. - `->schema()` → `->components()` is the most frequent compile-time error. - Action classes are now centralised — one import path for all contexts. - The official upgrade command handles boilerplate but misses custom plugin internals. - Test your Filament resources with Pest after migration; form assertion helpers still work but method names on `livewire()->assertFormFieldExists()` are unchanged. Found this useful? [ ](https://twitter.com/intent/tweet?url=https%3A%2F%2Fmsaied.com%2Farticles%2Ffilament-v4-migrating-from-v3-breaking-changes-and-refactor-patterns-1&text=Filament+v4+Migrating+from+v3%3A+Breaking+Changes+and+Refactor+Patterns) [ ](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fmsaied.com%2Farticles%2Ffilament-v4-migrating-from-v3-breaking-changes-and-refactor-patterns-1) Frequently Asked Questions ---------------------------- 3 questions Q01 Can I upgrade a large Filament v3 app incrementally, or must it be all-at-once? Filament v4 ships compatibility aliases for the most common v3 namespaces, so you can upgrade the package and then migrate files panel-by-panel. However, aliases emit deprecation notices and will be removed in a future minor, so treat incremental migration as a short-term strategy, not a permanent state. Q02 Does `php artisan filament:upgrade` handle all the breaking changes automatically? It handles the mechanical renames — namespace replacements, method renames on Schema, and action import paths. It does not touch custom field plugins, custom columns with overridden methods, or any logic inside closures. Always review the git diff it produces before committing. Q03 Are Pest-based Filament tests affected by the v4 migration? The Filament testing helpers (`livewire()->fillForm()`, `->assertFormFieldExists()`, etc.) are largely unchanged in v4. The main risk is that test fixtures that reference old component class names will fail to resolve. Update your `use` statements in test files the same way you do in resources. Continue reading More Articles --------------- [ View all ](https://msaied.com/articles) [ ![Livewire v3 Islands, Lazy Components, and Deferred Loading in Practice](https://cdn.msaied.com/699/2667012bbe680cb54d99e4596e396547.png) livewire laravel performance ### Livewire v3 Islands, Lazy Components, and Deferred Loading in Practice Lazy components and deferred loading in Livewire v3 let you ship fast initial pages and hydrate expensive UI o... ![Mohamed Said](https://cdn.msaied.com/01M22N44A70A5MC2S599JP0MPH.webp) Mohamed Said 25 Sep 2026 1 min read Read ](https://msaied.com/articles/livewire-v3-islands-lazy-components-and-deferred-loading-in-practice-4) [ ![Auto-Load Generated Columns After Save with Laravel's #[Refreshes] Attribute](https://cdn.msaied.com/697/2450936023128760d64547a61ee24087.png) Laravel Eloquent Generated Columns ### Auto-Load Generated Columns After Save with Laravel's #\[Refreshes\] Attribute Laravel 13.33 introduced the #\[Refreshes\] PHP attribute for Eloquent models. Declare which database-computed c... ![Mohamed Said](https://cdn.msaied.com/01M22N44A70A5MC2S599JP0MPH.webp) Mohamed Said 23 Sep 2026 4 min read Read ](https://msaied.com/articles/auto-load-generated-columns-after-save-with-laravels-refreshes-attribute) [ ![Laravel AI SDK 1.0: Classification, Tool Approvals, and Vercel Chat Streaming](https://cdn.msaied.com/696/4a8dc0443e01d9ddfd47cae8515f2943.png) Laravel AI SDK Classification Tool Approvals ### Laravel AI SDK 1.0: Classification, Tool Approvals, and Vercel Chat Streaming Laravel AI SDK 1.0 ships a new Classification capability, human-in-the-loop tool approvals, Vercel Chat and AG... ![Mohamed Said](https://cdn.msaied.com/01M22N44A70A5MC2S599JP0MPH.webp) Mohamed Said 23 Sep 2026 4 min read Read ](https://msaied.com/articles/laravel-ai-sdk-10-classification-tool-approvals-and-vercel-chat-streaming) [ ![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)