Deprecate some Pool methods related to groups and fix array shapes

UPGRADE-3.x.md

@@ -28,6 +28,9 @@ Argument 2 of `Sonata\AdminBundle\Model\ModelManagerInterface::createQuery()` me
   Use `Sonata\AdminBundle\SonataConfiguration::getLogo()` instead.
 - `Sonata\AdminBundle\Admin\Pool::getOption()` method has been deprecated.
   Use `Sonata\AdminBundle\SonataConfiguration::getOption()` instead.
+- `Sonata\AdminBundle\Admin\Pool::getGroups()` method has been deprecated.
+- `Sonata\AdminBundle\Admin\Pool::hasGroup()` method has been deprecated.
+- `Sonata\AdminBundle\Admin\Pool::getAdminsByGroup()` method has been deprecated.
 
 ### Sonata\AdminBundle\Admin\FieldDescriptionInterface
 

src/Admin/Pool.php

@@ -20,6 +20,24 @@
 use Symfony\Component\PropertyAccess\PropertyAccessorInterface;
 
 /**
+ * @psalm-type Group = array{
+ *  label: string,
+ *  label_catalogue: string,
+ *  icon: string,
+ *  item_adds: array,
+ *  items: array<array-key, array{
+ *      admin?: string,
+ *      label?: string,
+ *      roles: list<string>,
+ *      route?: string,
+ *      router_absolute: bool,
+ *      route_params: array<string, string>
+ *  }>,
+ *  keep_open: bool,
+ *  on_top: bool,
+ *  roles: list<string>
+ * }
+ *
  * @final since sonata-project/admin-bundle 3.52
  *
  * @author Thomas Rabaix <[email protected]>
@@ -38,6 +56,8 @@ class Pool
 
     /**
      * @var array
+     * @phpstan-var array<string, array<string, mixed>>
+     * @psalm-var array<string, Group>
      */
     protected $adminGroups = [];
 
@@ -137,10 +157,19 @@ public function __construct(
     }
 
     /**
-     * @return array<string, array<string, AdminInterface>>
+     * NEXT_MAJOR: Remove this method.
+     *
+     * @deprecated since sonata-project/admin-bundle 3.x and will be removed in 4.0.
+     *
+     * @return array
      */
     public function getGroups()
     {
+        @trigger_error(sprintf(
+            'Method "%s()" is deprecated since sonata-project/admin-bundle 3.x and will be removed in version 4.0.',
+            __METHOD__
+        ), E_USER_DEPRECATED);
+
         $groups = $this->adminGroups;
 
         foreach ($this->adminGroups as $name => $adminGroup) {
@@ -153,6 +182,10 @@ public function getGroups()
     }
 
     /**
+     * NEXT_MAJOR: Remove this method.
+     *
+     * @deprecated since sonata-project/admin-bundle 3.x and will be removed in 4.0.
+     *
      * Returns whether an admin group exists or not.
      *
      * @param string $group
@@ -161,11 +194,26 @@ public function getGroups()
      */
     public function hasGroup($group)
     {
+        @trigger_error(sprintf(
+            'Method "%s()" is deprecated since sonata-project/admin-bundle 3.x and will be removed in version 4.0.',
+            __METHOD__
+        ), E_USER_DEPRECATED);
+
         return isset($this->adminGroups[$group]);
     }
 
     /**
      * @return array
+     * @phpstan-return array<string, array{
+     *  label: string,
+     *  label_catalogue: string,
+     *  icon: string,
+     *  item_adds: array,
+     *  items: array<array-key, AdminInterface>,
+     *  keep_open: bool,
+     *  on_top: bool,
+     *  roles: list<string>
+     * }>
      */
     public function getDashboardGroups()
     {
@@ -198,6 +246,10 @@ public function getDashboardGroups()
     }
 
     /**
+     * NEXT_MAJOR: Remove this method.
+     *
+     * @deprecated since sonata-project/admin-bundle 3.x and will be removed in 4.0.
+     *
      * Returns all admins related to the given $group.
      *
      * @param string $group
@@ -208,6 +260,11 @@ public function getDashboardGroups()
      */
     public function getAdminsByGroup($group)
     {
+        @trigger_error(sprintf(
+            'Method "%s()" is deprecated since sonata-project/admin-bundle 3.x and will be removed in version 4.0.',
+            __METHOD__
+        ), E_USER_DEPRECATED);
+
         if (!isset($this->adminGroups[$group])) {
             throw new \InvalidArgumentException(sprintf('Group "%s" not found in admin pool.', $group));
         }
@@ -449,6 +506,9 @@ public function getContainer()
     }
 
     /**
+     * @phpstan-param array<string, array<string, mixed>> $adminGroups
+     * @psalm-param array<string, Group> $adminGroups
+     *
      * @return void
      */
     public function setAdminGroups(array $adminGroups)

src/Twig/Extension/GroupExtension.php

@@ -44,13 +44,16 @@ public function getFunctions(): array
     }
 
     /**
-     * @phpstan-return array{array{
-     *  roles: list<string>,
-     *  icon: string,
+     * @phpstan-return array<array{
      *  label: string,
      *  label_catalogue: string,
-     *  items: AdminInterface[]
-     * }}
+     *  icon: string,
+     *  item_adds: array,
+     *  items: AdminInterface[],
+     *  keep_open: bool,
+     *  on_top: bool,
+     *  roles: list<string>
+     * }>
      */
     public function getDashboardGroupsWithCreatableAdmins(): array
     {

tests/Admin/PoolTest.php

@@ -18,11 +18,14 @@
 use Sonata\AdminBundle\Admin\AdminInterface;
 use Sonata\AdminBundle\Admin\Pool;
 use Sonata\AdminBundle\Templating\MutableTemplateRegistryInterface;
+use Symfony\Bridge\PhpUnit\ExpectDeprecationTrait;
 use Symfony\Component\DependencyInjection\Container;
 use Symfony\Component\DependencyInjection\ContainerInterface;
 
 class PoolTest extends TestCase
 {
+    use ExpectDeprecationTrait;
+
     /**
      * @var Container
      */
@@ -40,6 +43,11 @@ protected function setUp(): void
         $this->pool = new Pool($this->container, 'Sonata Admin', '/path/to/pic.png', ['foo' => 'bar']);
     }
 
+    /**
+     * NEXT_MAJOR: Remove this method.
+     *
+     * @group legacy
+     */
     public function testGetGroups(): void
     {
         $this->container->set('sonata.user.admin.group1', $this->createMock(AdminInterface::class));
@@ -50,17 +58,26 @@ public function testGetGroups(): void
             'adminGroup1' => ['sonata.user.admin.group1' => []],
         ]);
 
+        $this->expectDeprecation('Method "Sonata\AdminBundle\Admin\Pool::getGroups()" is deprecated since sonata-project/admin-bundle 3.x and will be removed in version 4.0.');
+
         $result = $this->pool->getGroups();
         $this->assertArrayHasKey('adminGroup1', $result);
         $this->assertArrayHasKey('sonata.user.admin.group1', $result['adminGroup1']);
     }
 
+    /**
+     * NEXT_MAJOR: Remove this test.
+     *
+     * @group legacy
+     */
     public function testHasGroup(): void
     {
         $this->pool->setAdminGroups([
             'adminGroup1' => [],
         ]);
 
+        $this->expectDeprecation('Method "Sonata\AdminBundle\Admin\Pool::hasGroup()" is deprecated since sonata-project/admin-bundle 3.x and will be removed in version 4.0.');
+
         $this->assertTrue($this->pool->hasGroup('adminGroup1'));
         $this->assertFalse($this->pool->hasGroup('adminGroup2'));
     }
@@ -103,26 +120,43 @@ public function testGetDashboardGroups(): void
         $this->assertSame($adminGroup1, $groups['adminGroup1']['items']['itemKey']);
     }
 
+    /**
+     * NEXT_MAJOR: Remove this test.
+     *
+     * @group legacy
+     */
     public function testGetAdminsByGroupWhenGroupNotSet(): void
     {
-        $this->expectException(\InvalidArgumentException::class);
-
         $this->pool->setAdminGroups([
                 'adminGroup1' => [],
             ]);
 
+        $this->expectException(\InvalidArgumentException::class);
+
         $this->pool->getAdminsByGroup('adminGroup2');
     }
 
+    /**
+     * NEXT_MAJOR: Remove this test.
+     *
+     * @group legacy
+     */
     public function testGetAdminsByGroupWhenGroupIsEmpty(): void
     {
         $this->pool->setAdminGroups([
                 'adminGroup1' => [],
             ]);
 
+        $this->expectDeprecation('Method "Sonata\AdminBundle\Admin\Pool::getAdminsByGroup()" is deprecated since sonata-project/admin-bundle 3.x and will be removed in version 4.0.');
+
         $this->assertSame([], $this->pool->getAdminsByGroup('adminGroup1'));
     }
 
+    /**
+     * NEXT_MAJOR: Remove this test.
+     *
+     * @group legacy
+     */
     public function testGetAdminsByGroup(): void
     {
         $this->container->set('sonata.admin1', $this->createMock(AdminInterface::class));
@@ -143,6 +177,8 @@ public function testGetAdminsByGroup(): void
             ],
         ]);
 
+        $this->expectDeprecation('Method "Sonata\AdminBundle\Admin\Pool::getAdminsByGroup()" is deprecated since sonata-project/admin-bundle 3.x and will be removed in version 4.0.');
+
         $this->assertCount(2, $this->pool->getAdminsByGroup('adminGroup1'));
         $this->assertCount(1, $this->pool->getAdminsByGroup('adminGroup2'));
     }