feature #6769 Update admin dashboard (javiereguiluz)

This PR was squashed before being merged into the 4.x branch.

Discussion
----------

Update admin dashboard

When we moved to "pretty URLs", the recommended solution to define the dashboard route was this:

```php
// ...
use Symfony\Component\Routing\Attribute\Route;

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

    // ...
}
```

In the past weeks we've faced many issues related to the cache and the event listener related to admin URLs. The problem to solve is this: we need to find out very quickly (i.e. performant) and unequivocally if a given URLs belongs to an EasyAdmin backend or not.

When using pretty URLs, this is trivial because we generate those routes and apply some special route attributes to them. But, there's a missing route: the main dashboard route. That one is defined by the user and we cannot add those special attributes to it. Trust me, I tried this very hard (even asking internally to the Symfony Core Team). This is not possible technically speaking.

So, after thinking a lot about this, I propose to use the recently introduced `#[AdminDashboard]` attribute to define the admin route:

```php
use EasyCorp\Bundle\EasyAdminBundle\Attribute\AdminDashboard;
use EasyCorp\Bundle\EasyAdminBundle\Config\Dashboard;
use EasyCorp\Bundle\EasyAdminBundle\Controller\AbstractDashboardController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

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

    // ...
}
```

This will solve all our problems, because this attribute will be used to generate the associated Symfony route. Since we create that route, we can apply the custom route attributes. This makes the caching hacks unnecessary and improves the performance of the application. So, I propose to add this now and make it mandatory in EasyAdmin 5.x as the only solution that works to define admin routes.

I know all these changes are tiring 😫 but this is the last time we'll change this and I think the change is worth it because it will solve all our internal issues related to admin routes 🙏

What do you think?

Commits
-------

901a892 Update admin dashboard

Author: javiereguiluz

doc/actions.rst

@@ -606,9 +606,11 @@ main menu using the ``configureMenuItems()`` method::
     // src/Controller/Admin/DashboardController.php
     namespace App\Controller\Admin;
 
+    use EasyCorp\Bundle\EasyAdminBundle\Attribute\AdminDashboard;
     use EasyCorp\Bundle\EasyAdminBundle\Config\Dashboard;
     use EasyCorp\Bundle\EasyAdminBundle\Controller\AbstractDashboardController;
 
