This will guide you to upgrade from Backpack v6 to v7. The steps are color-coded by the probability that you will need it for your application: High, Medium and Low. At the very least, please read what's in bold.
Please make sure your project respects the requirements below, before you start the upgrade process. You can check with php artisan backpack:version:
If you're running Backpack version 3.x-5.x, please follow ALL other upgrade guides first, to incrementally get to use Backpack v6. Test that your app works well with each version, after each upgrade. Only afterwards can you follow this guide, to upgrade from v5 to v6. Previous upgrade guides:
Step 0. Upgrade to Laravel 12 if you don't use it yet, then test to confirm your app is working fine.
Step 1. We've created a command to help you run a lot of the steps in this upgrade guide, automatically. To run it:
# update your existing v6 installation, to get the upgrade command
composer update
# before calling the next command make sure you have no pending migrations with `php artisan migrate:status`
# and that your webserver is running and accessible in the URL you defined in .env `APP_URL`
php artisan backpack:upgrade
# follow the prompts in that command, then run
composer updateNow you should be running Backpack v7, with a lot of the steps below already finished. But don't stop here. Please read the upgrade steps below. Either double-check that the command has already done them or do them manually.
Step 2. Your composer.json should require the new version of Backpack CRUD:
"backpack/crud": "^7.0.0-beta",Step 3. Bump the version of any first-party Backpack add-ons you have installed (eg. backpack/pro, backpack/editable-columns etc.) to the versions that support Backpack v6. For 3rd-party add-ons, please check each add-on's Github page. Here's a quick list of 1st party packages and versions:
'backpack/crud' => '^7.0.0-beta',
'backpack/theme-coreuiv2' => 'dev-next',
'backpack/theme-coreuiv4' => '^1.2',
'backpack/theme-tabler' => 'dev-next',
'backpack/logmanager' => '^5.1',
'backpack/settings' => '^3.2',
'backpack/newscrud' => '^5.2',
'backpack/permissionmanager' => '^7.3',
'backpack/pagemanager' => '^3.4',
'backpack/menucrud' => '^4.1',
'backpack/backupmanager' => '^5.1',
'backpack/editable-columns' => '^3.1',
'backpack/revise-operation' => '^2.1',
'backpack/medialibrary-uploaders' => '^2.0',
'backpack/devtools' => '^4.0',
'backpack/generators' => '^4.1',
'backpack/activity-log' => '^2.1',
'backpack/calendar-operation' => '^1.1',
'backpack/language-switcher' => '^2.1',
'backpack/pan-panel' => '^1.1',
'backpack/pro' => '^3.0.0-alpha',
'backpack/translation-manager' => '^1.1',
'backpack/ckeditor-field' => '^1.0',
'backpack/tinymce-field' => '^1.0',Note: To install Backpack v7 beta and its add-ons, set
"minimum-stability": "beta"in yourcomposer.json.
No changes needed.
No changes needed.
No changes needed.
Step 4. Operation Config Files - We have added new configuration options in the files inside config/backpack/operations/. If you have those files published, it is recommended that you copy the new options in your files too.
Step 5. Show Operation New Default - inside config/backpack/operations/show.php you'll find a new option, to choose which component will be used on the show operation. By default it's the new component bp-datagrid, but you can switch to bp-datalist if you want to keep the same look as before:
// Which component to use for displaying the Show page?
'component' => 'bp-datalist', // options: bp-datagrid, bp-datalist, or a custom component aliasStep 6. Theme Tabler - The default layout for theme tabler has changed. If you had the tabler config published you are good to go. In case you don't have the tabler theme config published and want to keep the old layout, you should publish it by running php artisan vendor:publish --tag="theme-tabler-config" and changing:
- 'layout' => 'horizontal',
+ 'layout' => 'horizontal_overlap',You should also remove the glass skin and fuzzy background from the theme styles:
'styles' => [
base_path('vendor/backpack/theme-tabler/resources/assets/css/skins/backpack-color-palette.css'),
- base_path('vendor/backpack/theme-tabler/resources/assets/css/skins/glass.css'),
- base_path('vendor/backpack/theme-tabler/resources/assets/css/skins/fuzzy-background.css'),
],Step 7. The wysiwyg field and column have been removed, because they were hiding functionality. But don't worry, they were just alias columns. Behind the scenes, they were just loading the ckeditor field and text column respectively. If you're using the wysiwyg column of field in your CrudController, replace them with their originals.
Step 8. The ckeditor field and column have been moved from the PRO package to an open-source addon. If you are using either of them and want to keep doing so, just run composer require backpack/ckeditor-field. Please note that CKEditor is a 3rd party JS library that requires payment when used for commercial purposes (GPL licensed). See their pricing page for options. We can give away a few sub-licenses every year - contact us to see if any are still available. If you would rather move away from CKEditor, you can just change your field/column to use summernote instead, they are both HTML editors so your content should be compatible. Summernote has more limited editing options, but it's MIT-licensed.
Step 9. Similarly, the tinymce field and column have been moved from the PRO package to an open-source addon. If you are using either of them and want to keep doing so, just run composer require backpack/tinymce-field. Please note that TinyMCE is a 3rd party JS library that normally requires payment when used for commercial purposes (GLP licensed). See their pricing page for options. You can sign-up for free commercial licenses on their website here. If you would rather move away from TinyMCE, you can just change your field/column to use summernote instead, they are both HTML editors so your content should be compatible. Summernote has more limited editing options, but it's MIT-licensed.
All 3rd party dependencies have been updated to their latest versions. A lot of CSS & JS assets have suffered changes. Fortunately, thanks to Basset, we can easily clear the old files and get the new ones.
Step 10. Many views have suffered tiny changes, for various reasons. They should still work in your context, but you should consider updating them to get the latest features. Here's a quick way to see if you have overidden any core files from Backpack packages, and those files have had changes:
# run this in your terminal, to register these 2 custom functions
# the functions will only be available in the current terminal session
# (if you close the terminal, the functions need to be pasted again)
# anychange()
# - receives 2 directories as parameters
# - the result is a list of files that are present in both directories, but have differences
anychange() { src=${1%/}; dst=${2%/}; find "$src" -type f -print0 | while IFS= read -r -d '' f; do rel=${f#"$src/"}; g="$dst/$rel"; if [ -f "$g" ] && ! cmp -s "$f" "$g"; then echo "$rel"; fi; done; }
# anydiff()
# - receives 2 directories as parameters
# - the result is the actual diffs of files that are present in both directories, but have differences
anydiff() { src=${1%/}; dst=${2%/}; find "$src" -type f -print0 | while IFS= read -r -d '' f; do rel=${f#"$src/"}; g="$dst/$rel"; [ -f "$g" ] && echo ">>> Diff for $rel" && diff -u "$f" "$g" && echo; done; }Here are the commands we recommend you run, at a minimum:
anychange resources/views/vendor/backpack/crud vendor/backpack/crud/src/resources/views/crud
anychange resources/views/vendor/backpack/ui vendor/backpack/crud/src/resources/views/ui
anychange resources/views/vendor/backpack/crud vendor/backpack/pro/resources/viewsIf you do have differences, you can then do a diff between your files and ours, to see the difference. You can do that using a diff app like Kaleidoscope or using the diff command in your terminal. For example:
# compare the file from the project with the new file from the package
diff resources/views/vendor/backpack/crud/fields/datetime_picker.blade.php vendor/backpack/pro/resources/views/fields/datetime_picker.blade.phpStep 10.A. If the anychange command has told you there are differences in the list operation. Yes, the List Operation view has received significant changes. We decoupled the datatable from the view, so that you can use the table anywhere you would like. Most of the code is still identical but moved to datatable.blade.php. The list.blade.php view now only includes the mentioned datatable component. If you had customized the list.blade.php you should move your customizations to datatable.blade.php. If you've overidden it, you should do a diff and implement the changes. You can do that using a diff app like Kaleidoscope or using the diff command in your terminal. For example:
# compare the file from the project with the new file from the package
diff resources/views/vendor/backpack/crud/list.blade.php vendor/backpack/crud/src/resources/views/crud/list.blade.phpStep 10.B. If the anychange command has told you there are differences in the filters. Yes, Filters Views from Backpack/PRO have all suffered considerable changes, mostly to their JS. That's because we've liberated them - and filters can now we used in custom pages as well. If you have overridden the default filters, or created custom filters - they should still work. But to make them work on custom pages, you should do the same changes we did. If you've overidden it, you should do a diff and implement the changes. You can do that using a diff app like Kaleidoscope or using the diff command in your terminal. For example:
# compare the file from the project with the new file from the package
diff resources/views/vendor/backpack/crud/filters/simple.blade.php vendor/backpack/pro/resources/views/filters/simple.blade.phpStep 10.C. If the anychange command has told you there are differences in the select2 fields. Yes, Select2 Fields from Backpack/PRO have all suffered tiny changes, to make them work inside the DataForm Modal. If you have overridden select2_multiple, select2_nested, select2_json_from_api, select2_grouped, select2_from_array, select2_from_ajax, select2_from_ajax_multiple, select2 or relationship... or created any custom select2 fields - they should still work in your context. But to make them work inside the DataForm modal, you should do the same tiny changes we did. Do a diff between your files and ours, to see the difference. You can do that using a diff app like Kaleidoscope or using the diff command in your terminal. For example:
# compare the file from the project with the new file from the package
diff resources/views/vendor/backpack/crud/fields/select2_multiple.blade.php vendor/backpack/pro/resources/views/fields/select2_multiple.blade.phpNo changes needed.
Step 11. Clear your app's cache:
php artisan basset:clear
php artisan config:clear
php artisan cache:clear
php artisan view:clearIf the table view still looks wonky (search bar out of place, big + instead of ellipsis), then do a hard-reload in your browser (Cmd+Shift+R or Ctrl+Shift+F5) to purge the browser cache too.
Step 12. If your pages are slow to load, that's because Basset caching the assets as you load the pages, so your first pageload will be quite slow. If you find that annoying, run php artisan basset:cache to cache all CSS and JS assets. Alternatively, if you want Basset NOT to run because you're making changes to CSS and JS files, you can add BASSET_DEV_MODE=true to your .ENV file.
Using the File Manager package? Most of the views that weren't in use were removed, and the dependencies were bumped. If you didn't do any customization you should delete the resources/views/vendor/elfinder (rm -rf resources/views/vendor/elfinder) folder. No need to publish any views anymore if you are not customizing them. If you were, publish the new view files (php artisan vendor:publish --provider="Backpack\FileManager\FileManagerServiceProvider" --tag="elfinder-views"). Then apply your customization on the new files, now located at: resources/views/vendor/backpack/filemanager/
Additional the browse and browse_multiple fields/columns are now part of this package. If you previously made any modifications to this fields/columns you should publish the new views (php artisan vendor:publish --provider="Backpack\FileManager\FileManagerServiceProvider" --tag="filemanger-fields" and php artisan vendor:publish --provider="Backpack\FileManager\FileManagerServiceProvider" --tag="filemanager-columns"), and carry over the modifications from the old files to this new files.
By upgrading Backpack from v6 to v7, you've automatically upgraded from Basset v1 to v2. This new version changes some default behaviour, so please read more about it here. Most projects will not be affected.
You're done! Good job. Thank you for taking the time to upgrade. Now you can:
Then you'll love our premium add-ons - productivity tools and tons of new features.