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 v3 to v4 Migration: Breaking Changes and Practical Refactor Patterns On this page 1. [ Why v3→v4 Is Not a Minor Bump ](#why-v3v4-is-not-a-minor-bump) 2. [ 1. The Schema API Replaces form() and infolist() Signatures ](#1-the-schema-api-replaces-codeformcode-and-codeinfolistcode-signatures) 3. [ 2. Action Signature Changes ](#2-action-signature-changes) 4. [ 3. Custom Fields: getFormComponent() Is Gone ](#3-custom-fields-codegetformcomponentcode-is-gone) 5. [ 4. Repeatable Refactor Order ](#4-repeatable-refactor-order) 6. [ 5. Gotcha: Panel Provider Boot Order ](#5-gotcha-panel-provider-boot-order) 7. [ Key Takeaways ](#key-takeaways) ![Filament v3 to v4 Migration: Breaking Changes and Practical Refactor Patterns](https://cdn.msaied.com/198/66326ab03b7a5b33a766804a10502cb1.png) #filament #laravel #upgrade #filament-v4 Filament v3 to v4 Migration: Breaking Changes and Practical Refactor Patterns =============================================================================== 15 Jun 2026 3 min read ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said Table of contents 1. [ 01 Why v3→v4 Is Not a Minor Bump ](#why-v3v4-is-not-a-minor-bump) 2. [ 02 1. The Schema API Replaces form() and infolist() Signatures ](#1-the-schema-api-replaces-codeformcode-and-codeinfolistcode-signatures) 3. [ 03 2. Action Signature Changes ](#2-action-signature-changes) 4. [ 04 3. Custom Fields: getFormComponent() Is Gone ](#3-custom-fields-codegetformcomponentcode-is-gone) 5. [ 05 4. Repeatable Refactor Order ](#4-repeatable-refactor-order) 6. [ 06 5. Gotcha: Panel Provider Boot Order ](#5-gotcha-panel-provider-boot-order) 7. [ 07 Key Takeaways ](#key-takeaways) Why v3→v4 Is Not a Minor Bump ----------------------------- Filament v4 rewrites the form and infolist rendering layer around a unified **Schema API**. If your panels have custom fields, complex resource forms, or bespoke actions, you will touch almost every resource file. The good news: the changes are systematic, and a disciplined refactor order keeps the panel functional throughout. --- 1. The Schema API Replaces `form()` and `infolist()` Signatures --------------------------------------------------------------- In v3, `form()` received a `Form` instance and `infolist()` received an `Infolist` instance as separate contracts: ```php // v3 public static function form(Form $form): Form { return $form->schema([ TextInput::make('name')->required(), ]); } public static function infolist(Infolist $infolist): Infolist { return $infolist->schema([ TextEntry::make('name'), ]); } ``` In v4, both collapse into a single `schema()` method on the resource, and components are context-aware — the same schema renders as a form or infolist depending on the page: ```php // v4 public static function schema(): array { return [ TextInput::make('name') ->required() ->formOnly(), // visible only in form context TextEntry::make('name') ->infolistOnly(), // visible only in infolist context ]; } ``` For fields that behave identically in both contexts you simply omit the context modifier — the framework resolves the correct renderer automatically. --- 2. Action Signature Changes --------------------------- v3 table actions accepted a closure receiving the record: ```php // v3 Tables\Actions\Action::make('approve') ->action(fn (Order $record) => $record->approve()) ->requiresConfirmation(), ``` v4 introduces a typed `ActionArguments` contract and moves confirmation into a fluent builder chain: ```php // v4 Tables\Actions\Action::make('approve') ->action(function (Order $record, array $data): void { $record->approve(); }) ->confirm( title: 'Approve order?', description: 'This cannot be undone.', ), ``` The `requiresConfirmation()` shorthand still exists as an alias, but the explicit `confirm()` builder gives you translated strings and custom icon support without a modal component. --- 3. Custom Fields: `getFormComponent()` Is Gone ---------------------------------------------- v3 custom field plugins exposed `getFormComponent()` to return a Livewire view. v4 replaces this with a `render()` method that returns a `ComponentRenderer`: ```php // v3 public function getFormComponent(): string { return 'my-package::colour-swatch'; } // v4 public function render(): ComponentRenderer { return ComponentRenderer::make( view: 'my-package::colour-swatch', data: fn () => ['swatches' => $this->getSwatches()], ); } ``` This matters because `ComponentRenderer` participates in the deferred-loading pipeline, so your custom field gets lazy hydration for free. --- 4. Repeatable Refactor Order ---------------------------- Do not attempt a big-bang migration. Use this order to keep the panel green at each step: 1. **Upgrade composer deps** — `filament/filament:^4.0` with `--no-scripts` first. 2. **Run the upgrade command** — `php artisan filament:upgrade` patches the most mechanical changes (import paths, method renames). 3. **Fix schema methods** — convert `form()` / `infolist()` to `schema()` resource by resource. 4. **Audit custom fields** — replace `getFormComponent()` with `render()`. 5. **Review action closures** — add explicit type hints; test confirmation dialogs. 6. **Run Pest suite** — Filament's test helpers (`livewire(EditOrder::class)->fillForm([...])->call('save')`) are unchanged in v4, so existing feature tests catch regressions immediately. --- 5. Gotcha: Panel Provider Boot Order ------------------------------------ v4 defers panel registration to `booted()` instead of `boot()`. If you resolve panel-specific services inside `boot()` in a custom service provider, those services may not yet be registered: ```php // v4-safe: use booted() public function booted(): void { FilamentAsset::register([ Js::make('my-plugin', __DIR__ . '/../dist/my-plugin.js'), ]); } ``` --- Key Takeaways ------------- - The unified Schema API is the largest surface-area change; migrate resource by resource, not all at once. - `php artisan filament:upgrade` handles ~60% of mechanical renames — always run it first. - Custom field plugins must replace `getFormComponent()` with `ComponentRenderer::make()`. - Action confirmation moves to the fluent `confirm()` builder; `requiresConfirmation()` still works as an alias. - Existing Pest/Livewire test helpers are compatible — lean on them to validate each migrated resource before moving to the next. Found this useful? [ ](https://twitter.com/intent/tweet?url=https%3A%2F%2Fmsaied.com%2Farticles%2Ffilament-v3-to-v4-migration-breaking-changes-and-practical-refactor-patterns&text=Filament+v3+to+v4+Migration%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-migration-breaking-changes-and-practical-refactor-patterns) Frequently Asked Questions ---------------------------- 3 questions Q01 Can I migrate resources one at a time without breaking the whole panel? Yes. Filament v4 ships a compatibility shim for the v3 `form()` and `infolist()` signatures that emits a deprecation notice but does not throw. Migrate resource by resource, running your Pest suite after each one. Q02 Do Filament v3 custom field packages work in v4 without changes? Not without a small update. Any package that implements `getFormComponent()` must replace it with `render(): ComponentRenderer`. The view itself is usually unchanged; only the method signature and return type differ. Q03 Are Livewire-based Filament tests affected by the v4 upgrade? The test helper API (`livewire(ResourcePage::class)->fillForm()->assertFormSet()`) is stable across v3 and v4. Your existing Pest feature tests should pass without modification after migrating a resource's schema. Continue reading More Articles --------------- [ View all ](https://msaied.com/articles) [ ![Pest 5 Released: Test Impact Analysis, Agent Verification, and Evals](https://cdn.msaied.com/493/a1d6434093b945e8a3291eb09c09e768.png) Pest PHP Testing PHP 8.4 ### Pest 5 Released: Test Impact Analysis, Agent Verification, and Evals Pest v5 lands with the TIA engine that cut Laravel Cloud's 19,000-test suite from 3 minutes to 5 seconds, plus... ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said 31 Jul 2026 4 min read Read ](https://msaied.com/articles/pest-5-released-test-impact-analysis-agent-verification-and-evals) [ ![Job Batching, Chaining, and Rate-Limited Middleware in Laravel Queues](https://cdn.msaied.com/489/89d47dc6b618d5435f9d7f333b75e922.png) laravel queues jobs ### Job Batching, Chaining, and Rate-Limited Middleware in Laravel Queues Go beyond basic dispatch: learn how to compose Laravel job batches with callbacks, chain dependent jobs safely... ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said 30 Jul 2026 4 min read Read ](https://msaied.com/articles/job-batching-chaining-and-rate-limited-middleware-in-laravel-queues-3) [ ![Laravel Observers vs. Model Events: Choosing the Right Hook for Domain Side-Effects](https://cdn.msaied.com/488/451564d0a43aa33809619fa299027222.png) laravel eloquent domain-events ### Laravel Observers vs. Model Events: Choosing the Right Hook for Domain Side-Effects Model events and observers look similar but behave differently under bulk operations, transactions, and test i... ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said 30 Jul 2026 4 min read Read ](https://msaied.com/articles/laravel-observers-vs-model-events-choosing-the-right-hook-for-domain-side-effects) [ ![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)