Filament v3 → v4 Migration: Breaking Changes & Patterns | 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 v3 to v4: Breaking Changes, Migration Patterns, and Refactor Strategies Filament v3 to v4: Breaking Changes, Migration Patterns, and Refactor Strategies ================================================================================= A practical, opinionated guide to migrating a real Filament v3 application to v4—covering schema API changes, deprecated helpers, and the refactor patterns that keep your panels maintainable. ![](https://cdn.msaied.com/01M22N44A70A5MC2S599JP0MPH.webp) [Mohamed Said](https://www.msaied.com/public#person) Published 7 Jul 2026 · Updated 7 Jul 2026 · 4 min read ShareCopy linkCopied ![Filament v3 to v4: Breaking Changes, Migration Patterns, and Refactor Strategies](https://cdn.msaied.com/384/f36ae5ebd4fe74ef168cd02f23936d7d.png) On this page +1. [Why v4 Is Not a Drop-In Upgrade](#why-v4-is-not-a-drop-in-upgrade) 2. [1. The Schema API: What Actually Changed](#1-the-schema-api-what-actually-changed) 3. [Grid and Section Changes](#grid-and-section-changes) 4. [2. Infolist Refactors](#2-infolist-refactors) 5. [3. Action Class Signature Changes](#3-action-class-signature-changes) 6. [4. Updating Pest Tests](#4-updating-pest-tests) 7. [Migration Checklist](#migration-checklist) 8. [Takeaways](#takeaways) Why v4 Is Not a Drop-In Upgrade ------------------------------- Filament v4 ships a unified Schema API that collapses the previously separate `Form`, `Infolist`, and `Table` component trees into a single composable layer. That architectural shift is the source of most breaking changes. If you treat the upgrade as a find-and-replace exercise you will miss subtle runtime errors that only surface on specific resource actions. This article walks through the highest-impact changes and the refactor patterns that keep your panels clean. --- 1. The Schema API: What Actually Changed ---------------------------------------- In v3, form schemas lived inside `form(Form $form)` and infolist schemas inside `infolist(Infolist $infolist)`. Both accepted a flat array of components. In v4 both methods accept a `Schema` object, and components are now schema-aware nodes. **v3 form method:** ```php public static function form(Form $form): Form { return $form->schema([ TextInput::make('name')->required(), Select::make('status')->options(Status::class), ]); } ``` **v4 equivalent:** ```php public static function form(Form $form): Form { return $form->schema([ TextInput::make('name')->required(), Select::make('status')->options(Status::class), ]); } ``` The method signature looks identical for simple cases—but the moment you use layout components the differences appear. ### Grid and Section Changes v3 `Grid::make(2)` accepted a `columns` integer as the first argument. v4 moves column configuration to a fluent method: ```php // v3 Grid::make(2)->schema([...]); // v4 Grid::make()->columns(2)->schema([...]); ``` This is a silent failure: v3 code compiles in v4 but `Grid::make(2)` now creates a grid with the default column count and ignores the integer, because the first parameter is no longer `$columns`. --- 2. Infolist Refactors --------------------- v3 infolists used `TextEntry`, `ImageEntry`, and `IconEntry` from `Filament\Infolists\Components`. v4 retains these classes but the `state()` helper is removed in favour of direct model attribute binding through `->record()`. If you were calling `->state(fn ($record) => $record->full_name)` you must switch to a computed attribute or a custom `->getStateUsing()` closure: ```php // v3 — removed in v4 TextEntry::make('display_name') ->state(fn (User $record): string => $record->first_name.' '.$record->last_name), // v4 TextEntry::make('display_name') ->getStateUsing(fn (User $record): string => $record->first_name.' '.$record->last_name), ``` --- 3. Action Class Signature Changes --------------------------------- Table actions in v3 accepted `$record` as a typed parameter in closures. v4 enforces named argument injection via the container, which means positional assumptions break: ```php // v3 — positional, works by convention Action::make('approve') ->action(function (Order $record, array $data): void { $record->approve($data['note']); }), // v4 — explicit named injection, always safe Action::make('approve') ->action(function (array $data, Order $record): void { $record->approve($data['note']); }), ``` The order no longer matters in v4 because arguments are resolved by name, but you must ensure your closure parameter names match what Filament injects (`$record`, `$data`, `$livewire`, `$component`). --- 4. Updating Pest Tests ---------------------- Filament's test helpers gained stricter type assertions in v4. The `assertFormFieldExists` helper now requires the full dot-notation path for nested schema components: ```php // v3 livewire(EditOrder::class, ['record' => $order->getRouteKey()]) ->assertFormFieldExists('status'); // v4 — nested inside a Section livewire(EditOrder::class, ['record' => $order->getRouteKey()]) ->assertFormFieldExists('status', 'form', 'details_section'); ``` Run your full Pest suite immediately after upgrading. Schema path mismatches surface here before they surface in the browser. --- Migration Checklist ------------------- - Replace `Grid::make(int)` with `Grid::make()->columns(int)` across all resources. - Swap `->state()` on infolist entries for `->getStateUsing()`. - Audit action closures for positional `$record` assumptions; switch to named parameters. - Update Pest assertions that reference nested schema paths. - Re-publish vendor assets: `php artisan filament:upgrade && php artisan filament:assets`. - Check any custom field plugins for `ComponentContainer` references—this class was renamed in v4. --- Takeaways --------- - The unified Schema API is the architectural core of v4; understand it before touching code. - `Grid::make(int)` silently misbehaves—it is the most common hidden regression. - Action closure injection is now container-driven; parameter order is irrelevant but names are not. - Pest test paths for nested components changed; update assertions before declaring the migration done. - Run `filament:upgrade` as the first step, not the last. - [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 --------------------------- Is Filament v4 backwards compatible with v3 custom field plugins?Not fully. Plugins that reference `ComponentContainer` directly will break because the class was renamed in v4. You need to update the import and any method calls that relied on the old container API before the plugin will render correctly. Do I need to republish all Filament assets after upgrading to v4?Yes. Run `php artisan filament:upgrade` followed by `php artisan filament:assets` to ensure compiled JS and CSS assets match the v4 component tree. Stale v3 assets cause subtle UI regressions that are hard to trace. Will my v3 Pest tests pass after upgrading to v4?Tests that assert on top-level form fields often pass, but any test using `assertFormFieldExists` on a field nested inside a Section or Grid will fail because v4 requires the full dot-notation schema path. Audit and update those assertions as part of the migration. ![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 articleLaravel AI SDK: Tool-Calling Agents and Conversation Persistence](https://www.msaied.com/public/articles/laravel-ai-sdk-tool-calling-agents-and-conversation-persistence-2) [Next articleProduction AI Agents in Laravel: Streaming, Token Budgets, and Structured Output Contracts](https://www.msaied.com/public/articles/production-ai-agents-in-laravel-streaming-token-budgets-and-structured-output-contracts-2) On this page ------------- 1. [Why v4 Is Not a Drop-In Upgrade](#why-v4-is-not-a-drop-in-upgrade) 2. [1. The Schema API: What Actually Changed](#1-the-schema-api-what-actually-changed) 3. [Grid and Section Changes](#grid-and-section-changes) 4. [2. Infolist Refactors](#2-infolist-refactors) 5. [3. Action Class Signature Changes](#3-action-class-signature-changes) 6. [4. Updating Pest Tests](#4-updating-pest-tests) 7. [Migration Checklist](#migration-checklist) 8. [Takeaways](#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)