Filament v3 → v4 Migration: Breaking Changes Guide | Mohamed Said [Skip to content](#main) [ ![](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MH.png) Mohamed SaidLaravel Backend Engineer ](https://www.msaied.com/public) - [Home](https://www.msaied.com/public) - [Projects](https://www.msaied.com/public/projects) - [Articles](https://www.msaied.com/public/articles) - [Certificates](https://www.msaied.com/public/certificates) - [About](https://www.msaied.com/public#about) [ Contact](https://www.msaied.com/public#contact) Menu Menu ---- Close - [HomeStart here](https://www.msaied.com/public) - [ProjectsCase studies](https://www.msaied.com/public/projects) - [ArticlesEngineering notes](https://www.msaied.com/public/articles) - [CertificatesCredentials](https://www.msaied.com/public/certificates) - [AboutHow I work](https://www.msaied.com/public#about) - [ContactGet in touch](https://www.msaied.com/public#contact) [Start a conversation](https://www.msaied.com/public#contact) [WhatsApp](https://wa.me/201094619204) [Email](mailto:hello@msaied.com) 1. [Home](https://www.msaied.com/public) 2. / 3. [Articles](https://www.msaied.com/public/articles) 4. / 5. Filament v4 Migrating from v3: Breaking Changes and Refactor Patterns Filament v4 Migrating from v3: Breaking Changes and Refactor Patterns ====================================================================== A practical, opinionated guide to the most impactful breaking changes when upgrading Filament v3 to v4, with concrete refactor patterns and code examples for senior engineers. ![](https://cdn.msaied.com/01M22N44A70A5MC2S599JP0MPH.webp) [Mohamed Said](https://www.msaied.com/public#person) Published 25 Sep 2026 · Updated 25 Sep 2026 · 4 min read ShareCopy linkCopied ![Filament v4 Migrating from v3: Breaking Changes and Refactor Patterns](https://cdn.msaied.com/700/85cddaf32751d756924869323a845563.png) 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: 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. - [filament](https://www.msaied.com/public/articles?search=filament) - [laravel](https://www.msaied.com/public/articles?search=laravel) - [upgrade](https://www.msaied.com/public/articles?search=upgrade) - [filament-v4](https://www.msaied.com/public/articles?search=filament-v4) Frequently asked questions --------------------------- 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. 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. 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. ![Mohamed Said](https://cdn.msaied.com/01M22N44A70A5MC2S599JP0MPH.webp)About the author ---------------- [Mohamed Said](https://www.msaied.com/public#person)Senior Backend Engineer specializing in Laravel, scalable SaaS platforms, APIs, and cloud infrastructure. I build secure, high-performance web applications that help businesses grow. [About](https://www.msaied.com/public#about) [GitHub ↗](https://github.com/EG-Mohamed) [LinkedIn ↗](https://www.linkedin.com/in/msaiedm/) [WhatsApp ↗](https://wa.me/201094619204) [Email Address ↗](mailto:hello@msaied.com) [My CV ↗](https://drive.google.com/file/u/0/d/1MF20IPRJyzfy32mhEutjL5EpSls0w2Q8/view) [Previous articleLivewire v3 Islands, Lazy Components, and Deferred Loading in Practice](https://www.msaied.com/public/articles/livewire-v3-islands-lazy-components-and-deferred-loading-in-practice-4) [Next articleDecide with Jev: Build a Laravel AI Content Preflight Checker That Returns a Probability](https://www.msaied.com/public/articles/decide-with-jev-build-a-laravel-ai-content-preflight-checker-that-returns-a-probability) 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) ### Have a technical challenge? Tell me what you’re building. I reply within two working days. [Start a conversation](https://www.msaied.com/public#contact) Related articles ----------------- [ ![](https://cdn.msaied.com/740/cce86edc21eddcbdd2f2454fadaf9c70.png) · 3 min read### The Pipeline Pattern in Laravel: Custom Pipelines Beyond Middleware 5 Oct 2026 ](https://www.msaied.com/public/articles/the-pipeline-pattern-in-laravel-custom-pipelines-beyond-middleware-1) [ ![](https://cdn.msaied.com/739/2d6897fdcdcf090613f96f72a64b8a78.png) · 4 min read### MySQL Full-Text Search in Laravel: Indexes, Relevance Scoring, and Boolean Mode 4 Oct 2026 ](https://www.msaied.com/public/articles/mysql-full-text-search-in-laravel-indexes-relevance-scoring-and-boolean-mode) [ ![](https://cdn.msaied.com/738/073696a3fefe18bec825beec5ac658f5.png) · 4 min read### Laravel Queue Rate-Limited Middleware: Throttling Jobs Without Losing Work 4 Oct 2026 ](https://www.msaied.com/public/articles/laravel-queue-rate-limited-middleware-throttling-jobs-without-losing-work) Have a technical challenge? ---------------------------- Tell me what you’re building. I reply within two working days. [Discuss your project ↗](https://www.msaied.com/public#contact) © 2026 Mohamed Said · Built with Laravel, meant to last.Senior Backend Engineer specializing in Laravel, scalable SaaS platforms, APIs, and cloud infrastructure. I build secure, high-performance web applications that help businesses grow. - [Home](https://www.msaied.com/public) - [Articles](https://www.msaied.com/public/articles) - [Certificates](https://www.msaied.com/public/certificates) - [GitHub](https://github.com/EG-Mohamed) - [LinkedIn](https://www.linkedin.com/in/msaiedm/) - [WhatsApp](https://wa.me/201094619204) - [Email Address](mailto:hello@msaied.com) - [My CV](https://drive.google.com/file/u/0/d/1MF20IPRJyzfy32mhEutjL5EpSls0w2Q8/view) - [Sitemap](https://www.msaied.com/public/sitemap.xml)