#2492 - Groups filtering & retrieve single endpoint (#3084)

Fixes #2492

* Added api/groups/{id} endpoint for retrieving a single group by its id
* Fixed GroupRepository incorrectly opening query to User instead of Group model
* Added filtering & paging abilities to GET api/groups endpoint
* Added test for sorting for GET api/groups endpoint

Co-authored-by: Alexander Skvortsov <38059171+askvortsov1@users.noreply.github.com>

tests/integration/api/groups/ListTest.php

@@ -65,6 +65,148 @@ class ListTest extends TestCase
         $this->assertEquals(['1', '2', '3', '4', '10'], Arr::pluck($data['data'], 'id'));
     }
 
+    /**
+     * @test
+     */
+    public function filters_only_public_groups_for_admin()
+    {
+        $response = $this->send(
+            $this->request('GET', '/api/groups', [
+                'authenticatedAs' => 1,
+            ])
+            ->withQueryParams([
+                'filter' => ['hidden' => 0],
+            ])
+        );
+
+        $this->assertEquals(200, $response->getStatusCode());
+        $data = json_decode($response->getBody()->getContents(), true);
+
+        // The four default groups created by the installer without our hidden group
+        $this->assertEquals(['1', '2', '3', '4'], Arr::pluck($data['data'], 'id'));
+    }
+
+    /**
+     * @test
+     */
+    public function filters_only_hidden_groups_for_admin()
+    {
+        $response = $this->send(
+            $this->request('GET', '/api/groups', [
+                'authenticatedAs' => 1,
+            ])
+            ->withQueryParams([
+                'filter' => ['hidden' => 1],
+            ])
+        );
+
+        $this->assertEquals(200, $response->getStatusCode());
+        $data = json_decode($response->getBody()->getContents(), true);
+
+        // Only our hidden group
+        $this->assertEquals(['10'], Arr::pluck($data['data'], 'id'));
+    }
+
+    /**
+     * @test
+     */
+    public function filters_only_public_groups_for_guest()
+    {
+        $response = $this->send(
+            $this->request('GET', '/api/groups')
+            ->withQueryParams([
+                'filter' => ['hidden' => 0],
+            ])
+        );
+
+        $this->assertEquals(200, $response->getStatusCode());
+        $data = json_decode($response->getBody()->getContents(), true);
+
+        // The four default groups created by the installer without our hidden group
+        $this->assertEquals(['1', '2', '3', '4'], Arr::pluck($data['data'], 'id'));
+    }
+
+    /**
+     * @test
+     */
+    public function hides_hidden_groups_when_filtering_for_guest()
+    {
+        $response = $this->send(
+            $this->request('GET', '/api/groups')
+            ->withQueryParams([
+                'filter' => ['hidden' => 1],
+            ])
+        );
+
+        $this->assertEquals(200, $response->getStatusCode());
+        $data = json_decode($response->getBody()->getContents(), true);
+
+        // When guest attempts to filter for hidden groups, system should
+        // still apply scoping and exclude those groups from results
+        $this->assertEquals([], Arr::pluck($data['data'], 'id'));
+    }
+
+    /**
+     * @test
+     */
+    public function paginates_groups_without_filter()
+    {
+        $response = $this->send(
+            $this->request('GET', '/api/groups')
+            ->withQueryParams([
+                'page' => ['limit' => '2', 'offset' => '2'],
+            ])
+        );
+
+        $this->assertEquals(200, $response->getStatusCode());
+        $data = json_decode($response->getBody()->getContents(), true);
+
+        // Show second page of groups
+        $this->assertEquals(['3', '4'], Arr::pluck($data['data'], 'id'));
+    }
+
+    /**
+     * @test
+     */
+    public function paginates_groups_with_filter()
+    {
+        $response = $this->send(
+            $this->request('GET', '/api/groups')
+            ->withQueryParams([
+                'filter' => ['hidden' => 1],
+                'page' => ['limit' => '1', 'offset' => '1'],
+            ])
+        );
+
+        $this->assertEquals(200, $response->getStatusCode());
+        $data = json_decode($response->getBody()->getContents(), true);
+
+        // Show second page of groups. Because there is only one hidden group,
+        // second page should be empty.
+        $this->assertEmpty($data['data']);
+    }
+
+    /**
+     * @test
+     */
+    public function sorts_groups_by_name()
+    {
+        $response = $this->send(
+            $this->request('GET', '/api/groups', [
+                'authenticatedAs' => 1,
+            ])
+            ->withQueryParams([
+                'sort' => 'nameSingular',
+            ])
+        );
+
+        $this->assertEquals(200, $response->getStatusCode());
+        $data = json_decode($response->getBody()->getContents(), true);
+
+        // Ascending alphabetical order is: Admin - Guest - Hidden - Member - Mod
+        $this->assertEquals(['1', '2', '10', '3', '4'], Arr::pluck($data['data'], 'id'));
+    }
+
     protected function hiddenGroup(): array
     {
         return [

tests/integration/api/groups/ShowTest.php

@@ -0,0 +1,126 @@
+<?php
+
+/*
+ * This file is part of Flarum.
+ *
+ * For detailed copyright and license information, please view the
+ * LICENSE file that was distributed with this source code.
+ */
+
+namespace Flarum\Tests\integration\api\groups;
+
+use Flarum\Testing\integration\RetrievesAuthorizedUsers;
+use Flarum\Testing\integration\TestCase;
+use Illuminate\Support\Arr;
+
+class ShowTest extends TestCase
+{
+    use RetrievesAuthorizedUsers;
+
+    /**
+     * @inheritDoc
+     */
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        $this->prepareDatabase([
+            'groups' => [
+                $this->hiddenGroup(),
+            ],
+        ]);
+    }
+
+    /**
+     * @test
+     */
+    public function shows_public_group_for_guest()
+    {
+        $response = $this->send(
+            $this->request('GET', '/api/groups/1')
+        );
+
+        $this->assertEquals(200, $response->getStatusCode());
+        $data = json_decode($response->getBody()->getContents(), true);
+
+        // Default group created by the installer should be returned
+        $this->assertEquals('1', Arr::get($data, 'data.id'));
+    }
+
+    /**
+     * @test
+     */
+    public function shows_public_group_for_admin()
+    {
+        $response = $this->send(
+            $this->request('GET', '/api/groups/1', [
+                'authenticatedAs' => 1,
+            ])
+        );
+
+        $this->assertEquals(200, $response->getStatusCode());
+        $data = json_decode($response->getBody()->getContents(), true);
+
+        // Default group created by the installer should be returned
+        $this->assertEquals('1', Arr::get($data, 'data.id'));
+    }
+
+    /**
+     * @test
+     */
+    public function hides_hidden_group_for_guest()
+    {
+        $response = $this->send(
+            $this->request('GET', '/api/groups/10')
+        );
+
+        // Hidden group should not be returned for guest
+        $this->assertEquals(404, $response->getStatusCode());
+    }
+
+    /**
+     * @test
+     */
+    public function shows_hidden_group_for_admin()
+    {
+        $response = $this->send(
+            $this->request('GET', '/api/groups/10', [
+                'authenticatedAs' => 1,
+            ])
+        );
+
+        $this->assertEquals(200, $response->getStatusCode());
+        $data = json_decode($response->getBody()->getContents(), true);
+
+        // Hidden group should be returned for admin
+        $this->assertEquals('10', Arr::get($data, 'data.id'));
+    }
+
+    /**
+     * @test
+     */
+    public function rejects_request_for_non_existing_group()
+    {
+        $response = $this->send(
+            $this->request('GET', '/api/groups/999', [
+                'authenticatedAs' => 1,
+            ])
+        );
+
+        // If group does not exist in database, controller
+        // should reject the request with 404 Not found
+        $this->assertEquals(404, $response->getStatusCode());
+    }
+
+    protected function hiddenGroup(): array
+    {
+        return [
+            'id' => 10,
+            'name_singular' => 'Hidden',
+            'name_plural' => 'Ninjas',
+            'color' => null,
+            'icon' => 'fas fa-wrench',
+            'is_hidden' => 1
+        ];
+    }
+}