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 "backpack/crud": "4.1.*"
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 Str and 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 or 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:
App\Models\BackpackUser.php file;config/backpack/base.php file to:- 'user_model_fqn' => App\Models\BackpackUser::class,
+ 'user_model_fqn' => App\User::class,config/backpack/permissionmanager.php file to: 'models' => [
- 'user' => App\Models\BackpackUser::class,
+ 'user' => App\User::class,
'permission' => Backpack\PermissionManager\app\Models\Permission::class,
'role' => Backpack\PermissionManager\app\Models\Role::class,
],App\User will need some changes for backpack to use it properly. It must use CrudTrait and HasRoles traits:<?php namespace App;
+ use Backpack\CRUD\app\Models\Traits\CrudTrait;
+ use Spatie\Permission\Traits\HasRoles;
use Illuminate\Foundation\Auth\User as Authenticatable;
class User extends Authenticatable
{
+ use CrudTrait;
+ use HasRoles;
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 InheritsRelationsFromParentModel.
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 standardApp\Usermodel.
If you've used PermissionManager or 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?Another example of polymorphic relationships is the revisions table, if you've used it you may have references to App\Models\BackpackUser there too, please replace it with App\User.
The steps below should apply for each of your CrudControllers. For each Step, go through every one of your CrudControllers (usually stored in app\Http\Controllers\Admin:
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\RevisionsOperation and replace with Backpack\ReviseOperation\ReviseOperationget()/set(), but please note that the operation is now called "revise" (verb) not "revisions" (noun), so your changes should be:
$this->crud->setRevisionsView() to $this->crud->set('revise.view')$this->crud->getRevisionsView() to $this->crud->get('revise.view')$this->crud->setRevisionsTimelineView() to $this->crud->set('revise.timelineView')$this->crud->getRevisionsTimelineView() to $this->crud->set('revise.timelineView')$this->crud->setRevisionsTimelineContentClass() to $this->crud->set('revise.timelineContentClass')$this->crud->getRevisionsTimelineContentClass() to $this->crud->set('revise.timelineContentClass')config/backpack/crud.php, please note that the operation name has changed, so inside operations you should change revisions to revise;Step 11. Inside CrudControllers, Backpack 4.1:
$this->request$this->crud->request (aka CRUD::request) but uses getters and setters to work with it ($this->crud->getRequest() and $this->crud->setRequest());Why? Since $this->request did nothing at all, we've removed it, to avoid any confusion between working with $this->request and $this->crud->request. Make sure that:
$this->request anywhere in your CrudControllers custom logic, please replace it with either Laravel's request() helper or with $this->crud->getRequest().$this->crud->request anywhere inside your custom CrudController logic, please replace it with either $this->crud->getRequest() or $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 wrapperAttributes with wrapper in your CrudControllers.
Additionally, for the select2_from_ajax and 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 and 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/packages folder, or placed anything custom inside it:
public/packages directory and all its contents;php artisan vendor:publish --provider="Backpack\CRUD\BackpackServiceProvider" --tag=publicresources/views/vendor/elfinder and run php artisan backpack:filemanager:installphp 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/packages folder, 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:
crud::inc.field_attributes with crud::fields.inc.attributescrud::inc.field_translatable_icon with crud::fields.inc.translatable_icon- <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:
wrapper allows you to add links to your columns;escaped allows 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:
text);select);If you need a difftool, we recommend Kaleidoscope on Mac OS, WinMerge on Windows, or Fork on both Mac OS and Windows.
Step 16. Backpack 4.1 uses the same icon set, Line Awesome, but we've upgraded to the latest version.
newspaper-o it's now just newspaper;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/backpack folder, search & replace fa fa- with la la-;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 blank template:
//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:clearYou'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.