Filament v3 to v4 Migration: Breaking Changes | Mohamed Said [ ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MH.png) Mohamed Said Laravel Backend Engineer ](https://www.msaied.com) [ Home ](https://www.msaied.com) [ Projects ](https://www.msaied.com/projects) [ Articles ](https://www.msaied.com/articles) [ Certificates ](https://www.msaied.com/certificates) [ Contact ](https://www.msaied.com#contact-section) [ ](https://github.com/EG-Mohamed) [ Home ](https://www.msaied.com) [ Projects ](https://www.msaied.com/projects) [ Articles ](https://www.msaied.com/articles) [ Certificates ](https://www.msaied.com/certificates) [ Contact ](https://www.msaied.com#contact-section) [ home ](https://www.msaied.com) [ articles ](https://www.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%2Fwww.msaied.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%2Fwww.msaied.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://www.msaied.com/articles) [ ![Laravel Telescope Alternatives: Building a Lightweight Request Inspector with Middleware](https://cdn.msaied.com/216/9b6d240010b80483f072902dafcd216c.png) laravel middleware debugging ### Laravel Telescope Alternatives: Building a Lightweight Request Inspector with Middleware Telescope is powerful but heavy for production. Learn how to build a focused, low-overhead request inspector u... ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said 16 Jun 2026 1 min read Read ](https://www.msaied.com/articles/laravel-telescope-alternatives-building-a-lightweight-request-inspector-with-middleware) [ ![RAG Pipelines in Laravel: Chunking, Embedding, and Retrieval with pgvector](https://cdn.msaied.com/215/e037e13535aa77822f879ee829ec3f68.png) laravel ai pgvector ### RAG Pipelines in Laravel: Chunking, Embedding, and Retrieval with pgvector Build a production-ready Retrieval-Augmented Generation pipeline in Laravel using pgvector, OpenAI embeddings,... ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said 16 Jun 2026 3 min read Read ](https://www.msaied.com/articles/rag-pipelines-in-laravel-chunking-embedding-and-retrieval-with-pgvector) [ ![Laravel Pest: Architecture Tests, Mutation Testing, and Type Coverage in CI](https://cdn.msaied.com/214/0d4822fa8ee1765d0689e387dd849d92.png) laravel pest testing ### Laravel Pest: Architecture Tests, Mutation Testing, and Type Coverage in CI Go beyond feature tests. Learn how to enforce architectural rules, catch logic gaps with mutation testing, and... ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said 16 Jun 2026 4 min read Read ](https://www.msaied.com/articles/laravel-pest-architecture-tests-mutation-testing-and-type-coverage-in-ci) [ ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MH.png) Mohamed Said Laravel Backend Engineer ](https://www.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://www.msaied.com) - [Projects](https://www.msaied.com/projects) - [Articles](https://www.msaied.com/articles) - [Certificates](https://www.msaied.com/certificates) - [Contact](https://www.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)