Filament v3 to v4 Migration: Breaking Changes | 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. [ Why v3→v4 Is a Real Migration, Not a Bump ](#why-v3v4-is-a-real-migration-not-a-bump) 2. [ 1. The Schema API Replaces Separate form() and infolist() Builders ](#1-the-schema-api-replaces-separate-codeformcode-and-codeinfolistcode-builders) 3. [ 2. ->schema() → ->components() on Layouts ](#2-code-gtschemacode-code-gtcomponentscode-on-layouts) 4. [ 3. Removed Static Helpers on Action ](#3-removed-static-helpers-on-codeactioncode) 5. [ 4. Table Column ->getStateUsing() Signature Change ](#4-table-column-code-gtgetstateusingcode-signature-change) 6. [ 5. Refactor Pattern: Extract a SchemaBuilder Class ](#5-refactor-pattern-extract-a-codeschemabuildercode-class) 7. [ Key Takeaways ](#key-takeaways) ![Filament v4 Migrating from v3: Breaking Changes and Refactor Patterns](https://cdn.msaied.com/472/bb7fbf8441c775fcfadd23850e1756e8.png) #filament #laravel #migration #filament-v4 Filament v4 Migrating from v3: Breaking Changes and Refactor Patterns ======================================================================= 26 Jul 2026 4 min read ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said Table of contents 1. [ 01 Why v3→v4 Is a Real Migration, Not a Bump ](#why-v3v4-is-a-real-migration-not-a-bump) 2. [ 02 1. The Schema API Replaces Separate form() and infolist() Builders ](#1-the-schema-api-replaces-separate-codeformcode-and-codeinfolistcode-builders) 3. [ 03 2. ->schema() → ->components() on Layouts ](#2-code-gtschemacode-code-gtcomponentscode-on-layouts) 4. [ 04 3. Removed Static Helpers on Action ](#3-removed-static-helpers-on-codeactioncode) 5. [ 05 4. Table Column ->getStateUsing() Signature Change ](#4-table-column-code-gtgetstateusingcode-signature-change) 6. [ 06 5. Refactor Pattern: Extract a SchemaBuilder Class ](#5-refactor-pattern-extract-a-codeschemabuildercode-class) 7. [ 07 Key Takeaways ](#key-takeaways) Why v3→v4 Is a Real Migration, Not a Bump ----------------------------------------- Filament v4 is not a cosmetic release. The team unified forms, infolists, and table columns under a single **Schema API**, removed a handful of convenience statics, and changed how component state flows through resources. If you have a mid-size panel with 20+ resources, expect a focused but non-trivial refactor. This article walks through the highest-impact changes with concrete before/after examples. --- 1. The Schema API Replaces Separate `form()` and `infolist()` Builders ---------------------------------------------------------------------- In v3, `form()` returned a `Form` and `infolist()` returned an `Infolist`. In v4 both accept a `Schema` and share the same component tree. **v3** ```php public static function form(Form $form): Form { return $form->schema([ Forms\Components\TextInput::make('name')->required(), ]); } public static function infolist(Infolist $infolist): Infolist { return $infolist->schema([ Infolists\Components\TextEntry::make('name'), ]); } ``` **v4** ```php use Filament\Schemas\Schema; public static function form(Schema $schema): Schema { return $schema->components([ Forms\Components\TextInput::make('name')->required(), ]); } public static function infolist(Schema $schema): Schema { return $schema->components([ Infolists\Components\TextEntry::make('name'), ]); } ``` The method signature change is the first thing your IDE will flag. Run a project-wide search for `Form $form` and `Infolist $infolist` in resource files. --- 2. `->schema()` → `->components()` on Layouts --------------------------------------------- Every layout component (`Grid`, `Section`, `Fieldset`, `Tabs\Tab`, etc.) that previously accepted `->schema([...])` now uses `->components([...])`. ```php // v3 Forms\Components\Section::make('Details') ->schema([ Forms\Components\TextInput::make('email'), ]); // v4 Forms\Components\Section::make('Details') ->components([ Forms\Components\TextInput::make('email'), ]); ``` This is the most widespread mechanical change. A simple regex replacement handles 90% of it: ```bash # dry-run first grep -rn '->schema(\[' app/Filament # replace (macOS sed) find app/Filament -name '*.php' \ -exec sed -i '' 's/->schema(\[/->components([/g' {} + ``` Verify manually — `->schema()` still exists on the root `Schema` object itself, so a blanket replace will over-correct. --- 3. Removed Static Helpers on `Action` ------------------------------------- Several static convenience methods on `Action` were removed in favour of explicit closures. ```php // v3 — no longer exists Action::make('approve') ->requiresConfirmation() ->successNotificationTitle('Approved'); // v4 — use notification() explicitly Action::make('approve') ->requiresConfirmation() ->successNotification( Notification::make()->title('Approved')->success() ); ``` Check the changelog for the full list; `->failureNotificationTitle()` and `->successNotificationTitle()` are both gone. --- 4. Table Column `->getStateUsing()` Signature Change ---------------------------------------------------- Custom columns that used `->getStateUsing(fn ($record) => ...)` now receive a typed `$state` parameter when chained after `->state()`. ```php // v4 — explicit state pipeline TextColumn::make('status_label') ->state(fn (Order $record): string => $record->status->value) ->formatStateUsing(fn (string $state): string => Str::title($state)); ``` Separating state resolution from formatting is cleaner and easier to test in isolation. --- 5. Refactor Pattern: Extract a `SchemaBuilder` Class ---------------------------------------------------- For large resources, avoid bloating `form()` and `infolist()` with inline logic. Extract a dedicated class: ```php final class OrderSchemaBuilder { public static function form(): array { return [ TextInput::make('reference')->required(), Select::make('status')->options(OrderStatus::class), ]; } public static function infolist(): array { return [ TextEntry::make('reference'), TextEntry::make('status')->badge(), ]; } } // In OrderResource public static function form(Schema $schema): Schema { return $schema->components(OrderSchemaBuilder::form()); } ``` This pattern survives future API shifts because the resource itself becomes a thin adapter. --- Key Takeaways ------------- - `Form $form` / `Infolist $infolist` signatures become `Schema $schema` — update every resource. - `->schema([])` on layout components becomes `->components([])` — automate with a careful find-replace. - `->successNotificationTitle()` and `->failureNotificationTitle()` are removed; use `->successNotification()` with a `Notification` object. - Separate state resolution (`->state()`) from formatting (`->formatStateUsing()`) in table columns. - Extract `SchemaBuilder` classes for large resources to isolate your domain logic from Filament's API surface. 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&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) Frequently Asked Questions ---------------------------- 3 questions Q01 Can I migrate resources one at a time, or does v4 require all-at-once? Filament v4 is a hard dependency upgrade, so all resources must be compatible before you can run the application. However, you can batch the mechanical changes (schema/components rename) with a script and then address the action/notification API changes resource by resource. Q02 Does the `->schema()` method still exist anywhere in v4? Yes — the root `Schema` object passed into `form()` and `infolist()` still exposes `->components()` as the primary method. The `->schema()` alias was removed from layout components like Section and Grid, which is where the confusion arises. Q03 Are custom Filament v3 field plugins compatible with v4 out of the box? Usually not without changes. Plugins that extend `Field` or `Column` and call `->schema()` internally need updating. Check the plugin's GitHub issues or changelog before upgrading, and pin the plugin version until the maintainer ships a v4-compatible release. Continue reading More Articles --------------- [ View all ](https://msaied.com/articles) [ ![Concurrency in Laravel: Process Pools, Fibers, and the Concurrency Facade](https://cdn.msaied.com/471/ba1a628c196e92cbb81033c865c9ad26.png) laravel concurrency php ### Concurrency in Laravel: Process Pools, Fibers, and the Concurrency Facade Laravel's Concurrency facade and process pools let you run independent work in parallel without reaching for a... ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said 26 Jul 2026 4 min read Read ](https://msaied.com/articles/concurrency-in-laravel-process-pools-fibers-and-the-concurrency-facade) [ ![Laravel Queues in Production: Horizon Tuning, Metrics, and Graceful Scaling](https://cdn.msaied.com/470/afd2bee56d15842d72c1c6d5c238d236.png) laravel horizon queues ### Laravel Queues in Production: Horizon Tuning, Metrics, and Graceful Scaling Go beyond basic queue setup. Learn how to tune Horizon supervisor processes, interpret queue metrics, handle b... ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said 26 Jul 2026 3 min read Read ](https://msaied.com/articles/laravel-queues-in-production-horizon-tuning-metrics-and-graceful-scaling) [ ![Laravel Horizon: Queue Metrics, Supervisor Tuning, and Graceful Scaling in Production](https://cdn.msaied.com/469/ebbc461b808da425a418bf6ffc998d7a.png) laravel horizon queues ### Laravel Horizon: Queue Metrics, Supervisor Tuning, and Graceful Scaling in Production Beyond the dashboard: how to tune Horizon supervisors, interpret queue metrics, and scale workers gracefully w... ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said 25 Jul 2026 3 min read Read ](https://msaied.com/articles/laravel-horizon-queue-metrics-supervisor-tuning-and-graceful-scaling-in-production-1) [ ![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)