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

nextcloud · Nov 6, 2024 · d53fde8 · d53fde8
2 parents 8fab143 + 77114fb
commit d53fde8
Show file tree

Hide file tree

Showing 109 changed files with 698 additions and 448 deletions.
diff --git a/apps/cloud_federation_api/lib/Capabilities.php b/apps/cloud_federation_api/lib/Capabilities.php
@@ -31,11 +31,11 @@ public function __construct(
 	 *         enabled: bool,
 	 *         apiVersion: string,
 	 *         endPoint: string,
-	 *         resourceTypes: array{
+	 *         resourceTypes: list<array{
 	 *             name: string,
-	 *             shareTypes: string[],
+	 *             shareTypes: list<string>,
 	 *             protocols: array<string, string>
-	 *           }[],
+	 *           }>,
 	 *       },
 	 * }
 	 * @throws OCMArgumentException

diff --git a/apps/cloud_federation_api/lib/Controller/RequestHandlerController.php b/apps/cloud_federation_api/lib/Controller/RequestHandlerController.php
@@ -67,7 +67,7 @@ public function __construct(
 	 * @param string|null $ownerDisplayName Display name of the user who shared the item
 	 * @param string|null $sharedBy Provider specific UID of the user who shared the resource
 	 * @param string|null $sharedByDisplayName Display name of the user who shared the resource
-	 * @param array{name: string[], options: array<string, mixed>} $protocol e,.g. ['name' => 'webdav', 'options' => ['username' => 'john', 'permissions' => 31]]
+	 * @param array{name: list<string>, options: array<string, mixed>} $protocol e,.g. ['name' => 'webdav', 'options' => ['username' => 'john', 'permissions' => 31]]
 	 * @param string $shareType 'group' or 'user' share
 	 * @param string $resourceType 'file', 'calendar',...
 	 *

diff --git a/apps/cloud_federation_api/lib/ResponseDefinitions.php b/apps/cloud_federation_api/lib/ResponseDefinitions.php
@@ -20,10 +20,10 @@
  * }
  *
  * @psalm-type CloudFederationAPIValidationError = CloudFederationAPIError&array{
- *     validationErrors: array{
+ *     validationErrors: list<array{
  *          name: string,
  *          message: string|null,
- *     }[],
+ *     }>,
  * }
  */
 class ResponseDefinitions {

diff --git a/apps/dashboard/lib/Controller/DashboardApiController.php b/apps/dashboard/lib/Controller/DashboardApiController.php
@@ -74,8 +74,8 @@ static function (IWidget $widget) use ($widgetIds) {
 	 * @param array<string, string> $sinceIds Array indexed by widget Ids, contains date/id from which we want the new items
 	 * @param int $limit Limit number of result items per widget
 	 * @psalm-param int<1, 30> $limit
-	 * @param string[] $widgets Limit results to specific widgets
-	 * @return DataResponse<Http::STATUS_OK, array<string, DashboardWidgetItem[]>, array{}>
+	 * @param list<string> $widgets Limit results to specific widgets
+	 * @return DataResponse<Http::STATUS_OK, array<string, list<DashboardWidgetItem>>, array{}>
 	 *
 	 * 200: Widget items returned
 	 */
@@ -102,7 +102,7 @@ public function getWidgetItems(array $sinceIds = [], int $limit = 7, array $widg
 	 * @param array<string, string> $sinceIds Array indexed by widget Ids, contains date/id from which we want the new items
 	 * @param int $limit Limit number of result items per widget, not more than 30 are allowed
 	 * @psalm-param int<1, 30> $limit
-	 * @param string[] $widgets Limit results to specific widgets
+	 * @param list<string> $widgets Limit results to specific widgets
 	 * @return DataResponse<Http::STATUS_OK, array<string, DashboardWidgetItems>, array{}>
 	 *
 	 * 200: Widget items returned

diff --git a/apps/dashboard/lib/ResponseDefinitions.php b/apps/dashboard/lib/ResponseDefinitions.php
@@ -18,13 +18,13 @@
  *     icon_url: string,
  *     widget_url: ?string,
  *     item_icons_round: bool,
- *     item_api_versions: int[],
+ *     item_api_versions: list<int>,
  *     reload_interval: int,
- *     buttons?: array{
+ *     buttons?: list<array{
  *         type: string,
  *         text: string,
  *         link: string,
- *     }[],
+ *     }>,
  * }
  *
  * @psalm-type DashboardWidgetItem = array{
@@ -37,7 +37,7 @@
  * }
  *
  * @psalm-type DashboardWidgetItems = array{
- *     items: DashboardWidgetItem[],
+ *     items: list<DashboardWidgetItem>,
  *     emptyContentMessage: string,
  *     halfEmptyContentMessage: string,
  *  }

diff --git a/apps/dav/lib/Controller/UpcomingEventsController.php b/apps/dav/lib/Controller/UpcomingEventsController.php
@@ -35,7 +35,7 @@ public function __construct(
 	 * Get information about upcoming events
 	 *
 	 * @param string|null $location location/URL to filter by
-	 * @return DataResponse<Http::STATUS_OK, array{events: DAVUpcomingEvent[]}, array{}>|DataResponse<Http::STATUS_UNAUTHORIZED, null, array{}>
+	 * @return DataResponse<Http::STATUS_OK, array{events: list<DAVUpcomingEvent>}, array{}>|DataResponse<Http::STATUS_UNAUTHORIZED, null, array{}>
 	 *
 	 * 200: Upcoming events
 	 * 401: When not authenticated
@@ -47,10 +47,10 @@ public function getEvents(?string $location = null): DataResponse {
 		}
 
 		return new DataResponse([
-			'events' => array_map(fn (UpcomingEvent $e) => $e->jsonSerialize(), $this->service->getEvents(
+			'events' => array_values(array_map(fn (UpcomingEvent $e) => $e->jsonSerialize(), $this->service->getEvents(
 				$this->userId,
 				$location,
-			)),
+			))),
 		]);
 	}
 

diff --git a/apps/federatedfilesharing/lib/Controller/RequestHandlerController.php b/apps/federatedfilesharing/lib/Controller/RequestHandlerController.php
@@ -72,7 +72,7 @@ public function __construct(
 	 * @param int|null $remoteId ID of the remote
 	 * @param string|null $sharedByFederatedId Federated ID of the sender
 	 * @param string|null $ownerFederatedId Federated ID of the receiver
-	 * @return Http\DataResponse<Http::STATUS_OK, array<empty>, array{}>
+	 * @return Http\DataResponse<Http::STATUS_OK, list<empty>, array{}>
 	 * @throws OCSException
 	 *
 	 * 200: Share created successfully
@@ -186,7 +186,7 @@ public function reShare(int $id, ?string $token = null, ?string $shareWith = nul
 	 *
 	 * @param int $id ID of the remote share
 	 * @param string|null $token Shared secret between servers
-	 * @return Http\DataResponse<Http::STATUS_OK, array<empty>, array{}>
+	 * @return Http\DataResponse<Http::STATUS_OK, list<empty>, array{}>
 	 * @throws OCSException
 	 * @throws ShareNotFound
 	 * @throws HintException
@@ -221,7 +221,7 @@ public function acceptShare(int $id, ?string $token = null) {
 	 *
 	 * @param int $id ID of the remote share
 	 * @param string|null $token Shared secret between servers
-	 * @return Http\DataResponse<Http::STATUS_OK, array<empty>, array{}>
+	 * @return Http\DataResponse<Http::STATUS_OK, list<empty>, array{}>
 	 * @throws OCSException
 	 *
 	 * 200: Share declined successfully
@@ -254,7 +254,7 @@ public function declineShare(int $id, ?string $token = null) {
 	 *
 	 * @param int $id ID of the share
 	 * @param string|null $token Shared secret between servers
-	 * @return Http\DataResponse<Http::STATUS_OK, array<empty>, array{}>
+	 * @return Http\DataResponse<Http::STATUS_OK, list<empty>, array{}>
 	 * @throws OCSException
 	 *
 	 * 200: Share unshared successfully
@@ -290,7 +290,7 @@ private function cleanupRemote($remote) {
 	 *
 	 * @param int $id ID of the share
 	 * @param string|null $token Shared secret between servers
-	 * @return Http\DataResponse<Http::STATUS_OK, array<empty>, array{}>
+	 * @return Http\DataResponse<Http::STATUS_OK, list<empty>, array{}>
 	 * @throws OCSBadRequestException Revoking the share is not possible
 	 *
 	 * 200: Share revoked successfully
@@ -332,7 +332,7 @@ private function isS2SEnabled($incoming = false) {
 	 * @param int $id ID of the share
 	 * @param string|null $token Shared secret between servers
 	 * @param int|null $permissions New permissions
-	 * @return Http\DataResponse<Http::STATUS_OK, array<empty>, array{}>
+	 * @return Http\DataResponse<Http::STATUS_OK, list<empty>, array{}>
 	 * @throws OCSBadRequestException Updating permissions is not possible
 	 *
 	 * 200: Permissions updated successfully

diff --git a/apps/federation/lib/Controller/OCSAuthAPIController.php b/apps/federation/lib/Controller/OCSAuthAPIController.php
@@ -52,7 +52,7 @@ public function __construct(
 	 *
 	 * @param string $url URL of the server
 	 * @param string $token Token of the server
-	 * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
+	 * @return DataResponse<Http::STATUS_OK, list<empty>, array{}>
 	 * @throws OCSForbiddenException Requesting shared secret is not allowed
 	 *
 	 * 200: Shared secret requested successfully
@@ -87,7 +87,7 @@ public function getSharedSecretLegacy(string $url, string $token): DataResponse
 	 *
 	 * @param string $url URL of the server
 	 * @param string $token Token of the server
-	 * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
+	 * @return DataResponse<Http::STATUS_OK, list<empty>, array{}>
 	 * @throws OCSForbiddenException Requesting shared secret is not allowed
 	 *
 	 * 200: Shared secret requested successfully

diff --git a/apps/files/lib/Capabilities.php b/apps/files/lib/Capabilities.php
@@ -21,7 +21,7 @@ public function __construct(
 	/**
 	 * 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
@@ -36,7 +36,7 @@ public function __construct(
 
 	/**
 	 * 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
@@ -46,7 +46,7 @@ public function __construct(
 	 *
 	 * @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 @@ public function create(string $path): DataResponse {
 	 * @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
@@ -16,13 +16,16 @@
 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 @@ public function __construct(
 	/**
 	 * 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 @@ public function list(): DataResponse {
 	 * @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 @@ public function create(
 	 * @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 @@ public function path(string $templatePath = '', bool $copySystemTemplates = fals
 			$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
@@ -47,7 +47,7 @@ public function __construct(
 	 * @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 @@ public function transfer(string $recipient, string $path): DataResponse {
 	 *
 	 * @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 @@ public function accept(int $id): DataResponse {
 	 *
 	 * @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
@@ -192,37 +192,34 @@ public static function getFiles($dir, $sortAttribute = 'name', $sortDescending =
 	/**
 	 * 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);
 			}
 		}