Upgrading from EasyAdmin 2 to EasyAdmin 3

Automatic Upgrade from EasyAdmin 2 to EasyAdmin 3

To simplify migrations, EasyAdmin includes a command to migrate the EasyAdmin 2 YAML configuration into the PHP files needed in EasyAdmin 3. In some complex projects this command won't be able to do all the needed work, but it will help you making most of the work.

Step 1. In your existing Symfony application, run this command:

1
2

$ cd your-project/
$ php bin/console make:admin:migration

This command will back up the EasyAdmin 2 YAML configuration in a file so you can later access to it from EasyAdmin 3.

Step 2. Update your composer.json dependencies to upgrade to EasyAdmin 3:

1
2

-"easycorp/easyadmin-bundle": "^2.0",
+"easycorp/easyadmin-bundle": "^3.0",

Now, run this command to actually update the dependencies:

1

$ composer update

Step 3. Depending on your project configuration, you may need to fix some minor routing and configuration issues after the upgrade. Symfony's error messages will guide you.

Step 4. Run this command again from your EasyAdmin 3 application:

1

$ php bin/console make:admin:migration

Select the configuration that contains EasyAdmin 2 YAML configuration and the command will generate all the needed PHP files to replicate that configuration. In most applications this command generates all the needed code, but in complex application you may need to tweak, fix or add some additional changes.

Changes Breaking Backward Compatibility

The make:admin:migration command tries its best to generate the PHP files that are equivalent to the previous YAML configuration. However, there are some other changes that you may need to make in your application manually:

• The event names have changed in favor of object-based events, as recommended starting from Symfony 4.3. For example, EasyAdminEvents::PRE_PERSIST is now BeforeCreatingEntity::class. Read the events article for details.
• Most default template paths have changed: @EasyAdmin/default/*.html.twig templates have been split into three different directories: @EasyAdmin/page/*.html.twig, @EasyAdmin/label/*.html.twig and @EasyAdmin/field/*.html.twig.
• Some HTML elements and their CSS classes and IDs have changed. This only affects you if you have created some custom CSS/JS code for your backend.

• ---

Removed Features

EasyAdmin 3 removes some features of the previous versions which are no longer considered useful:

• The design.brand_color config option has been removed because you can't customize the backend design by changing just this value. If you still want to do that, use the following code in your dashboard class:

  1
  2
  3
  4
  5
  6
  7
  8
  9
  10
  11

  class DashboardController extends AbstractDashboardController
  {
      // ...
  
      public function configureAssets(): Assets
      {
          return Assets::new()
              // ...
              ->addHtmlContentToHead('<style>:root { --color-primary: #123456; }</style>');
      }
  }

• The default: true option to set the default backend page has been removed. Use the dashboard index as the default page or redirect to the desired page inside the dashboard controller action.
• The global options easy_admin.list.title, easy_admin.show.title, etc. have been removed in favor of the setPageTitle() method in the Crud class.
• The global help option for entities has been removed in favor of the setHelp() method in the Crud class.
• The global easy_admin.list.max_results option has been removed in favor of the setPaginatorPageSize() method in the Crud class.
• The dql_filter option to quickly filter the entity listings has been removed. Instead, use the createIndexQueryBuilder() method in the CRUD controller.
• The PRE_INITIALIZE and POST_INITIALIZE events have been removed. If you want to modify the configuration in the AdminContext variable, use a Symfony listener/subscriber and run it after EasyAdmin one. You can also decorate the AdminContextProvider service.
• The PRE_DELETE, POST_DELETE, PRE_EDIT, POST_EDIT, PRE_LIST, POST_LIST, PRE_NEW, POST_NEW, PRE_SEARCH, POST_SEARCH, PRE_SHOW, POST_SHOW events have been removed. Use instead the BeforeCrudActionEvent and AfterCrudActionEvent events.

• ---