Javier Eguiluz

Posted on Feb 26

EasyAdmin 5.0: A New Foundation for Your Admin Backends

#easyadmin #symfony #php

EasyAdmin 5.0.0 has just been released as the new stable version of EasyAdmin.

EasyAdmin follows a development philosophy similar to Symfony. That means EasyAdmin 5.x includes exactly the same features as 4.x. The difference is that 5.x removes everything that was deprecated during the 4.x cycle, providing a cleaner and more future-proof foundation.

EasyAdmin 5.0 raises the minimum Symfony and PHP requirements while still offering broad compatibility. It supports Symfony 6.4, all 7.x and 8.x versions, works with Doctrine ORM 2.x and higher, and requires PHP 8.2 or later.

What Changed in 5.0

All features introduced throughout the 4.x cycle are now the only supported approach in 5.0. Here is a summary of the most relevant changes.

Pretty URLs

In 4.x, you could still use the legacy URL format that this bundle used since day one (e.g. https://example.com/admin?crudAction=edit&crudControllerFqcn=App%5CController%5CAdmin%5cPostCrudController&entityId=3874).
In 5.0, only the pretty URLs are supported (e.g. https://example.com/admin/post/3874/edit), which we introduced in version 4.14.

You do not need to configure anything to use them. They are enabled by default thanks to this Symfony Flex recipe which loads a custom Symfony route loader.

Pretty URLs have been tested in production for over a year. During that time, we fixed edge cases related to menus, custom actions, and more. They are stable and ready for all applications.

Dashboard Definition via Attribute

Instead of relying on Symfony's #[Route] attribute, you now must apply the #[AdminDashboard] attribute to your dashboard class, added in version 4.24:

// BEFORE (4.x)
use Symfony\Component\Routing\Attribute\Route;

class DashboardController extends AbstractDashboardController
{
    #[Route('/admin', name: 'admin')]
    public function index(): Response
    {
        // ...
    }
}

// AFTER (5.x)
use EasyCorp\Bundle\EasyAdminBundle\Attribute\AdminDashboard;

#[AdminDashboard(routePath: '/admin', routeName: 'admin')]
class DashboardController extends AbstractDashboardController
{
    public function index(): Response
    {
        // ...
    }
}

The new attribute supports all route options provided by Symfony and adds its own features. For example, you can customize the format of admin routes and restrict which CRUD controllers are available on each dashboard.

Embedding Symfony Controllers in Your Backend

With the new #[AdminRoute] attribute added in version 4.25 you can integrate any Symfony controller action into your admin backends. This attribute automatically generates the routes required to render your action inside one or more dashboards, reusing the same layout, menus, and visual design as built-in EasyAdmin actions.

Action Improvements

During the 4.x cycle, we shipped several improvements to actions: grouping them in dropdowns and split buttons (version 4.26), showing a custom confirmation message before any action (version 4.28), and configuring a default action triggered when clicking any row on CRUD index pages.

Autocomplete Customization

In version 4.28, we added full control over how autocomplete entries are rendered:

// use callbacks for simple customizations
yield AssociationField::new('category', 'post.category')
    ->setSortProperty('name')
    ->autocomplete(callback: static fn (Category $c): string => sprintf('%s %s', $c->getIcon(), $c->getName()));

// use Twig template fragments for complex customizations with HTML elements
yield AssociationField::new('author', 'post.author')
    ->setSortProperty('fullName')
    ->autocomplete(template: 'admin/post/_author_autocomplete.html.twig', renderAsHtml: true);

Custom Icon Sets

EasyAdmin still uses FontAwesome icons by default, but since version 4.16 you can use any icon set, such as Tabler or Material Icons.

New Twig Components

During the 4.x cycle, we introduced Twig Components for common UI elements. In EasyAdmin 5.x, the long-term goal is to build the entire UI on top of reusable Twig Components, making it easier to compose fully custom admin pages.

Upgrading to 5.x

We strongly recommend upgrading as soon as possible. EasyAdmin 4.x will not receive new features, and future improvements will target 5.x exclusively.

First, ensure your application has no remaining deprecations from 4.x. You can check this in the Symfony profiler or by running your test suite with deprecations treated as errors. Review the EasyAdmin 4.x to 5.x Upgrade Guide for detailed instructions.

Once your project is free of deprecations, update the constraint in your composer.json:

$ composer require easycorp/easyadmin-bundle:^5.0

That is all. Since 5.0 is functionally identical to the latest 4.x release, except for removed deprecated code, no additional changes should be required.

Trying EasyAdmin for the First Time

If you are new to EasyAdmin, getting started takes only a few commands:

$ composer require easycorp/easyadmin-bundle

$ php bin/console make:admin:dashboard
$ php bin/console make:admin:crud

This creates a working admin backend with a dashboard and your first CRUD controller. From there, explore the EasyAdmin documentation to customize fields, actions, filters, and more.

You can also review the EasyAdmin Demo project.

✨ If you enjoyed these features and want to see more like it, consider
sponsoring the EasyAdmin project 🙌💡

DEV Community