If you see anything missing from this guide, please don’t hesitate to make a pull request to our repository! Any help is appreciated!
doctrine/dbal, but if your application still does, and you don’t have it installed directly, you should add it to your composer.json file.The upgrade script is not a replacement for the upgrade guide. It handles many small changes that aren’t mentioned in the upgrade guide, but it doesn’t handle all breaking changes. You should still read the manual upgrade steps to see what changes you need to make to your code.
Some plugins you're using may not be available in v4 just yet. You could temporarily remove them from your composer.json file until they've been upgraded, replace them with similar plugins that are v4-compatible, wait for the plugins to be upgraded before upgrading your app, or even write PRs to help the authors upgrade them.
The first step to upgrade your Filament app is to run the automated upgrade script. This script will automatically upgrade your application to the latest version of Filament and make changes to your code, which handles most breaking changes:
composer require filament/upgrade:"^4.0" -W --dev
vendor/bin/filament-v4
# Run the commands output by the upgrade script, they are unique to your app
composer require filament/filament:"^4.0" -W --no-update
composer updateWhen using Windows PowerShell to install Filament, you may need to run the command below, since it ignores ^ characters in version constraints:
composer require filament/upgrade:"~4.0" -W --dev
vendor/bin/filament-v4
# Run the commands output by the upgrade script, they are unique to your app
composer require filament/filament:"~4.0" -W --no-update
composer updateIf installing the upgrade script fails, make sure that your PHPStan version is at least v2, or your Larastan version is at least v3. The script uses Rector v2, which requires PHPStan v2 or higher.
Make sure to carefully follow the instructions, and review the changes made by the script. You may need to make some manual changes to your code afterwards, but the script should handle most of the repetitive work for you.
Filament v4 introduces a new default directory structure for your Filament resources and clusters. If you’re using Filament panels with resources and clusters, you can choose to keep the old directory structure, or migrate to the new one. If you want to migrate to the new directory structure, you can run the following command:
php artisan filament:upgrade-directory-structure-to-v4 --dry-runThe --dry-run option will show you what the command would do without actually making any changes. If you’re happy with the changes, you can run the command without the --dry-run option to apply the changes:
php artisan filament:upgrade-directory-structure-to-v4This directory upgrade script is not able to perfectly update any references to classes in the same namespace that were present in resource and cluster files, and those references will need to be updated manually after the script has run. You should use tools like PHPStan to identify references to classes that are broken after the upgrade.
You can now composer remove filament/upgrade --dev as you don't need it anymore.
Some changes in Filament v4 can be reverted using the configuration file. If you haven't published the configuration file yet, you can do so by running the following command:
php artisan vendor:publish --tag=filament-configFirstly, the default_filesystem_disk in v4 is set to the FILESYSTEM_DISK variable instead of FILAMENT_FILESYSTEM_DISK. To preserve the v3 behavior, make sure you use this setting:
return [
// ...
'default_filesystem_disk' => env('FILAMENT_FILESYSTEM_DISK', 'public'),
// ...
]v4 introduces some changes to how Filament generates files. A new file_generation section has been added to the v4 configuration file, so that you can revert back to the v3 style if you would like to keep new code consistent with how it looked before upgrading. If your configuration file doesn't already have a file_generation section, you should add it yourself, or re-publish the configuration file and tweak it to your liking:
use Filament\Support\Commands\FileGenerators\FileGenerationFlag;
return [
// ...
'file_generation' => [
'flags' => [
FileGenerationFlag::EMBEDDED_PANEL_RESOURCE_SCHEMAS, // Define new forms and infolists inside the resource class instead of a separate schema class.
FileGenerationFlag::EMBEDDED_PANEL_RESOURCE_TABLES, // Define new tables inside the resource class instead of a separate table class.
FileGenerationFlag::PANEL_CLUSTER_CLASSES_OUTSIDE_DIRECTORIES, // Create new cluster classes outside of their directories. Not required if you run `php artisan filament:upgrade-directory-structure-to-v4`.
FileGenerationFlag::PANEL_RESOURCE_CLASSES_OUTSIDE_DIRECTORIES, // Create new resource classes outside of their directories. Not required if you run `php artisan filament:upgrade-directory-structure-to-v4`.
FileGenerationFlag::PARTIAL_IMPORTS, // Partially import components such as form fields and table columns instead of importing each component explicitly.
],
],
// ...
]The filament/upgrade package includes a command to help you move panel resources and clusters to the new directory structure, which is the default in v4:
php artisan filament:upgrade-directory-structure-to-v4 --dry-runThe --dry-run option will show you what the command would do without actually making any changes. If you are happy with the changes, you can run the command without the --dry-run option to apply the changes:
php artisan filament:upgrade-directory-structure-to-v4This directory upgrade script is not able to perfectly update any references to classes in the same namespace that were present in resource and cluster files, and those references will need to be updated manually after the script has run. You should use tools like PHPStan to identify references to classes that are broken after the upgrade.
Once you have run the command, you do not need to keep the FileGenerationFlag::PANEL_CLUSTER_CLASSES_OUTSIDE_DIRECTORIES or FileGenerationFlag::PANEL_RESOURCE_CLASSES_OUTSIDE_DIRECTORIES flags in your configuration file, as the new directory structure is now the default. You can remove them from the file_generation.flags array.
To begin, filter the upgrade guide for your specific needs by selecting only the packages that you use in your project: