- How do I prepare my Laravel app for a Filament v4 to v5 upgrade?
- Start by forking your repo and creating a dedicated `v5-upgrade` branch. Install the package via `composer require filament/upgrade --dev`, then run `php artisan filament:upgrade --dry-run` to preview changes. Backup your database and storage before proceeding.
- Does filament/upgrade handle custom Filament plugins or widgets?
- The package automates core Filament v4-to-v5 refactoring, but custom plugins or widgets may require manual adjustments. Review the dry-run output for unsupported components and update them post-upgrade. Complex logic often needs direct code review.
- What Laravel and PHP versions are required for filament/upgrade?
- filament/upgrade requires **Laravel 9+** and **PHP 8.1+** to align with Filament v5’s baseline. Ensure your environment meets these requirements before running the upgrade command, as older versions will block execution.
- Can I roll back if the upgrade fails?
- There’s no built-in rollback feature. To mitigate risk, commit the pre-upgrade state to a branch or use feature flags to isolate Filament v5 functionality. Always test in staging first and maintain a backup of your v4 branch.
- Will filament/upgrade update my Tailwind CSS configuration?
- Filament v5 defaults to **Tailwind CSS v3+**, so you may need to update your `tailwind.config.js` and purge old assets. The package doesn’t automate this, but the dry-run output will flag related changes in your Blade files or CSS.
- Are there alternatives to filament/upgrade for Filament migrations?
- For smaller projects, manual refactoring or a custom script might suffice, but filament/upgrade is the **official** tool for v4→v5 upgrades. Alternatives like `laravel-shift` or `roave/security-advisories` don’t specialize in Filament-specific changes.
- How do I handle third-party packages that depend on Filament v4?
- Audit your `composer.json` for packages like `spatie/laravel-filament-spa` or `filament-notification-channels`. Some may not yet support v5—check their release notes or GitHub issues. Replace or patch them before upgrading.
- Does filament/upgrade modify my database schema?
- No, the package doesn’t alter schemas directly, but related models (e.g., `filament_users`) or custom tables tied to Filament may need updates. Run migrations post-upgrade and test all database interactions thoroughly.
- How can I test the upgrade in a staging environment?
- Deploy your upgrade branch to staging, then run `php artisan filament:upgrade` there. Use a staging database mirroring production and validate all Filament features (Resources, Pages, Widgets). Monitor logs for errors during the dry-run phase.
- What should I do if the upgrade fails during execution?
- Check the error logs for specific failures (e.g., missing classes or config keys). Revert the upgrade by restoring your v4 branch, then address issues incrementally. For complex failures, open an issue on the [Filament Upgrade GitHub repo](https://github.com/filamentphp/upgrade) with your `composer.json` and error details.