+    #[AdminDashboard(routePath: '/admin', routeName: 'admin')]
     class DashboardController extends AbstractDashboardController
     {
         // ...

doc/crud.rst

@@ -79,12 +79,12 @@ Admin route name                Admin route path
     on each dahboard to not generate all these routes.
 
 You can customize the route names and/or paths of the actions of all the CRUD controllers
-served by some dashboard using the ``#[AdminDashboard]`` attribute::
+served by some dashboard using the ``routes`` option of the ``#[AdminDashboard]`` attribute::
 
     use EasyCorp\Bundle\EasyAdminBundle\Attribute\AdminDashboard;
     // ...
 
-    #[AdminDashboard(routes: [
+    #[AdminDashboard(routePath: '/admin', routeName: 'admin', routes: [
         'index' => ['routePath' => '/all'],
         'new' => ['routePath' => '/create', 'routeName' => 'create'],
         'edit' => ['routePath' => '/editing-{entityId}', 'routeName' => 'editing'],
@@ -554,10 +554,12 @@ If you want to do the same config in all CRUD controllers, there's no need to
 repeat the config in each controller. Instead, add the ``configureCrud()`` method
 in your dashboard and all controllers will inherit that configuration::
 
+    use EasyCorp\Bundle\EasyAdminBundle\Attribute\AdminDashboard;
     use EasyCorp\Bundle\EasyAdminBundle\Config\Crud;
     use EasyCorp\Bundle\EasyAdminBundle\Config\Dashboard;
     use EasyCorp\Bundle\EasyAdminBundle\Controller\AbstractDashboardController;
 
+    #[AdminDashboard(routePath: '/admin', routeName: 'admin')]
     class DashboardController extends AbstractDashboardController
     {
         // ...

doc/dashboards.rst

@@ -25,9 +25,8 @@ shortcuts like ``$this->render()`` or ``$this->isGranted()``.
 Dashboard controller classes must implement the
 ``EasyCorp\Bundle\EasyAdminBundle\Contracts\Controller\DashboardControllerInterface``,
 which ensures that certain methods are defined in the dashboard. Instead of
-implementing the interface, you can also extend from the
-``AbstractDashboardController`` class. Run the following command to quickly
-generate a dashboard controller:
+implementing the interface, you can also extend the ``AbstractDashboardController``
+class. Run the following command to quickly generate a dashboard controller:
 
 .. code-block:: terminal
 
@@ -76,21 +75,22 @@ first in your application. To do so, create this file:
     The ``easyadmin.routes`` string is also available as the PHP constant
     ``\EasyCorp\Bundle\EasyAdminBundle\Router\AdminRouteLoader::ROUTE_LOADER_TYPE``.
 
-Now, define the main route of your dashboard class using a PHP attribute in the
-``index()`` method of that controller (if you don't have a Dashboard yet, you can
-quickly generate one running the command ``make:admin:dashboard``)::
+Now, define the main route of your dashboard class using the following PHP attribute
+(if you don't have a Dashboard yet, you can quickly generate one running the command
+``make:admin:dashboard``)::
 
     // src/Controller/Admin/DashboardController.php
     namespace App\Controller\Admin;
 
+    use EasyCorp\Bundle\EasyAdminBundle\Attribute\AdminDashboard;
     use EasyCorp\Bundle\EasyAdminBundle\Config\Dashboard;
     use EasyCorp\Bundle\EasyAdminBundle\Controller\AbstractDashboardController;
     use Symfony\Component\HttpFoundation\Response;
     use Symfony\Component\Routing\Attribute\Route;
 
+    #[AdminDashboard(routePath: '/admin', routeName: 'admin')]
     class DashboardController extends AbstractDashboardController
     {
-        #[Route('/admin', name: 'admin')]
         public function index(): Response
         {
             return parent::index();
@@ -101,8 +101,25 @@ quickly generate one running the command ``make:admin:dashboard``)::
 
 .. caution::
 
-    The dashboard route must be defined using the ``#[Route]`` attribute. None
-    of the other ways supported by Symfony to configure a route will work.
+    The dashboard route must be defined using the ``#[AdminDashboard]`` attribute.
+    None of the other ways supported by Symfony to configure a route will work.
+
+.. versionadded:: 4.24.0
+
+    The feature to define the dashboard route using the ``#[AdminDashboard]``
+    attribute was introduced in EasyAdmin 4.24.0.
+
+EasyAdmin uses the configuration of the ``#[AdminDashboard]`` attribute to create
+the main route of your dashboard. You can verify this by running the following command:
+
+.. code-block:: terminal
+
+    $ php bin/console debug:router
+
+.. tip::
+
+    If you don't see any of the routes that must be generated by EasyAdmin, delete
+    the cache of your application to force the regeneration of the routes.
 
 .. tip::
 
@@ -114,15 +131,42 @@ The ``index()`` method is called by EasyAdmin to render your dashboard. Since
 to inject dependencies. Instead, inject those dependencies in the constructor
 method of the controller.
 
-The name of the ``index()`` route will be used as the prefix of all the routes
-associated to this dashboard (e.g. if this route name is ``my_private_backend``,
+The name of the dashboard route should be concise because it's used as the prefix
+of all the routes associated to this dashboard (e.g. if this route name is ``my_private_backend``,
 the generated routes will be like ``my_private_backend_product_index``). The path
 of this route will also be used by all the dasboard routes (e.g. if the path is
 ``/_secret/backend``, the generated routes paths will be like ``/_secret/backend/category/324``).
 
 That's it. Later, when you start adding :doc:`CRUD controllers </crud>`, the route
 loader will create all the needed routes for each of them.
 
+Defining the Route in the ``index()`` Method
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Using the ``#[AdminDashboard]`` attribute is the recommended way to define the
+dashboard route. However, you can also define the dashboard route aplying the
+``#[Route]`` attribute on the ``index()`` method::
+
+    // ...
+    use Symfony\Component\Routing\Attribute\Route;
+
+    class DashboardController extends AbstractDashboardController
+    {
+        #[Route('/admin', name: 'admin')]
+        public function index(): Response
+        {
+            return parent::index();
+        }
+
+        // ...
+    }
+
+.. caution::
+
+    This alternative still works in EasyAdmin 4.x versions, but **it's deprecated
+    and it won't work in EasyAdmin 5.x**. It's recommended to update the dashboard
+    classes as soon as possible to use the ``#[AdminDashboard]`` attribute.
+
 Legacy Admin URLs
 -----------------
 
@@ -315,10 +359,12 @@ explained later)::
 
     namespace App\Controller\Admin;
 
+    use EasyCorp\Bundle\EasyAdminBundle\Attribute\AdminDashboard;
     use EasyCorp\Bundle\EasyAdminBundle\Config\Dashboard;
     use EasyCorp\Bundle\EasyAdminBundle\Controller\AbstractDashboardController;
     use EasyCorp\Bundle\EasyAdminBundle\Dto\LocaleDto;
 
+    #[AdminDashboard(routePath: '/admin', routeName: 'admin')]
     class DashboardController extends AbstractDashboardController
     {
         // ...
@@ -409,11 +455,13 @@ provide yet any way of creating those widgets. It's in our list of future featur
 but meanwhile you can use `Symfony UX Chart.js`_ bundle to create those charts
 and render them in your own Twig template::
 
+    use EasyCorp\Bundle\EasyAdminBundle\Attribute\AdminDashboard;
     use EasyCorp\Bundle\EasyAdminBundle\Config\Dashboard;
     use EasyCorp\Bundle\EasyAdminBundle\Controller\AbstractDashboardController;
     use Symfony\UX\Chartjs\Builder\ChartBuilderInterface;
     use Symfony\UX\Chartjs\Model\Chart;
 
+    #[AdminDashboard(routePath: '/admin', routeName: 'admin')]
     class DashboardController extends AbstractDashboardController
     {
         public function __construct(
@@ -424,7 +472,6 @@ and render them in your own Twig template::
         // ... you'll also need to load some CSS/JavaScript assets to render
         // the charts; this is explained later in the chapter about Design
 
-        #[Route('/admin')]
         public function index(): Response
         {
             $chart = $this->chartBuilder->createChart(Chart::TYPE_LINE);
@@ -459,15 +506,16 @@ Another popular option is to avoid a dashboard at all and instead redirect to th
 for people working on the backend. This requires :ref:`generating admin URLs <generate-admin-urls>`,
 and :doc:`CRUD controllers </crud>`, which is explained in detail later::
 
+    use EasyCorp\Bundle\EasyAdminBundle\Attribute\AdminDashboard;
     use EasyCorp\Bundle\EasyAdminBundle\Config\Dashboard;
     use EasyCorp\Bundle\EasyAdminBundle\Controller\AbstractDashboardController;
     use EasyCorp\Bundle\EasyAdminBundle\Router\AdminUrlGenerator;
 
+    #[AdminDashboard(routePath: '/admin', routeName: 'admin')]
     class DashboardController extends AbstractDashboardController
     {
         // ...
 
-        #[Route('/admin', name: 'admin')]
         public function index(): Response
         {
             // when using pretty admin URLs, you can redirect directly to some route
@@ -504,9 +552,11 @@ the look and behavior of each menu item::
     use App\Entity\Category;
     use App\Entity\Comment;
     use App\Entity\User;
+    use EasyCorp\Bundle\EasyAdminBundle\Attribute\AdminDashboard;
     use EasyCorp\Bundle\EasyAdminBundle\Config\Dashboard;
     use EasyCorp\Bundle\EasyAdminBundle\Controller\AbstractDashboardController;
 
+    #[AdminDashboard(routePath: '/admin', routeName: 'admin')]
     class DashboardController extends AbstractDashboardController
     {
         // ...
@@ -789,11 +839,13 @@ The user name is the result of calling to the ``__toString()`` method on the
 current user object. The user avatar is a generic avatar icon. Use the
 ``configureUserMenu()`` method to configure the features and items of this menu::
 
+    use EasyCorp\Bundle\EasyAdminBundle\Attribute\AdminDashboard;
     use EasyCorp\Bundle\EasyAdminBundle\Config\MenuItem;
     use EasyCorp\Bundle\EasyAdminBundle\Config\UserMenu;
     use EasyCorp\Bundle\EasyAdminBundle\Controller\AbstractDashboardController;
     use Symfony\Component\Security\Core\User\UserInterface;
 
+    #[AdminDashboard(routePath: '/admin', routeName: 'admin')]
     class DashboardController extends AbstractDashboardController
     {
         // ...
@@ -899,6 +951,7 @@ The rest of the contents (e.g. the label of the menu items, entity and field
 names, etc.) use the ``messages`` translation domain by default. You can change
 this value with the ``translationDomain()`` method::
 
+    #[AdminDashboard(routePath: '/admin', routeName: 'admin')]
     class DashboardController extends AbstractDashboardController
     {
         // ...
@@ -941,6 +994,7 @@ HTML text direction is set to ``rtl`` (right-to-left) automatically. Otherwise,
 the text is displayed as ``ltr`` (left-to-right), but you can configure this
 value explicitly::
 
+    #[AdminDashboard(routePath: '/admin', routeName: 'admin')]
     class DashboardController extends AbstractDashboardController
     {
         // ...

doc/design.rst

@@ -38,10 +38,12 @@ If you prefer to use other icons, call the ``useCustomIconSet()`` in your dashbo
 
     namespace App\Controller\Admin;
 
+    use EasyCorp\Bundle\EasyAdminBundle\Attribute\AdminDashboard;
     use EasyCorp\Bundle\EasyAdminBundle\Config\Assets;
     use EasyCorp\Bundle\EasyAdminBundle\Config\Option\IconSet;
     use EasyCorp\Bundle\EasyAdminBundle\Controller\AbstractDashboardController;
 
+    #[AdminDashboard(routePath: '/admin', routeName: 'admin')]
     class DashboardController extends AbstractDashboardController
     {
         public function configureAssets(): Assets
@@ -139,9 +141,11 @@ This option allows you to render certain parts of the backend with your own Twig
 templates. First, you can replace some templates globally in the
 :doc:`dashboard </dashboards>`::
 
+    use EasyCorp\Bundle\EasyAdminBundle\Attribute\AdminDashboard;
     use EasyCorp\Bundle\EasyAdminBundle\Config\Crud;
     use EasyCorp\Bundle\EasyAdminBundle\Controller\AbstractDashboardController;
 
+    #[AdminDashboard(routePath: '/admin', routeName: 'admin')]
     class DashboardController extends AbstractDashboardController
     {
         // ...
@@ -390,9 +394,11 @@ To override any of them, create a CSS file and redefine the variable values:
 
 Then, load this CSS file in your dashboard and/or resource admin::
 
+    use EasyCorp\Bundle\EasyAdminBundle\Attribute\AdminDashboard;
     use EasyCorp\Bundle\EasyAdminBundle\Config\Assets;
     use EasyCorp\Bundle\EasyAdminBundle\Controller\AbstractDashboardController;
 
+    #[AdminDashboard(routePath: '/admin', routeName: 'admin')]
     class DashboardController extends AbstractDashboardController
     {
         // ...

doc/security.rst

@@ -41,10 +41,12 @@ cumbersome because you must apply it to all dashboard controllers and to all the
 :doc:`CRUD controllers </crud>`::
 
     // app/Controller/Admin/DashboardController.php
+    use EasyCorp\Bundle\EasyAdminBundle\Attribute\AdminDashboard;
     use EasyCorp\Bundle\EasyAdminBundle\Config\Dashboard;
     use EasyCorp\Bundle\EasyAdminBundle\Controller\AbstractDashboardController;
     use Symfony\Component\Security\Http\Attribute\IsGranted;
 
+    #[AdminDashboard(routePath: '/admin', routeName: 'admin')]
     #[IsGranted('ROLE_ADMIN')]
     class DashboardController extends AbstractDashboardController
     {
@@ -75,7 +77,10 @@ is to use the ``#[AdminDashboard]`` attribute::
     use EasyCorp\Bundle\EasyAdminBundle\Attribute\AdminDashboard;
     use EasyCorp\Bundle\EasyAdminBundle\Controller\AbstractDashboardController;
 
-    #[AdminDashboard(allowedControllers: [BlogPostCrudController::class, BlogCategoryCrudController::class])]
+    #[AdminDashboard(routePath: '/admin', routeName: 'admin', allowedControllers: [
+        BlogPostCrudController::class,
+        BlogCategoryCrudController::class,
+    ])]
     class DashboardController extends AbstractDashboardController
     {
         // ...

src/Attribute/AdminDashboard.php

@@ -9,12 +9,66 @@
 class AdminDashboard
 {
     public function __construct(
-        /** @var array<string, array{routeName?: string, routePath?: string}>|null */
+        /**
+         * @param string|null $routePath The path of the Symfony route that will be created for the dashboard (e.g. '/admin)
+         */
+        public /* ?string */ $routePath = null,
+        /**
+         * @param string|null $routeName The name of the Symfony route that will be created for the dashboard (e.g. 'admin')
+         */
+        public /* ?string */ $routeName = null,
+        /**
+         * @param array{
+         *     requirements?: array,
+         *     options?: array,
+         *     defaults?: array,
+         *     host?: string,
+         *     methods?: array|string,
+         *     schemes?: array|string,
+         *     condition?: string,
+         *     locale?: string,
+         *     format?: string,
+         *     utf8?: bool,
+         *     stateless?: bool,
+         * } $routeOptions The configuration used when creating the Symfony route for the dashboard (these values are passed "as is" without any additional validation)
+         */
+        public array $routeOptions = [],
+        /** @var array<string, array{routeName?: string, routePath?: string}>|null Allows to change the default route name and/or path of the CRUD actions for this dashboard */
         public ?array $routes = null,
         /** @var class-string[]|null $allowedControllers If defined, only these CRUD controllers will have a route defined for them */
         public ?array $allowedControllers = null,
         /** @var class-string[]|null $deniedControllers If defined, all CRUD controllers will have a route defined for them except these ones */
         public ?array $deniedControllers = null,
     ) {
+        // when this attribute was first created, the $routes, $allowedControllers, and $deniedControllers
+        // were the first and only arguments of the class; now we added $routePath and $routeName as the
+        // first arguments, so we need to move the values of the old arguments to the new ones
+        if (\func_num_args() > 0 && \is_array(func_get_arg(0))) {
+            $this->routes = func_get_arg(0);
+            trigger_deprecation(
+                'easycorp/easyadmin-bundle',
+                '4.24.0',
+                'Passing $routes as the first argument of the "%s" attribute is deprecated and will no longer work in EasyAdmin 5.0.0. Pass the routes as the fourth argument or, better, use the \'routes:\' named argument.',
+                __CLASS__,
+            );
+        }
+        if (\func_num_args() > 1 && \is_array(func_get_arg(1))) {
+            $this->allowedControllers = func_get_arg(1);
+            trigger_deprecation(
+                'easycorp/easyadmin-bundle',
+                '4.24.0',
+                'Passing $allowedControllers as the second argument of the "%s" attribute is deprecated and will no longer work in EasyAdmin 5.0.0. Pass the allowed controllers as the fifth argument or, better, use the \'allowedControllers:\' named argument.',
+                __CLASS__,
+            );
+        }
+        if (\func_num_args() > 2 && \is_array(func_get_arg(0)) && \is_array(func_get_arg(1)) && \is_array(func_get_arg(2))) {
+            $this->deniedControllers = func_get_arg(2);
+            trigger_deprecation(
+                'easycorp/easyadmin-bundle',
+                '4.24.0',
+                'Passing $deniedControllers as the third argument of the "%s" attribute is deprecated and will no longer work in EasyAdmin 5.0.0. Pass the denied controllers as the sixth argument or, better, use the \'deniedControllers:\' named argument.',
+                __CLASS__,
+            );
+        }
     }
 }