From 05c5668b21098069fc1779a4da95ddf073810fa1 Mon Sep 17 00:00:00 2001
From: Matthias Schuhmayer <38959016+mattamon@users.noreply.github.com>
Date: Thu, 18 Apr 2024 14:44:23 +0200
Subject: [PATCH] Wrap collection response into an object and set total items
 (#31)

* Wrap collection response into an object and set total items

* Apply php-cs-fixer changes

* Restructure

* Rename property

* Update minor stuff

* CS fix

* Remove unecessary brackets

* Add DataObjectCollection

* Apply php-cs-fixer changes

---------

Co-authored-by: mattamon <mattamon@users.noreply.github.com>
---
 config/filters.yaml                           | 14 ++---
 .../Response/Content/CollectionJson.php       | 37 ++++++++++++
 .../Response/Property/AssetCollection.php     | 56 +++++++++++++++++++
 .../Property/DataObjectCollection.php         | 42 ++++++++++++++
 .../Api/Assets/CollectionController.php       | 31 +---------
 .../Api/DataObjects/CollectionController.php  |  7 +--
 .../Trait/PaginatedResponseTrait.php          |  3 +-
 src/Response/Asset/Image.php                  |  2 +-
 src/Response/Collection.php                   | 48 ++++++++++++++++
 .../Filter/Loader/TaggedIteratorAdapter.php   |  8 +--
 10 files changed, 203 insertions(+), 45 deletions(-)
 create mode 100644 src/Attributes/Response/Content/CollectionJson.php
 create mode 100644 src/Attributes/Response/Property/AssetCollection.php
 create mode 100644 src/Attributes/Response/Property/DataObjectCollection.php
 create mode 100644 src/Response/Collection.php

diff --git a/config/filters.yaml b/config/filters.yaml
index 7dc94788e..74302b254 100644
--- a/config/filters.yaml
+++ b/config/filters.yaml
@@ -14,23 +14,23 @@ services:
     class: Pimcore\Bundle\StudioApiBundle\Service\Filter\FilterService
 
   Pimcore\Bundle\StudioApiBundle\Filter\PageFilter:
-    tags: [ 'pimcore.studio_api.collection.filter' ]
+    tags: [ 'pimcore.studio_api.filter' ]
 
   Pimcore\Bundle\StudioApiBundle\Filter\PageSizeFilter:
-    tags: [ 'pimcore.studio_api.collection.filter' ]
+    tags: [ 'pimcore.studio_api.filter' ]
 
   Pimcore\Bundle\StudioApiBundle\Filter\ExcludeFolderFilter:
-    tags: [ 'pimcore.studio_api.collection.filter' ]
+    tags: [ 'pimcore.studio_api.filter' ]
 
   Pimcore\Bundle\StudioApiBundle\Filter\IdSearchFilter:
-    tags: [ 'pimcore.studio_api.collection.filter' ]
+    tags: [ 'pimcore.studio_api.filter' ]
 
   Pimcore\Bundle\StudioApiBundle\Filter\ParentIdFilter:
-    tags: [ 'pimcore.studio_api.collection.filter' ]
+    tags: [ 'pimcore.studio_api.filter' ]
 
   Pimcore\Bundle\StudioApiBundle\Filter\PathFilter:
-    tags: [ 'pimcore.studio_api.collection.filter' ]
+    tags: [ 'pimcore.studio_api.filter' ]
 
   # DataObject
   Pimcore\Bundle\StudioApiBundle\Filter\DataObject\ClassIdFilter:
-      tags: [ 'pimcore.studio_api.collection.data_object.filter' ]
\ No newline at end of file
+      tags: [ 'pimcore.studio_api.data_object.filter' ]
\ No newline at end of file
diff --git a/src/Attributes/Response/Content/CollectionJson.php b/src/Attributes/Response/Content/CollectionJson.php
new file mode 100644
index 000000000..11188cfeb
--- /dev/null
+++ b/src/Attributes/Response/Content/CollectionJson.php
@@ -0,0 +1,37 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * Pimcore
+ *
+ * This source file is available under two different licenses:
+ * - GNU General Public License version 3 (GPLv3)
+ * - Pimcore Commercial License (PCL)
+ * Full copyright and license information is available in
+ * LICENSE.md which is distributed with this source code.
+ *
+ *  @copyright  Copyright (c) Pimcore GmbH (http://www.pimcore.org)
+ *  @license    http://www.pimcore.org/license     GPLv3 and PCL
+ */
+
+namespace Pimcore\Bundle\StudioApiBundle\Attributes\Response\Content;
+
+use OpenApi\Attributes\JsonContent;
+use OpenApi\Attributes\Property;
+
+/**
+ * @internal
+ */
+final class CollectionJson extends JsonContent
+{
+    public function __construct(Property $collection)
+    {
+        parent::__construct(
+            properties: [
+                new Property('totalItems', title: 'totalItems', type: 'integer', example: 666),
+                $collection,
+            ],
+            type: 'object',
+        );
+    }
+}
diff --git a/src/Attributes/Response/Property/AssetCollection.php b/src/Attributes/Response/Property/AssetCollection.php
new file mode 100644
index 000000000..a864c4df5
--- /dev/null
+++ b/src/Attributes/Response/Property/AssetCollection.php
@@ -0,0 +1,56 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * Pimcore
+ *
+ * This source file is available under two different licenses:
+ * - GNU General Public License version 3 (GPLv3)
+ * - Pimcore Commercial License (PCL)
+ * Full copyright and license information is available in
+ * LICENSE.md which is distributed with this source code.
+ *
+ *  @copyright  Copyright (c) Pimcore GmbH (http://www.pimcore.org)
+ *  @license    http://www.pimcore.org/license     GPLv3 and PCL
+ */
+
+namespace Pimcore\Bundle\StudioApiBundle\Attributes\Response\Property;
+
+use OpenApi\Attributes\Items;
+use OpenApi\Attributes\Property;
+use OpenApi\Attributes\Schema;
+use Pimcore\Bundle\StudioApiBundle\Response\Asset\Archive;
+use Pimcore\Bundle\StudioApiBundle\Response\Asset\Audio;
+use Pimcore\Bundle\StudioApiBundle\Response\Asset\Document;
+use Pimcore\Bundle\StudioApiBundle\Response\Asset\Folder;
+use Pimcore\Bundle\StudioApiBundle\Response\Asset\Image;
+use Pimcore\Bundle\StudioApiBundle\Response\Asset\Text;
+use Pimcore\Bundle\StudioApiBundle\Response\Asset\Unknown;
+use Pimcore\Bundle\StudioApiBundle\Response\Asset\Video;
+
+/**
+ * @internal
+ */
+final class AssetCollection extends Property
+{
+    public function __construct()
+    {
+        parent::__construct(
+            'items',
+            title: 'items',
+            type: 'array',
+            items: new Items(
+                anyOf: [
+                    new Schema(ref: Image::class),
+                    new Schema(ref: Document::class),
+                    new Schema(ref: Audio::class),
+                    new Schema(ref: Video::class),
+                    new Schema(ref: Archive::class),
+                    new Schema(ref: Text::class),
+                    new Schema(ref: Folder::class),
+                    new Schema(ref: Unknown::class),
+                ]
+            )
+        );
+    }
+}
diff --git a/src/Attributes/Response/Property/DataObjectCollection.php b/src/Attributes/Response/Property/DataObjectCollection.php
new file mode 100644
index 000000000..bc3d09c2b
--- /dev/null
+++ b/src/Attributes/Response/Property/DataObjectCollection.php
@@ -0,0 +1,42 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * Pimcore
+ *
+ * This source file is available under two different licenses:
+ * - GNU General Public License version 3 (GPLv3)
+ * - Pimcore Commercial License (PCL)
+ * Full copyright and license information is available in
+ * LICENSE.md which is distributed with this source code.
+ *
+ *  @copyright  Copyright (c) Pimcore GmbH (http://www.pimcore.org)
+ *  @license    http://www.pimcore.org/license     GPLv3 and PCL
+ */
+
+namespace Pimcore\Bundle\StudioApiBundle\Attributes\Response\Property;
+
+use OpenApi\Attributes\Items;
+use OpenApi\Attributes\Property;
+use OpenApi\Attributes\Schema;
+use Pimcore\Bundle\StudioApiBundle\Response\DataObject;
+
+/**
+ * @internal
+ */
+final class DataObjectCollection extends Property
+{
+    public function __construct()
+    {
+        parent::__construct(
+            'items',
+            title: 'items',
+            type: 'array',
+            items: new Items(
+                anyOf: [
+                    new Schema(ref: DataObject::class),
+                ]
+            )
+        );
+    }
+}
diff --git a/src/Controller/Api/Assets/CollectionController.php b/src/Controller/Api/Assets/CollectionController.php
index 8153d8d37..dac059fd8 100644
--- a/src/Controller/Api/Assets/CollectionController.php
+++ b/src/Controller/Api/Assets/CollectionController.php
@@ -17,9 +17,6 @@
 namespace Pimcore\Bundle\StudioApiBundle\Controller\Api\Assets;
 
 use OpenApi\Attributes\Get;
-use OpenApi\Attributes\Items;
-use OpenApi\Attributes\JsonContent;
-use OpenApi\Attributes\Schema;
 use Pimcore\Bundle\StudioApiBundle\Attributes\Parameters\Query\ExcludeFoldersParameter;
 use Pimcore\Bundle\StudioApiBundle\Attributes\Parameters\Query\IdSearchTermParameter;
 use Pimcore\Bundle\StudioApiBundle\Attributes\Parameters\Query\PageParameter;
@@ -28,6 +25,8 @@
 use Pimcore\Bundle\StudioApiBundle\Attributes\Parameters\Query\PathIncludeDescendantsParameter;
 use Pimcore\Bundle\StudioApiBundle\Attributes\Parameters\Query\PathIncludeParentParameter;
 use Pimcore\Bundle\StudioApiBundle\Attributes\Parameters\Query\PathParameter;
+use Pimcore\Bundle\StudioApiBundle\Attributes\Response\Content\CollectionJson;
+use Pimcore\Bundle\StudioApiBundle\Attributes\Response\Property\AssetCollection;
 use Pimcore\Bundle\StudioApiBundle\Attributes\Response\SuccessResponse;
 use Pimcore\Bundle\StudioApiBundle\Attributes\Response\UnauthorizedResponse;
 use Pimcore\Bundle\StudioApiBundle\Config\Tags;
@@ -35,14 +34,6 @@
 use Pimcore\Bundle\StudioApiBundle\Controller\Trait\PaginatedResponseTrait;
 use Pimcore\Bundle\StudioApiBundle\Exception\InvalidQueryTypeException;
 use Pimcore\Bundle\StudioApiBundle\Request\Query\Filter\Parameters;
-use Pimcore\Bundle\StudioApiBundle\Response\Asset\Archive;
-use Pimcore\Bundle\StudioApiBundle\Response\Asset\Audio;
-use Pimcore\Bundle\StudioApiBundle\Response\Asset\Document;
-use Pimcore\Bundle\StudioApiBundle\Response\Asset\Folder;
-use Pimcore\Bundle\StudioApiBundle\Response\Asset\Image;
-use Pimcore\Bundle\StudioApiBundle\Response\Asset\Text;
-use Pimcore\Bundle\StudioApiBundle\Response\Asset\Unknown;
-use Pimcore\Bundle\StudioApiBundle\Response\Asset\Video;
 use Pimcore\Bundle\StudioApiBundle\Service\AssetSearchServiceInterface;
 use Pimcore\Bundle\StudioApiBundle\Service\Filter\FilterServiceInterface;
 use Pimcore\Bundle\StudioApiBundle\Service\GenericData\V1\AssetQuery;
@@ -89,23 +80,7 @@ public function __construct(
     #[PathIncludeDescendantsParameter]
     #[SuccessResponse(
         description: 'Paginated assets with total count as header param',
-        content: new JsonContent(
-            type: 'array',
-            items: new Items(
-                description: 'Asset or Image object',
-                anyOf: [
-                    // TODO maybe find an easier way of describing this
-                    new Schema(ref: Archive::class),
-                    new Schema(ref: Audio::class),
-                    new Schema(ref: Document::class),
-                    new Schema(ref: Folder::class),
-                    new Schema(ref: Image::class),
-                    new Schema(ref: Text::class),
-                    new Schema(ref: Unknown::class),
-                    new Schema(ref: Video::class),
-                ]
-            )
-        )
+        content: new CollectionJson(new AssetCollection())
     )]
     #[UnauthorizedResponse]
     public function getAssets(#[MapQueryString] Parameters $parameters): JsonResponse
diff --git a/src/Controller/Api/DataObjects/CollectionController.php b/src/Controller/Api/DataObjects/CollectionController.php
index f04bf875e..60bdd5ce7 100644
--- a/src/Controller/Api/DataObjects/CollectionController.php
+++ b/src/Controller/Api/DataObjects/CollectionController.php
@@ -17,8 +17,6 @@
 namespace Pimcore\Bundle\StudioApiBundle\Controller\Api\DataObjects;
 
 use OpenApi\Attributes\Get;
-use OpenApi\Attributes\Items;
-use OpenApi\Attributes\JsonContent;
 use Pimcore\Bundle\StudioApiBundle\Attributes\Parameters\Query\ClassIdParameter;
 use Pimcore\Bundle\StudioApiBundle\Attributes\Parameters\Query\ExcludeFoldersParameter;
 use Pimcore\Bundle\StudioApiBundle\Attributes\Parameters\Query\IdSearchTermParameter;
@@ -28,6 +26,8 @@
 use Pimcore\Bundle\StudioApiBundle\Attributes\Parameters\Query\PathIncludeDescendantsParameter;
 use Pimcore\Bundle\StudioApiBundle\Attributes\Parameters\Query\PathIncludeParentParameter;
 use Pimcore\Bundle\StudioApiBundle\Attributes\Parameters\Query\PathParameter;
+use Pimcore\Bundle\StudioApiBundle\Attributes\Response\Content\CollectionJson;
+use Pimcore\Bundle\StudioApiBundle\Attributes\Response\Property\DataObjectCollection;
 use Pimcore\Bundle\StudioApiBundle\Attributes\Response\SuccessResponse;
 use Pimcore\Bundle\StudioApiBundle\Attributes\Response\UnauthorizedResponse;
 use Pimcore\Bundle\StudioApiBundle\Config\Tags;
@@ -35,7 +35,6 @@
 use Pimcore\Bundle\StudioApiBundle\Controller\Trait\PaginatedResponseTrait;
 use Pimcore\Bundle\StudioApiBundle\Exception\InvalidQueryTypeException;
 use Pimcore\Bundle\StudioApiBundle\Request\Query\Filter\DataObjectParameters;
-use Pimcore\Bundle\StudioApiBundle\Response\DataObject;
 use Pimcore\Bundle\StudioApiBundle\Service\DataObjectSearchServiceInterface;
 use Pimcore\Bundle\StudioApiBundle\Service\Filter\FilterServiceInterface;
 use Pimcore\Bundle\StudioApiBundle\Service\GenericData\V1\DataObjectQuery;
@@ -80,7 +79,7 @@ public function __construct(
     #[ClassIdParameter]
     #[SuccessResponse(
         description: 'Paginated data objects with total count as header param',
-        content: new JsonContent(type: 'array', items: new Items(ref: DataObject::class))
+        content: new CollectionJson(new DataObjectCollection())
     )]
     #[UnauthorizedResponse]
     public function getDataObjects(#[MapQueryString] DataObjectParameters $parameters): JsonResponse
diff --git a/src/Controller/Trait/PaginatedResponseTrait.php b/src/Controller/Trait/PaginatedResponseTrait.php
index 61923b7b6..dd05a5758 100644
--- a/src/Controller/Trait/PaginatedResponseTrait.php
+++ b/src/Controller/Trait/PaginatedResponseTrait.php
@@ -16,6 +16,7 @@
 
 namespace Pimcore\Bundle\StudioApiBundle\Controller\Trait;
 
+use Pimcore\Bundle\StudioApiBundle\Response\Collection;
 use Symfony\Component\HttpFoundation\JsonResponse;
 use Symfony\Component\Serializer\SerializerInterface;
 
@@ -31,7 +32,7 @@ protected function getPaginatedCollection(
         array $data,
         int $totalItems = 0
     ): JsonResponse {
-        $serialized = $serializer->serialize($data, 'json');
+        $serialized = $serializer->serialize(new Collection($totalItems, $data), 'json');
 
         return new JsonResponse($serialized, 200, [self::HEADER_TOTAL_ITEMS => $totalItems], true);
     }
diff --git a/src/Response/Asset/Image.php b/src/Response/Asset/Image.php
index f3aef2afe..21766f65a 100644
--- a/src/Response/Asset/Image.php
+++ b/src/Response/Asset/Image.php
@@ -37,7 +37,7 @@ public function __construct(
         private readonly bool $isVectorGraphic,
         #[Property(description: 'is animated', type: 'boolean', example: false)]
         private readonly bool $isAnimated,
-        #[Property(description: 'path to thumbnail', type: 'string', example: '/path/to/element/thumbnail.jpg')]
+        #[Property(description: 'path to thumbnail', type: 'string', example: '/path/to/element/hulk-smash.jpg')]
         private readonly string $thumbnailPath,
         string $iconName,
         bool $hasChildren,
diff --git a/src/Response/Collection.php b/src/Response/Collection.php
new file mode 100644
index 000000000..9d8c8e85c
--- /dev/null
+++ b/src/Response/Collection.php
@@ -0,0 +1,48 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * Pimcore
+ *
+ * This source file is available under two different licenses:
+ * - GNU General Public License version 3 (GPLv3)
+ * - Pimcore Commercial License (PCL)
+ * Full copyright and license information is available in
+ * LICENSE.md which is distributed with this source code.
+ *
+ *  @copyright  Copyright (c) Pimcore GmbH (http://www.pimcore.org)
+ *  @license    http://www.pimcore.org/license     GPLv3 and PCL
+ */
+
+namespace Pimcore\Bundle\StudioApiBundle\Response;
+
+use OpenApi\Attributes\Property;
+use OpenApi\Attributes\Schema;
+
+/**
+ * @internal
+ */
+#[Schema(
+    title: 'Collection',
+    type: 'object'
+)]
+final readonly class Collection
+{
+    public function __construct(
+        #[Property(description: 'total items', type: 'integer', example: 666)]
+        private int $totalItems,
+        #[Property(description: 'items', type: 'mixed', example: ['Asset', 'Folder', 'Document', 'DataObject'])]
+        private array $items
+    ) {
+    }
+
+    public function getTotalItems(): int
+    {
+        return $this->totalItems;
+    }
+
+    public function getItems(): array
+    {
+        return $this->items;
+    }
+}
diff --git a/src/Service/Filter/Loader/TaggedIteratorAdapter.php b/src/Service/Filter/Loader/TaggedIteratorAdapter.php
index c863060e2..5572c599a 100644
--- a/src/Service/Filter/Loader/TaggedIteratorAdapter.php
+++ b/src/Service/Filter/Loader/TaggedIteratorAdapter.php
@@ -25,13 +25,13 @@
  */
 final class TaggedIteratorAdapter implements FilterLoaderInterface
 {
-    public const FILTER_TAG = 'pimcore.studio_api.collection.filter';
+    public const FILTER_TAG = 'pimcore.studio_api.filter';
 
-    public const FILTER_ASSET_TAG = 'pimcore.studio_api.collection.asset.filter';
+    public const FILTER_ASSET_TAG = 'pimcore.studio_api.asset.filter';
 
-    public const FILTER_DATA_OBJECT_TAG = 'pimcore.studio_api.collection.data_object.filter';
+    public const FILTER_DATA_OBJECT_TAG = 'pimcore.studio_api.data_object.filter';
 
-    public const FILTER_DOCUMENT_TAG = 'pimcore.studio_api.collection.document.filter';
+    public const FILTER_DOCUMENT_TAG = 'pimcore.studio_api.document.filter';
 
     public function __construct(
         #[TaggedIterator(self::FILTER_TAG)]