Upgrade Laravel Package

Getting Started

filament/upgrade is a one-shot codemod for moving an application from Filament v4 to v5. Treat it as a migration accelerator, not an installer — it belongs in a short-lived branch, not in your steady-state require block.

Prerequisites and safety net

• Filament v4 already installed and working; PHP 8.1+, Laravel 9+ (v5 baseline).
• A clean git working tree, a dedicated branch (v5-upgrade), and a database/storage backup if you plan to boot the app mid-migration.
• Third-party Filament plugins audited first — the codemod will not migrate them.

Install and discover the actual CLI surface

composer require filament/upgrade --dev
php artisan list | grep filament
php artisan filament:upgrade --help

Command and flag names have moved between releases (sources reference filament:upgrade, filament:upgrade:analyze, filament:upgrade:fix, and --dry-run). Always confirm against --help for the version you installed rather than copying a blog snippet.

First use case

Pick the smallest, least-critical panel and run analysis only:

php artisan filament:upgrade:analyze   # or: filament:upgrade --dry-run

Where to look first, in order:

1. The generated report (often storage/logs/filament-upgrade-report.log).
2. composer.json / composer.lock — confirm you are targeting filament/filament:^5.0.
3. app/Providers/Filament/*.php and panel providers — namespace and registration changes.
4. app/Filament/**/Resources, Pages, Widgets — the bulk of the churn.
5. config/filament.php and any published Blade views under resources/views/filament/.

Do not run the fixer until you have read the report and confirmed the diff is explainable.

Implementation Patterns

The core loop: analyze → dry-run → apply → review → test → commit

git checkout -b v5-upgrade
php artisan filament:upgrade --dry-run        # inspect
git diff --stat                                # gauge blast radius
php artisan filament:upgrade                   # apply
git diff                                       # the real review surface
php artisan optimize:clear && composer dump-autoload
php artisan test

Commit per module so a bad codemod pass is one git revert away. The package has no rollback of its own; git is the rollback.

Scope by module, not by whole app

Migrate one panel or one resource directory at a time — admin reports first, then core CRUD (PostsResource, UsersResource), then custom widgets and plugins. If the command supports path/namespace arguments, use them; otherwise scope with branches and revert unrelated changes before committing.

Separate dependency bump from code rewrite

The codemod rewrites code; Composer changes the installed version. Keep them as two commits:

# 1. code rewrite on a branch
php artisan filament:upgrade

# 2. dependency alignment
composer require filament/filament:^5.0 -W
composer update --with-all-dependencies
php artisan optimize:clear

This makes it obvious whether a failure came from the rewrite or the dependency graph.

Plugin and dependency audit as a pattern

composer why-not filament/filament ^5.0

Anything blocking v5 is either patched, replaced, or removed before you run the codemod. Record the decision in the PR description.

Static analysis is the second pass

The codemod handles mechanical renames; PHPStan/Larastan and Pint catch the half-migrated files it leaves behind (dead imports, signature mismatches, unused traits). Run them immediately after each codemod commit, not at the end.

CI guardrail

Run the upgrade in a throwaway container job and fail if the resulting diff contains files you did not expect. A short whitelist of touched paths keeps the codemod honest as you widen its scope.

Testing workflow

• Pest/Livewire tests for resource CRUD and table filters.
• Pest Browser smoke test for at least one panel: login, list, create, edit.
• php artisan filament:upgrade:test is referenced in some sources; verify it exists before wiring it into CI.
• Test the diff in staging with a real database copy — namespace migrations pass unit tests while Blade/asset regressions only appear at render time.

Extension points

If your installed version exposes custom rules or an exclude list, use them for directories you intend to migrate by hand. Where it does not, the practical extension point is a targeted grep/Rector pass for the leftovers the tool skips.

Gotchas and Tips

• No built-in rollback. The upgrade is one-way and file-mutating. Branch, commit, and back up before every run.
• Command drift is real. filament:upgrade, filament:upgrade:analyze, filament:upgrade:fix, and --dry-run appear across sources; confirm with --help on your installed version.
• Namespace moves are the easy 20%. Method renames, trait changes, and schema API shifts are where behavior breaks. Grep the report for method-level items and review each one.
• Dynamic references are invisible to the codemod. Class names built from strings ("App\\Filament\\{$type}"), config-driven component lists, and class_exists() checks will silently keep pointing at v4 names.
• Blade and published assets are frequently missed. Check resources/views/filament/, vendor-published views, and @filament* directives by hand. Then re-publish assets if v5 expects it.
• Config keys get renamed, not just reformatted. Do not blindly accept a regenerated config/filament.php — diff it against your customized version and port overrides (spa_mode → livewire_mode-style changes and similar) manually.
• Third-party plugins are outside the tool's scope. Anything not upgraded upstream must be patched or dropped; do this before running the codemod so you are not debugging two problems at once.
• Caches mask failures. After each pass: php artisan optimize:clear, composer dump-autoload, and restart queue workers. Stale compiled views and config caches produce phantom errors.
• False positives happen on heavily customized files. If a file needs more than a couple of manual corrections after the codemod, revert it and migrate that file by hand.
• Pin the pairing. Install the filament/upgrade release that targets the v5 version you are moving to, and check its changelog before upgrading the tool itself mid-migration.
• Remove it when done. composer remove filament/upgrade --dev and commit the lockfile; leaving a migration tool in a production dependency graph is an unnecessary supply-chain surface.
• Announce the UI delta. v5 changes visible layout and dashboard behavior; the codemod keeps functionality but not pixel parity, so pair the technical migration with release notes for end users.