This will guide you to upgrade from Backpack 4.0 to 4.1. The steps are color-coded by the probability that you will need it for your application: High, Medium and Low.
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, please follow ALL the minor upgrade guides first, to incrementally get to use Backpack 4.0. Test that your app works well with each version, after each upgrade. Only afterwards can you follow this guide, to upgrade from 4.0 to 4.1. Previous upgrade guides:
Step 0. Upgrade to Laravel 6. Then upgrade to Laravel 7, if you can. This is not required, but it's recommended. You need to do this one day anyway - might as well do it now. Backpack 4.0 (that your project is already running) supports Laravel 5.8, 6 and 7. So you should:
Our recommendation is to not stick to Laravel 6.0 just because it's a LTS version, but to upgrade to the latest Laravel. All upgrades after Laravel 5.6 have been very very easy, and it's expected for this to continue, since Laravel has reached stability for some years now. If you're scared or lazy, for just $9 you can purchase a Laravel Shift, to automatically upgrade, and make sure you haven't missed a step.
Step 1. Update your
composer.json file to require
Step 2. If you have a lot of Backpack add-ons installed (and their dependencies), here are their latest versions, that support Backpack 4.1, you can copy-paste the versions of the packages you're using:
"backpack/logmanager": "^4.0.0", "backpack/settings": "^3.0.0", "backpack/pagemanager": "^3.0.0", "backpack/menucrud": "^2.0.0", "backpack/newscrud": "^4.0.0", "backpack/permissionmanager": "^6.0.0", "backpack/backupmanager": "^2.0.0", "spatie/laravel-translatable": "^4.0", "backpack/langfilemanager": "^3.0.0", /* and in require-dev */ "backpack/generators": "^3.0", "laracasts/generators": "^1.0"
Step 3. If you're using the Revisions operation, it has now been split into a separate package. So please add
"backpack/revise-operation": "^1.0", to your composer's require section.
Step 4. Backpack itself is no longer using
laravel/helpers. Instead of using helpers like
str_slug() we're now doing
Str::slug() everywhere. We recommend you do the same. But if you want to keep using string and array helpers, please add
"laravel/helpers": "^1.1", to your composer's require section.
Step 5. Since we're no longer using
laravel/helpers, we need the
Arr classes to be aliased. You should have already done this when upgrading to Laravel 5.8/6.x/7.x. But please make sure that in your
config/app.php you have these aliases:
'aliases' => [ // ... 'Arr' => Illuminate\Support\Arr::class, // .. 'Str' => Illuminate\Support\Str::class, // .. ],
Step 6. Backpack no longer installs the FileManager by default (elFinder), since most projects don't need it. If you did use the FileManager, or the
browse_multiple fields, make sure you require
"backpack/filemanager": "^1.0", in your
composer.json - we've separated it into an add-on.
Step 7. Backpack no longer installs
intervention/image by default. If you use the
image field type and you've used our example Mutator in your Model, you might be using
intervention/image - please check. If so, please add
"intervention/image": "^2.3", to your
composer.json's require section.
Step 8. Run
composer update in the command line.
No changes needed.
No changes needed.
Step 9. Backpack no longer provides, needs or uses the
App\Models\BackpackUser model for authentication. New installs default to using
App\User. Since that model was only used for authentication & forgotten-password functionality, we recommend you:
- 'user_model_fqn' => App\Models\BackpackUser::class, + 'user_model_fqn' => App\User::class,
'models' => [ - 'user' => App\Models\BackpackUser::class, + 'user' => App\User::class, 'permission' => Backpack\PermissionManager\app\Models\Permission::class, 'role' => Backpack\PermissionManager\app\Models\Role::class, ],
Of course, if you actually liked having a separate model for your admins, you can keep it. But we recommend removing it - since it's unnecessary. If you decide to keep the
BackpackUser model, take note that we also removed the
InheritsRelationsFromParentModel trait, that only
BackpackUser was using. To pull that trait in, install calebporzio/parental and use
\Parental\HasParent instead of
IMPORTANT: If you use polymorphic relationships, you might have mentions of the
App\Models\BackpackUsermodel in your BD. You will need to replace all those mentions in the DB with the standard
If you've used
spatie/laravel-permission, please note that you DO use polymorphic relationships. All permissions and roles that pointed to
App\Models\BackpackUser in the database need to be pointed to
App\User model now:
# ------------------- # ONLY if you've used PermissionManager and/or spatie/laravel=permission # ------------------- # Step 9.1. # Create a database backup. Please. Pretty please. # Step 9.2. # Publish the migration for the standard configuration. # This should work as-is if you haven't changed table names. php artisan vendor:publish --provider="Backpack\PermissionManager\PermissionManagerServiceProvider" --tag="migrations" # Step 9.3. # Take a look at the migration and change whatever you need: # - are the table names the same in the DB & in the migration? # - are the column names the same? # - are there entries in the DB with App\Models\BackpackUser? # - did you notice there's no down() method for the migration? maybe you'll create a DB backup now, if you haven't? # Step 9.4. # Run the migration. php artisan migrate # Step 9.5. # Take another look at your model_has_roles and model_has_permissions tables. # Are there any more entries that point to App\Models\BackpackUser?
The steps below should apply for each of your CrudControllers. For each Step, go through every one of your CrudControllers (usually stored in
Step 10. If you're using the
RevisionsOperation inside your CrudControllers, that operation has been moved to a separate package (that you've already installed in steps 3 & 8). Now you need to:
Backpack\CRUD\app\Http\Controllers\Operations\RevisionsOperationand replace with
set(), but please note that the operation is now called "revise" (verb) not "revisions" (noun), so your changes should be:
config/backpack/crud.php, please note that the operation name has changed, so inside
operationsyou should change
Step 11. Inside CrudControllers, Backpack 4.1:
CRUD::request) but uses getters and setters to work with it (
$this->request did nothing at all, we've removed it, to avoid any confusion between working with
$this->crud->request. Make sure that:
$this->requestanywhere in your CrudControllers custom logic, please replace it with either Laravel's
request()helper or with
$this->crud->requestanywhere inside your custom CrudController logic, please replace it with either
$this->crud->setRequest()depending on what your intention is.
Step 12. Inside CrudControllers, if you've used
wrapperAttributes on fields, please note that it's now called
wrapper. Please search & replace
wrapper in your CrudControllers.
Additionally, for the
select2_from_ajax_multiple field types, the inputs on the main form are no longer sent through the AJAX request by default. If you're using dependant selects, please make sure that you add
'include_all_form_fields' => true to your
select2_from_ajax_multiple field definition to keep the same behaviour as before.
Step 13. We've updated most CSS & JS dependencies to their latest versions. There are two ways to publish the latest styles and scripts for these dependencies:
public/packagesfolder, or placed anything custom inside it:
public/packagesdirectory and all its contents;
php artisan vendor:publish --provider="Backpack\CRUD\BackpackServiceProvider" --tag=public
php artisan backpack:filemanager:install
php artisan vendor:publish --provider="Backpack\CRUD\BackpackServiceProvider" --tag=public --force. Please note this will overwrite anything that's already there. This B solution has a downside: unused files are not removed. A few files Backpack no longer uses will still be in your
public/packagesfolder, even though they're no longer used.
Step 14. If you've overwritten default Fields, or have custom Fields, take note that ALL of them have suffered changes (for the better); as a minimum, if you have any files in
resources/views/vendor/backpack/crud/fields you should:
- <div @include('crud::inc.field_wrapper_attributes') > + @include('crud::fields.inc.wrapper_start') // Your actual field HTML - </div> + @include('crud::fields.inc.wrapper_end')
Step 15. If you've overwritten Columns, or have custom Columns, take note that ALL columns have suffered changes (for the better). Most notably:
wrapperallows you to add links to your columns;
escapedallows you to output HTML instead of text;
If you want your custom/overwritten columns to have these cool new features, they're very easy to implement:
newspaper-oit's now just
fa fa-home), we're now using the "line awesome syntax" (
la la-home), to prevent conflicts when both fonts are used at the same time;
In order to account for this icon font change please:
resources/views/vendor/backpackfolder, search & replace
Step 17. In order to be able to use the new fluent syntax for Widgets, you should make sure all main admin panel views (ex: dashboard, create, update, etc) extend the
//from - @extends('backpack::layouts.top_left') - @extends(backpack_view('layouts.top_left')) // to + @extends(backpack_view('blank')) // or + @extends('backpack::blank')
Step 18. Clear your app's cache:
php artisan config:clear php artisan cache:clear php artisan view:clear
You're done! Good job. Thank you for taking the time to upgrade. Now you can: