feature EasyCorp#7412 Introduce an AdminControllerRegistry (javiereguiluz)

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

Discussion
----------

Introduce an AdminControllerRegistry

This is the last piece we need to be able to release the 5.x version.

`CrudControllerRegistry` and `DashboardControllerRegistry` are mostly internal classes that holds a registry of all the controllers that define a CRUD controller or a Dashboard controller. Some of their features are outdated and make no sense when using pretty URLs.

Since 5.x requires pretty URLs and deep Symfony controller integrations via `#[AdminRoute]` we can simplify many things. So, let's merge both registries into a new single `AdminControllerRegistry` that stores everything and provides useful methods that still must be used.

Commits
-------

7c6b291 Introduce an AdminControllerRegistry

Author: javiereguiluz

AGENTS.md

@@ -132,6 +132,7 @@ make checks-before-pr
 - Braces required for all control structures
 - Trailing commas in multi-line arrays
 - Blank line before `return` (unless only statement in block)
+- Don't add comments in classes as separators (e.g. `// === Methods for dashboards ===`)
 
 ### Naming
 - Variables/methods: `camelCase`

config/services.php

@@ -81,8 +81,8 @@
 use EasyCorp\Bundle\EasyAdminBundle\Orm\EntityUpdater;
 use EasyCorp\Bundle\EasyAdminBundle\Provider\AdminContextProvider;
 use EasyCorp\Bundle\EasyAdminBundle\Provider\FieldProvider;
+use EasyCorp\Bundle\EasyAdminBundle\Registry\AdminControllerRegistry;
 use EasyCorp\Bundle\EasyAdminBundle\Registry\CrudControllerRegistry;
-use EasyCorp\Bundle\EasyAdminBundle\Registry\DashboardControllerRegistry;
 use EasyCorp\Bundle\EasyAdminBundle\Router\AdminRouteGenerator;
 use EasyCorp\Bundle\EasyAdminBundle\Router\AdminRouteLoader;
 use EasyCorp\Bundle\EasyAdminBundle\Router\AdminUrlGenerator;
@@ -181,7 +181,7 @@
             ->arg(5, service('cache.easyadmin'))
             ->arg(6, service(AdminRouteGenerator::class))
             ->arg(7, '%kernel.build_dir%')
-            ->arg(8, service(CrudControllerRegistry::class))
+            ->arg(8, service(AdminControllerRegistry::class))
             ->tag('kernel.event_subscriber')
 
         ->set(ControllerFactory::class)
@@ -196,11 +196,12 @@
             ->arg(0, '%kernel.build_dir%')
             ->arg(1, new Reference('security.token_storage', ContainerInterface::NULL_ON_INVALID_REFERENCE))
             ->arg(2, new Reference(MenuFactory::class))
-            ->arg(3, new Reference(CrudControllerRegistry::class))
+            ->arg(3, new Reference(AdminControllerRegistry::class))
             ->arg(4, new Reference(EntityFactory::class))
             ->arg(5, service(AdminRouteGenerator::class))
             ->arg(6, service(ActionFactory::class))
             ->arg(7, service(EntityTranslationIdGeneratorInterface::class))
+            ->arg(8, new Reference(CrudControllerRegistry::class))
 
         ->set(AdminUrlGenerator::class)
             // I don't know if we truly need the share() method to get a new instance of the
@@ -209,7 +210,7 @@
             ->share(false)
             ->arg(0, service(AdminContextProvider::class))
             ->arg(1, service('router'))
-            ->arg(2, service(DashboardControllerRegistry::class))
+            ->arg(2, service(AdminControllerRegistry::class))
             ->arg(3, service(AdminRouteGenerator::class))
             ->arg(4, service('cache.easyadmin'))
 
@@ -221,6 +222,11 @@
             ->parent('cache.system')
             ->tag('cache.pool')
 
+        ->set(AdminControllerRegistry::class)
+            ->arg(0, '%kernel.build_dir%')
+            ->arg(1, abstract_arg('CRUD controller FQCN to Entity FQCN map'))
+            ->arg(2, abstract_arg('Dashboard controller FQCNs'))
+
         ->set(AdminRouteGenerator::class)
             ->arg(0, tagged_iterator(EasyAdminExtension::TAG_DASHBOARD_CONTROLLER))
             ->arg(1, tagged_iterator(EasyAdminExtension::TAG_CRUD_CONTROLLER))

src/Context/AdminContext.php

@@ -12,6 +12,7 @@
 use EasyCorp\Bundle\EasyAdminBundle\Dto\MainMenuDto;
 use EasyCorp\Bundle\EasyAdminBundle\Dto\SearchDto;
 use EasyCorp\Bundle\EasyAdminBundle\Dto\UserMenuDto;
+use EasyCorp\Bundle\EasyAdminBundle\Registry\AdminControllerRegistry;
 use EasyCorp\Bundle\EasyAdminBundle\Registry\CrudControllerRegistry;
 use Symfony\Component\HttpFoundation\Request;
 use Symfony\Component\Security\Core\User\UserInterface;
@@ -85,8 +86,23 @@ public function getSearch(): ?SearchDto
         return $this->crudContext->getSearch();
     }
 
+    public function getAdminControllers(): AdminControllerRegistry
+    {
+        return $this->crudContext->getAdminControllers();
+    }
+
+    /**
+     * @deprecated since 4.28.1, use getAdminControllers() instead
+     */
     public function getCrudControllers(): CrudControllerRegistry
     {
+        trigger_deprecation(
+            'easycorp/easyadmin-bundle',
+            '4.28.1',
+            'The "%s()" method is deprecated. Use "getAdminControllers()" instead.',
+            __METHOD__
+        );
+
         return $this->crudContext->getCrudControllers();
     }
 
@@ -202,7 +218,7 @@ public function withEntity(EntityDto $entityDto): self
                 $this->crudContext->getCrud(),
                 $entityDto,
                 $this->crudContext->getSearch(),
-                $this->crudContext->getCrudControllers()
+                $this->crudContext->getAdminControllers(),
             ),
             $this->dashboardContext,
             $this->i18nContext,

src/Context/CrudContext.php

@@ -5,6 +5,7 @@
 use EasyCorp\Bundle\EasyAdminBundle\Dto\CrudDto;
 use EasyCorp\Bundle\EasyAdminBundle\Dto\EntityDto;
 use EasyCorp\Bundle\EasyAdminBundle\Dto\SearchDto;
+use EasyCorp\Bundle\EasyAdminBundle\Registry\AdminControllerRegistry;
 use EasyCorp\Bundle\EasyAdminBundle\Registry\CrudControllerRegistry;
 
 /**
@@ -19,7 +20,8 @@ public function __construct(
         private readonly ?CrudDto $crudDto,
         private readonly ?EntityDto $entityDto,
         private readonly ?SearchDto $searchDto,
-        private readonly CrudControllerRegistry $crudControllers,
+        private readonly AdminControllerRegistry $adminControllers,
+        private readonly ?CrudControllerRegistry $crudControllers = null,
     ) {
     }
 
@@ -40,23 +42,36 @@ public function getSearch(): ?SearchDto
 
     public function getCrudControllers(): CrudControllerRegistry
     {
+        if (null === $this->crudControllers) {
+            throw new \LogicException('The CrudControllerRegistry is not available. This method requires the registry to be injected in the constructor.');
+        }
+
         return $this->crudControllers;
     }
 
+    public function getAdminControllers(): AdminControllerRegistry
+    {
+        return $this->adminControllers;
+    }
+
     /**
      * Creates a CrudContext instance suitable for testing.
      */
     public static function forTesting(
         ?CrudDto $crudDto = null,
         ?EntityDto $entityDto = null,
         ?SearchDto $searchDto = null,
+        ?AdminControllerRegistry $adminControllers = null,
         ?CrudControllerRegistry $crudControllers = null,
     ): self {
+        $adminControllers ??= new AdminControllerRegistry('', [], []);
+
         return new self(
             $crudDto ?? new CrudDto(),
             $entityDto,
             $searchDto,
-            $crudControllers ?? new CrudControllerRegistry([], [], [], [])
+            $adminControllers,
+            $crudControllers ?? new CrudControllerRegistry([], [], [], []),
         );
     }
 }

src/Contracts/Context/AdminContextInterface.php

@@ -10,6 +10,7 @@
 use EasyCorp\Bundle\EasyAdminBundle\Dto\MainMenuDto;
 use EasyCorp\Bundle\EasyAdminBundle\Dto\SearchDto;
 use EasyCorp\Bundle\EasyAdminBundle\Dto\UserMenuDto;
+use EasyCorp\Bundle\EasyAdminBundle\Registry\AdminControllerRegistry;
 use EasyCorp\Bundle\EasyAdminBundle\Registry\CrudControllerRegistry;
 use Symfony\Component\HttpFoundation\Request;
 use Symfony\Component\Security\Core\User\UserInterface;
@@ -28,6 +29,13 @@ public function getReferrer(): ?string;
 
     public function getI18n(): I18nDto;
 
+    // this method will be introduced in 5.0.0, but the class that implements
+    // this interface already implements it, so you can use it to smooth upgrade
+    // public function getAdminControllers(): AdminControllerRegistry;
+
+    /**
+     * @deprecated since 4.28.1, use getAdminControllers() instead
+     */
     public function getCrudControllers(): CrudControllerRegistry;
 
     /**

src/Contracts/Registry/AdminControllerRegistryInterface.php

@@ -0,0 +1,79 @@
+<?php
+
+namespace EasyCorp\Bundle\EasyAdminBundle\Contracts\Registry;
+
+/**
+ * Unified registry for Dashboard and CRUD controllers.
+ * Replaces the deprecated DashboardControllerRegistry and CrudControllerRegistry.
+ *
+ * @author Javier Eguiluz <javier.eguiluz@gmail.com>
+ */
+interface AdminControllerRegistryInterface
+{
+    /**
+     * Returns the route name for the given Dashboard controller FQCN.
+     *
+     * @param class-string $dashboardFqcn
+     */
+    public function getDashboardRoute(string $dashboardFqcn): ?string;
+
+    /**
+     * Returns the Dashboard controller FQCN for the given route name.
+     *
+     * @return class-string|null
+     */
+    public function getDashboardByRoute(string $routeName): ?string;
+
+    /**
+     * Returns the number of registered Dashboard controllers.
+     */
+    public function getDashboardCount(): int;
+
+    /**
+     * Returns the FQCN of the first registered Dashboard controller.
+     *
+     * @return class-string|null
+     */
+    public function getFirstDashboard(): ?string;
+
+    /**
+     * Returns the route name of the first registered Dashboard controller.
+     */
+    public function getFirstDashboardRoute(): ?string;
+
+    /**
+     * Returns all registered Dashboard controller FQCNs.
+     *
+     * @return array<class-string>
+     */
+    public function getAllDashboards(): array;
+
+    /**
+     * Returns the CRUD controller FQCN that manages the given entity.
+     *
+     * Note: If multiple CRUD controllers manage the same entity, only the
+     * last one registered will be returned. Use explicit controller references
+     * when multiple controllers manage the same entity.
+     *
+     * @param class-string $entityFqcn
+     *
+     * @return class-string|null
+     */
+    public function findCrudControllerByEntity(string $entityFqcn): ?string;
+
+    /**
+     * Returns the entity FQCN managed by the given CRUD controller.
+     *
+     * @param class-string $crudControllerFqcn
+     *
+     * @return class-string|null
+     */
+    public function findEntityByCrudController(string $crudControllerFqcn): ?string;
+
+    /**
+     * Returns all registered CRUD controller FQCNs.
+     *
+     * @return array<class-string>
+     */
+    public function getAllCrudControllers(): array;
+}

src/DependencyInjection/CreateControllerRegistriesPass.php

@@ -2,14 +2,15 @@
 
 namespace EasyCorp\Bundle\EasyAdminBundle\DependencyInjection;
 
+use EasyCorp\Bundle\EasyAdminBundle\Registry\AdminControllerRegistry;
 use EasyCorp\Bundle\EasyAdminBundle\Registry\CrudControllerRegistry;
 use EasyCorp\Bundle\EasyAdminBundle\Registry\DashboardControllerRegistry;
 use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
 use Symfony\Component\DependencyInjection\ContainerBuilder;
 
 /**
- * Creates the services of the Dashboard and CRUD controller registries. They can't
- * be defined as normal services because they cause circular dependencies.
+ * Creates the services of the controller registries. They can't be defined as
+ * normal services because they cause circular dependencies.
  * See https://github.com/EasyCorp/EasyAdminBundle/issues/3541.
  *
  * @author Javier Eguiluz <javier.eguiluz@gmail.com>
@@ -18,10 +19,31 @@ class CreateControllerRegistriesPass implements CompilerPassInterface
 {
     public function process(ContainerBuilder $container): void
     {
+        $this->createAdminControllerRegistryService($container);
         $this->createDashboardControllerRegistryService($container);
         $this->createCrudControllerRegistryService($container);
     }
 
+    private function createAdminControllerRegistryService(ContainerBuilder $container): void
+    {
+        $dashboardControllersFqcn = array_keys($container->findTaggedServiceIds(EasyAdminExtension::TAG_DASHBOARD_CONTROLLER, true));
+        $crudControllersFqcn = array_keys($container->findTaggedServiceIds(EasyAdminExtension::TAG_CRUD_CONTROLLER, true));
+
+        $crudFqcnToEntityFqcnMap = [];
+        foreach ($crudControllersFqcn as $controllerFqcn) {
+            $crudFqcnToEntityFqcnMap[$controllerFqcn] = $controllerFqcn::getEntityFqcn();
+        }
+
+        // the service is defined with abstract_arg() placeholders:
+        // here we only replace the dynamic arguments built from tagged services.
+        $container->getDefinition(AdminControllerRegistry::class)
+            ->replaceArgument(1, $crudFqcnToEntityFqcnMap)
+            ->replaceArgument(2, $dashboardControllersFqcn);
+    }
+
+    /**
+     * @deprecated since 4.28.1, use AdminControllerRegistry instead
+     */
     private function createDashboardControllerRegistryService(ContainerBuilder $container): void
     {
         $dashboardControllersFqcn = array_keys($container->findTaggedServiceIds(EasyAdminExtension::TAG_DASHBOARD_CONTROLLER, true));
@@ -44,6 +66,9 @@ private function createDashboardControllerRegistryService(ContainerBuilder $cont
             ]);
     }
 
+    /**
+     * @deprecated since 4.28.1, use AdminControllerRegistry instead
+     */
     private function createCrudControllerRegistryService(ContainerBuilder $container): void
     {
         $crudControllersFqcn = array_keys($container->findTaggedServiceIds(EasyAdminExtension::TAG_CRUD_CONTROLLER, true));

src/EventListener/AdminRouterSubscriber.php

@@ -9,7 +9,7 @@
 use EasyCorp\Bundle\EasyAdminBundle\Contracts\Router\AdminRouteGeneratorInterface;
 use EasyCorp\Bundle\EasyAdminBundle\Factory\AdminContextFactory;
 use EasyCorp\Bundle\EasyAdminBundle\Factory\ControllerFactory;
-use EasyCorp\Bundle\EasyAdminBundle\Registry\CrudControllerRegistry;
+use EasyCorp\Bundle\EasyAdminBundle\Registry\AdminControllerRegistry;
 use EasyCorp\Bundle\EasyAdminBundle\Router\AdminRouteGenerator;
 use Psr\Cache\CacheItemPoolInterface;
 use Symfony\Component\EventDispatcher\EventSubscriberInterface;
@@ -47,7 +47,7 @@ public function __construct(
         private readonly CacheItemPoolInterface $cache,
         private readonly AdminRouteGeneratorInterface $adminRouteGenerator,
         private readonly string $buildDir,
-        private readonly CrudControllerRegistry $crudControllerRegistry,
+        private readonly AdminControllerRegistry $adminControllers,
     ) {
     }
 
@@ -158,7 +158,7 @@ public function onKernelRequest(RequestEvent $event): void
             if (is_subclass_of($entityFqcnOrCrudControllerFqcn, CrudControllerInterface::class)) {
                 $crudControllerFqcn = $entityFqcnOrCrudControllerFqcn;
             } else {
-                $crudControllerFqcn = $this->crudControllerRegistry->findCrudFqcnByEntityFqcn($entityFqcnOrCrudControllerFqcn);
+                $crudControllerFqcn = $this->adminControllers->findCrudControllerByEntity($entityFqcnOrCrudControllerFqcn);
             }
 
             $prettyUrlRoute = $this->adminRouteGenerator->findRouteName($dashboardControllerFqcn, $crudControllerFqcn, $request->query->get(EA::CRUD_ACTION, ''));