feat(FolderController): Add pagination for getFolders()

Signed-off-by: provokateurin <kate@provokateurin.de>

Author: provokateurin

lib/Controller/FolderController.php

@@ -93,14 +93,21 @@ private function formatFolder(array $folder): array {
 	 * Gets all Groupfolders
 	 *
 	 * @param bool $applicable Filter by applicable groups
+	 * @param non-negative-int $offset Number of items to skip.
+	 * @param ?positive-int $limit Number of items to return.
 	 * @return DataResponse<Http::STATUS_OK, array<string, GroupFoldersFolder>, array{}>
 	 * @throws OCSNotFoundException Storage not found
+	 * @throws OCSBadRequestException Wrong limit used
 	 *
 	 * 200: Groupfolders returned
 	 */
 	#[NoAdminRequired]
 	#[FrontpageRoute(verb: 'GET', url: '/folders')]
-	public function getFolders(bool $applicable = false): DataResponse {
+	public function getFolders(bool $applicable = false, int $offset = 0, ?int $limit = null): DataResponse {
+		if ($limit !== null && $limit <= 0) {
+			throw new OCSBadRequestException('The limit must be greater than 0.');
+		}
+
 		$storageId = $this->getRootFolderStorageId();
 		if ($storageId === null) {
 			throw new OCSNotFoundException();
@@ -111,8 +118,17 @@ public function getFolders(bool $applicable = false): DataResponse {
 			// Make them string-indexed for OpenAPI JSON output
 			$folders[(string)$id] = $this->formatFolder($folder);
 		}
+
+		// Make sure the order is always the same, otherwise pagination could break.
+		ksort($folders);
+
 		$isAdmin = $this->delegationService->isAdminNextcloud() || $this->delegationService->isDelegatedAdmin();
 		if ($isAdmin && !$applicable) {
+			// If only the default values are provided the pagination can be skipped.
+			if ($offset !== 0 || $limit !== null) {
+				$folders = array_slice($folders, $offset, $limit, true);
+			}
+
 			return new DataResponse($folders);
 		}
 
@@ -124,6 +140,11 @@ public function getFolders(bool $applicable = false): DataResponse {
 			$folders = array_filter(array_map($this->filterNonAdminFolder(...), $folders));
 		}
 
+		// If only the default values are provided the pagination can be skipped.
+		if ($offset !== 0 || $limit !== null) {
+			$folders = array_slice($folders, $offset, $limit, true);
+		}
+
 		return new DataResponse($folders);
 	}
 

openapi.json

@@ -472,6 +472,29 @@
                             ]
                         }
                     },
+                    {
+                        "name": "offset",
+                        "in": "query",
+                        "description": "Number of items to skip.",
+                        "schema": {
+                            "type": "integer",
+                            "format": "int64",
+                            "default": 0,
+                            "minimum": 0
+                        }
+                    },
+                    {
+                        "name": "limit",
+                        "in": "query",
+                        "description": "Number of items to return.",
+                        "schema": {
+                            "type": "integer",
+                            "format": "int64",
+                            "nullable": true,
+                            "default": null,
+                            "minimum": 1
+                        }
+                    },
                     {
                         "name": "OCS-APIRequest",
                         "in": "header",
@@ -544,6 +567,34 @@
                                 }
                             }
                         }
+                    },
+                    "400": {
+                        "description": "Wrong limit used",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "object",
+                                    "required": [
+                                        "ocs"
+                                    ],
+                                    "properties": {
+                                        "ocs": {
+                                            "type": "object",
+                                            "required": [
+                                                "meta",
+                                                "data"
+                                            ],
+                                            "properties": {
+                                                "meta": {
+                                                    "$ref": "#/components/schemas/OCSMeta"
+                                                },
+                                                "data": {}
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                        }
                     }
                 }
             },

src/types/openapi/openapi.ts

@@ -410,6 +410,10 @@ export interface operations {
             query?: {
                 /** @description Filter by applicable groups */
                 applicable?: 0 | 1;
+                /** @description Number of items to skip. */
+                offset?: number;
+                /** @description Number of items to return. */
+                limit?: number | null;
             };
             header: {
                 /** @description Required to be true for the API request to pass */
@@ -436,6 +440,20 @@ export interface operations {
                     };
                 };
             };
+            /** @description Wrong limit used */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        ocs: {
+                            meta: components["schemas"]["OCSMeta"];
+                            data: unknown;
+                        };
+                    };
+                };
+            };
             /** @description Storage not found */
             404: {
                 headers: {