Merge pull request #49015 from nextcloud/fix/openapi/array-syntax

7 files changed, 60 insertions, 32 deletions

diff --git a/apps/files/lib/Capabilities.php b/apps/files/lib/Capabilities.php
index d20d348a9f5..16ea42eae22 100644
--- a/apps/files/lib/Capabilities.php
+++ b/apps/files/lib/Capabilities.php
@@ -21,7 +21,7 @@ class Capabilities implements ICapability {
 	/**
 	 * Return this classes capabilities
 	 *
-	 * @return array{files: array{'$comment': ?string, bigfilechunking: bool, blacklisted_files: array<mixed>, forbidden_filenames: list<string>, forbidden_filename_basenames: list<string>, forbidden_filename_characters: list<string>, forbidden_filename_extensions: list<string>, chunked_upload: array{max_size: int, max_parallel_count: int}}}
+	 * @return array{files: array{'$comment': ?string, bigfilechunking: bool, blacklisted_files: list<mixed>, forbidden_filenames: list<string>, forbidden_filename_basenames: list<string>, forbidden_filename_characters: list<string>, forbidden_filename_extensions: list<string>, chunked_upload: array{max_size: int, max_parallel_count: int}}}
 	 */
 	public function getCapabilities(): array {
 		return [
diff --git a/apps/files/lib/Controller/DirectEditingController.php b/apps/files/lib/Controller/DirectEditingController.php
index 63f29d3ba2a..2c910006df5 100644
--- a/apps/files/lib/Controller/DirectEditingController.php
+++ b/apps/files/lib/Controller/DirectEditingController.php
@@ -36,7 +36,7 @@ class DirectEditingController extends OCSController {
 
 	/**
 	 * Get the direct editing capabilities
-	 * @return DataResponse<Http::STATUS_OK, array{editors: array<string, array{id: string, name: string, mimetypes: string[], optionalMimetypes: string[], secure: bool}>, creators: array<string, array{id: string, editor: string, name: string, extension: string, templates: bool, mimetypes: string[]}>}, array{}>
+	 * @return DataResponse<Http::STATUS_OK, array{editors: array<string, array{id: string, name: string, mimetypes: list<string>, optionalMimetypes: list<string>, secure: bool}>, creators: array<string, array{id: string, editor: string, name: string, extension: string, templates: bool, mimetypes: list<string>}>}, array{}>
 	 *
 	 * 200: Direct editing capabilities returned
 	 */
diff --git a/apps/files/lib/Controller/OpenLocalEditorController.php b/apps/files/lib/Controller/OpenLocalEditorController.php
index dae321ae437..b000304eef6 100644
--- a/apps/files/lib/Controller/OpenLocalEditorController.php
+++ b/apps/files/lib/Controller/OpenLocalEditorController.php
@@ -46,7 +46,7 @@ class OpenLocalEditorController extends OCSController {
 	 *
 	 * @param string $path Path of the file
 	 *
-	 * @return DataResponse<Http::STATUS_OK, array{userId: ?string, pathHash: string, expirationTime: int, token: string}, array{}>|DataResponse<Http::STATUS_INTERNAL_SERVER_ERROR, array<empty>, array{}>
+	 * @return DataResponse<Http::STATUS_OK, array{userId: ?string, pathHash: string, expirationTime: int, token: string}, array{}>|DataResponse<Http::STATUS_INTERNAL_SERVER_ERROR, list<empty>, array{}>
 	 *
 	 * 200: Local editor returned
 	 */
@@ -91,7 +91,7 @@ class OpenLocalEditorController extends OCSController {
 	 * @param string $path Path of the file
 	 * @param string $token Token of the local editor
 	 *
-	 * @return DataResponse<Http::STATUS_OK, array{userId: string, pathHash: string, expirationTime: int, token: string}, array{}>|DataResponse<Http::STATUS_NOT_FOUND, array<empty>, array{}>
+	 * @return DataResponse<Http::STATUS_OK, array{userId: string, pathHash: string, expirationTime: int, token: string}, array{}>|DataResponse<Http::STATUS_NOT_FOUND, list<empty>, array{}>
 	 *
 	 * 200: Local editor validated successfully
 	 * 404: Local editor not found
diff --git a/apps/files/lib/Controller/TemplateController.php b/apps/files/lib/Controller/TemplateController.php
index 551c9c54c4b..3321fb5f119 100644
--- a/apps/files/lib/Controller/TemplateController.php
+++ b/apps/files/lib/Controller/TemplateController.php
@@ -16,13 +16,16 @@ use OCP\AppFramework\OCS\OCSForbiddenException;
 use OCP\AppFramework\OCSController;
 use OCP\Files\GenericFileException;
 use OCP\Files\Template\ITemplateManager;
+use OCP\Files\Template\Template;
 use OCP\Files\Template\TemplateFileCreator;
 use OCP\IRequest;
 
 /**
  * @psalm-import-type FilesTemplateFile from ResponseDefinitions
  * @psalm-import-type FilesTemplateFileCreator from ResponseDefinitions
+ * @psalm-import-type FilesTemplateFileCreatorWithTemplates from ResponseDefinitions
  * @psalm-import-type FilesTemplateField from ResponseDefinitions
+ * @psalm-import-type FilesTemplate from ResponseDefinitions
  */
 class TemplateController extends OCSController {
 	public function __construct(
@@ -36,13 +39,17 @@ class TemplateController extends OCSController {
 	/**
 	 * List the available templates
 	 *
-	 * @return DataResponse<Http::STATUS_OK, array<FilesTemplateFileCreator>, array{}>
+	 * @return DataResponse<Http::STATUS_OK, list<FilesTemplateFileCreatorWithTemplates>, array{}>
 	 *
 	 * 200: Available templates returned
 	 */
 	#[NoAdminRequired]
 	public function list(): DataResponse {
-		return new DataResponse($this->templateManager->listTemplates());
+		/* Convert embedded Template instances to arrays to match return type */
+		return new DataResponse(array_map(static function (array $templateFileCreator) {
+			$templateFileCreator['templates'] = array_map(static fn (Template $template) => $template->jsonSerialize(), $templateFileCreator['templates']);
+			return $templateFileCreator;
+		}, $this->templateManager->listTemplates()));
 	}
 
 	/**
@@ -51,7 +58,7 @@ class TemplateController extends OCSController {
 	 * @param string $filePath Path of the file
 	 * @param string $templatePath Name of the template
 	 * @param string $templateType Type of the template
-	 * @param FilesTemplateField[] $templateFields Fields of the template
+	 * @param list<FilesTemplateField> $templateFields Fields of the template
 	 *
 	 * @return DataResponse<Http::STATUS_OK, FilesTemplateFile, array{}>
 	 * @throws OCSForbiddenException Creating template is not allowed
@@ -82,7 +89,7 @@ class TemplateController extends OCSController {
 	 * @param string $templatePath Path of the template directory
 	 * @param bool $copySystemTemplates Whether to copy the system templates to the template directory
 	 *
-	 * @return DataResponse<Http::STATUS_OK, array{template_path: string, templates: FilesTemplateFileCreator[]}, array{}>
+	 * @return DataResponse<Http::STATUS_OK, array{template_path: string, templates: list<FilesTemplateFileCreator>}, array{}>
 	 * @throws OCSForbiddenException Initializing the template directory is not allowed
 	 *
 	 * 200: Template directory initialized successfully
@@ -94,7 +101,7 @@ class TemplateController extends OCSController {
 			$templatePath = $this->templateManager->initializeTemplateDirectory($templatePath, null, $copySystemTemplates);
 			return new DataResponse([
 				'template_path' => $templatePath,
-				'templates' => array_map(fn (TemplateFileCreator $creator) => $creator->jsonSerialize(), $this->templateManager->listCreators()),
+				'templates' => array_values(array_map(fn (TemplateFileCreator $creator) => $creator->jsonSerialize(), $this->templateManager->listCreators())),
 			]);
 		} catch (\Exception $e) {
 			throw new OCSForbiddenException($e->getMessage());
diff --git a/apps/files/lib/Controller/TransferOwnershipController.php b/apps/files/lib/Controller/TransferOwnershipController.php
index 1420e57e987..51a25400efb 100644
--- a/apps/files/lib/Controller/TransferOwnershipController.php
+++ b/apps/files/lib/Controller/TransferOwnershipController.php
@@ -47,7 +47,7 @@ class TransferOwnershipController extends OCSController {
 	 * @param string $recipient Username of the recipient
 	 * @param string $path Path of the file
 	 *
-	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_BAD_REQUEST|Http::STATUS_FORBIDDEN, array<empty>, array{}>
+	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_BAD_REQUEST|Http::STATUS_FORBIDDEN, list<empty>, array{}>
 	 *
 	 * 200: Ownership transferred successfully
 	 * 400: Transferring ownership is not possible
@@ -101,7 +101,7 @@ class TransferOwnershipController extends OCSController {
 	 *
 	 * @param int $id ID of the ownership transfer
 	 *
-	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_FORBIDDEN|Http::STATUS_NOT_FOUND, array<empty>, array{}>
+	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_FORBIDDEN|Http::STATUS_NOT_FOUND, list<empty>, array{}>
 	 *
 	 * 200: Ownership transfer accepted successfully
 	 * 403: Accepting ownership transfer is not allowed
@@ -136,7 +136,7 @@ class TransferOwnershipController extends OCSController {
 	 *
 	 * @param int $id ID of the ownership transfer
 	 *
-	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_FORBIDDEN|Http::STATUS_NOT_FOUND, array<empty>, array{}>
+	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_FORBIDDEN|Http::STATUS_NOT_FOUND, list<empty>, array{}>
 	 *
 	 * 200: Ownership transfer rejected successfully
 	 * 403: Rejecting ownership transfer is not allowed
diff --git a/apps/files/lib/Helper.php b/apps/files/lib/Helper.php
index ce33bbb80a6..b66dc9a2056 100644
--- a/apps/files/lib/Helper.php
+++ b/apps/files/lib/Helper.php
@@ -192,37 +192,34 @@ class Helper {
 	/**
 	 * Populate the result set with file tags
 	 *
-	 * @param array $fileList
-	 * @param string $fileIdentifier identifier attribute name for values in $fileList
-	 * @param ITagManager $tagManager
-	 * @return array file list populated with tags
+	 * @psalm-template T of array{tags?: list<string>, file_source: int, ...array<string, mixed>}
+	 * @param list<T> $fileList
+	 * @return list<T> file list populated with tags
 	 */
-	public static function populateTags(array $fileList, $fileIdentifier, ITagManager $tagManager) {
-		$ids = [];
-		foreach ($fileList as $fileData) {
-			$ids[] = $fileData[$fileIdentifier];
-		}
+	public static function populateTags(array $fileList, ITagManager $tagManager) {
 		$tagger = $tagManager->load('files');
-		$tags = $tagger->getTagsForObjects($ids);
+		$tags = $tagger->getTagsForObjects(array_map(static fn (array $fileData) => $fileData['file_source'], $fileList));
 
 		if (!is_array($tags)) {
 			throw new \UnexpectedValueException('$tags must be an array');
 		}
 
 		// Set empty tag array
-		foreach ($fileList as $key => $fileData) {
-			$fileList[$key]['tags'] = [];
+		foreach ($fileList as &$fileData) {
+			$fileData['tags'] = [];
 		}
+		unset($fileData);
 
 		if (!empty($tags)) {
 			foreach ($tags as $fileId => $fileTags) {
-				foreach ($fileList as $key => $fileData) {
-					if ($fileId !== $fileData[$fileIdentifier]) {
+				foreach ($fileList as &$fileData) {
+					if ($fileId !== $fileData['file_source']) {
 						continue;
 					}
 
-					$fileList[$key]['tags'] = $fileTags;
+					$fileData['tags'] = $fileTags;
 				}
+				unset($fileData);
 			}
 		}
 
diff --git a/apps/files/lib/ResponseDefinitions.php b/apps/files/lib/ResponseDefinitions.php
index a05cbb75b21..c5d094e7bd8 100644
--- a/apps/files/lib/ResponseDefinitions.php
+++ b/apps/files/lib/ResponseDefinitions.php
@@ -22,21 +22,45 @@ namespace OCA\Files;
  *     hasPreview: bool,
  * }
  *
+ * @psalm-type FilesTemplateField = array{
+ *     index: string,
+ *     type: string,
+ *     alias: ?string,
+ *     tag: ?string,
+ *     id: ?int,
+ *     content?: string,
+ *     checked?: bool,
+ * }
+ *
+ * @psalm-type FilesTemplate = array{
+ *      templateType: string,
+ *      templateId: string,
+ *      basename: string,
+ *      etag: string,
+ *      fileid: int,
+ *      filename: string,
+ *      lastmod: int,
+ *      mime: string,
+ *      size: int|float,
+ *      type: string,
+ *      hasPreview: bool,
+ *      previewUrl: ?string,
+ *      fields: list<FilesTemplateField>,
+ *  }
+ *
  * @psalm-type FilesTemplateFileCreator = array{
  *     app: string,
  *     label: string,
  *     extension: string,
  *     iconClass: ?string,
  *     iconSvgInline: ?string,
- *     mimetypes: string[],
+ *     mimetypes: list<string>,
  *     ratio: ?float,
  *     actionLabel: string,
  * }
  *
- * @psalm-type FilesTemplateField = array{
- *     index: string,
- *     content: string,
- *     type: string,
+ * @psalm-type FilesTemplateFileCreatorWithTemplates = FilesTemplateFileCreator&array{
+ *     templates: list<FilesTemplate>,
  * }
  *
  * @psalm-type FilesFolderTree = list<array{