fix(openapi): Improve empty array cases

lib/Capabilities.php

@@ -272,18 +272,18 @@ public function getCapabilities(): array {
 			$capabilities['config']['signaling']['hello-v2-token-key'] = $pubKey;
 		}
 
-		/** @var ?string[] $predefinedBackgrounds */
+		/** @var ?list<string> $predefinedBackgrounds */
 		$predefinedBackgrounds = null;
 		$cachedPredefinedBackgrounds = $this->talkCache->get('predefined_backgrounds');
 		if ($cachedPredefinedBackgrounds !== null) {
 			// Try using cached value
-			/** @var string[]|null $predefinedBackgrounds */
+			/** @var list<string>|null $predefinedBackgrounds */
 			$predefinedBackgrounds = json_decode($cachedPredefinedBackgrounds, true);
 		}
 
 		if (!is_array($predefinedBackgrounds)) {
 			// Cache was empty or invalid, regenerate
-			/** @var string[] $predefinedBackgrounds */
+			/** @var list<string> $predefinedBackgrounds */
 			$predefinedBackgrounds = [];
 			if (file_exists(__DIR__ . '/../img/backgrounds')) {
 				$directoryIterator = new \DirectoryIterator(__DIR__ . '/../img/backgrounds');

lib/Controller/BanController.php

@@ -77,7 +77,7 @@ public function banActor(string $actorType, string $actorId, string $internalNot
 	 *
 	 * Required capability: `ban-v1`
 	 *
-	 * @return DataResponse<Http::STATUS_OK, TalkBan[], array{}>
+	 * @return DataResponse<Http::STATUS_OK, list<TalkBan>, array{}>
 	 *
 	 * 200: List all bans
 	 */
@@ -95,14 +95,14 @@ public function listBans(): DataResponse {
 	 * Required capability: `ban-v1`
 	 *
 	 * @param int $banId ID of the ban to be removed
-	 * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
+	 * @return DataResponse<Http::STATUS_OK, null, array{}>
 	 *
 	 * 200: Unban successfully or not found
 	 */
 	#[PublicPage]
 	#[RequireModeratorParticipant]
 	public function unbanActor(int $banId): DataResponse {
 		$this->banService->findAndDeleteBanByIdForRoom($banId, $this->room->getId());
-		return new DataResponse([], Http::STATUS_OK);
+		return new DataResponse(null, Http::STATUS_OK);
 	}
 }

lib/Controller/BotController.php

@@ -120,7 +120,7 @@ protected function getBotFromHeaders(string $token, string $message): Bot {
 	 * @param string $referenceId For the message to be able to later identify it again
 	 * @param int $replyTo Parent id which this message is a reply to
 	 * @param bool $silent If sent silent the chat message will not create any notifications
-	 * @return DataResponse<Http::STATUS_CREATED|Http::STATUS_BAD_REQUEST|Http::STATUS_UNAUTHORIZED|Http::STATUS_REQUEST_ENTITY_TOO_LARGE, array<empty>, array{}>
+	 * @return DataResponse<Http::STATUS_CREATED|Http::STATUS_BAD_REQUEST|Http::STATUS_UNAUTHORIZED|Http::STATUS_REQUEST_ENTITY_TOO_LARGE, null, array{}>
 	 *
 	 * 201: Message sent successfully
 	 * 400: When the replyTo is invalid or message is empty
@@ -133,15 +133,15 @@ protected function getBotFromHeaders(string $token, string $message): Bot {
 	#[PublicPage]
 	public function sendMessage(string $token, string $message, string $referenceId = '', int $replyTo = 0, bool $silent = false): DataResponse {
 		if (trim($message) === '') {
-			return new DataResponse([], Http::STATUS_BAD_REQUEST);
+			return new DataResponse(null, Http::STATUS_BAD_REQUEST);
 		}
 
 		try {
 			$bot = $this->getBotFromHeaders($token, $message);
 		} catch (\InvalidArgumentException $e) {
 			/** @var Http::STATUS_BAD_REQUEST|Http::STATUS_UNAUTHORIZED $status */
 			$status = $e->getCode();
-			$response = new DataResponse([], $status);
+			$response = new DataResponse(null, $status);
 			if ($e->getCode() === Http::STATUS_UNAUTHORIZED) {
 				$response->throttle(['action' => 'bot']);
 			}
@@ -159,7 +159,7 @@ public function sendMessage(string $token, string $message, string $referenceId
 				$parent = $this->chatManager->getParentComment($room, (string)$replyTo);
 			} catch (NotFoundException $e) {
 				// Someone is trying to reply cross-rooms or to a non-existing message
-				return new DataResponse([], Http::STATUS_BAD_REQUEST);
+				return new DataResponse(null, Http::STATUS_BAD_REQUEST);
 			}
 		}
 
@@ -169,12 +169,12 @@ public function sendMessage(string $token, string $message, string $referenceId
 		try {
 			$this->chatManager->sendMessage($room, $this->participant, $actorType, $actorId, $message, $creationDateTime, $parent, $referenceId, $silent, rateLimitGuestMentions: false);
 		} catch (MessageTooLongException) {
-			return new DataResponse([], Http::STATUS_REQUEST_ENTITY_TOO_LARGE);
+			return new DataResponse(null, Http::STATUS_REQUEST_ENTITY_TOO_LARGE);
 		} catch (\Exception) {
-			return new DataResponse([], Http::STATUS_BAD_REQUEST);
+			return new DataResponse(null, Http::STATUS_BAD_REQUEST);
 		}
 
-		return new DataResponse([], Http::STATUS_CREATED);
+		return new DataResponse(null, Http::STATUS_CREATED);
 	}
 
 	/**
@@ -183,7 +183,7 @@ public function sendMessage(string $token, string $message, string $referenceId
 	 * @param string $token Conversation token
 	 * @param int $messageId ID of the message
 	 * @param string $reaction Reaction to add
-	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_CREATED|Http::STATUS_BAD_REQUEST|Http::STATUS_UNAUTHORIZED|Http::STATUS_NOT_FOUND, array<empty>, array{}>
+	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_CREATED|Http::STATUS_BAD_REQUEST|Http::STATUS_UNAUTHORIZED|Http::STATUS_NOT_FOUND, null, array{}>
 	 *
 	 * 200: Reaction already exists
 	 * 201: Reacted successfully
@@ -200,7 +200,7 @@ public function react(string $token, int $messageId, string $reaction): DataResp
 		} catch (\InvalidArgumentException $e) {
 			/** @var Http::STATUS_BAD_REQUEST|Http::STATUS_UNAUTHORIZED $status */
 			$status = $e->getCode();
-			$response = new DataResponse([], $status);
+			$response = new DataResponse(null, $status);
 			if ($e->getCode() === Http::STATUS_UNAUTHORIZED) {
 				$response->throttle(['action' => 'bot']);
 			}
@@ -221,14 +221,14 @@ public function react(string $token, int $messageId, string $reaction): DataResp
 				$reaction
 			);
 		} catch (NotFoundException) {
-			return new DataResponse([], Http::STATUS_NOT_FOUND);
+			return new DataResponse(null, Http::STATUS_NOT_FOUND);
 		} catch (ReactionAlreadyExistsException) {
-			return new DataResponse([], Http::STATUS_OK);
+			return new DataResponse(null, Http::STATUS_OK);
 		} catch (ReactionNotSupportedException|ReactionOutOfContextException|\Exception) {
-			return new DataResponse([], Http::STATUS_BAD_REQUEST);
+			return new DataResponse(null, Http::STATUS_BAD_REQUEST);
 		}
 
-		return new DataResponse([], Http::STATUS_CREATED);
+		return new DataResponse(null, Http::STATUS_CREATED);
 	}
 
 	/**
@@ -237,7 +237,7 @@ public function react(string $token, int $messageId, string $reaction): DataResp
 	 * @param string $token Conversation token
 	 * @param int $messageId ID of the message
 	 * @param string $reaction Reaction to delete
-	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_BAD_REQUEST|Http::STATUS_NOT_FOUND|Http::STATUS_UNAUTHORIZED, array<empty>, array{}>
+	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_BAD_REQUEST|Http::STATUS_NOT_FOUND|Http::STATUS_UNAUTHORIZED, null, array{}>
 	 *
 	 * 200: Reaction deleted successfully
 	 * 400: Reacting is not possible
@@ -253,7 +253,7 @@ public function deleteReaction(string $token, int $messageId, string $reaction):
 		} catch (\InvalidArgumentException $e) {
 			/** @var Http::STATUS_BAD_REQUEST|Http::STATUS_UNAUTHORIZED $status */
 			$status = $e->getCode();
-			$response = new DataResponse([], $status);
+			$response = new DataResponse(null, $status);
 			if ($e->getCode() === Http::STATUS_UNAUTHORIZED) {
 				$response->throttle(['action' => 'bot']);
 			}
@@ -274,18 +274,18 @@ public function deleteReaction(string $token, int $messageId, string $reaction):
 				$reaction
 			);
 		} catch (ReactionNotSupportedException|ReactionOutOfContextException|NotFoundException) {
-			return new DataResponse([], Http::STATUS_NOT_FOUND);
+			return new DataResponse(null, Http::STATUS_NOT_FOUND);
 		} catch (\Exception) {
-			return new DataResponse([], Http::STATUS_BAD_REQUEST);
+			return new DataResponse(null, Http::STATUS_BAD_REQUEST);
 		}
 
-		return new DataResponse([], Http::STATUS_OK);
+		return new DataResponse(null, Http::STATUS_OK);
 	}
 
 	/**
 	 * List admin bots
 	 *
-	 * @return DataResponse<Http::STATUS_OK, TalkBotWithDetails[], array{}>
+	 * @return DataResponse<Http::STATUS_OK, list<TalkBotWithDetails>, array{}>
 	 *
 	 * 200: Bot list returned
 	 */
@@ -305,7 +305,7 @@ public function adminListBots(): DataResponse {
 	/**
 	 * List bots
 	 *
-	 * @return DataResponse<Http::STATUS_OK, TalkBot[], array{}>
+	 * @return DataResponse<Http::STATUS_OK, list<TalkBot>, array{}>
 	 *
 	 * 200: Bot list returned
 	 */

lib/Controller/BreakoutRoomController.php

@@ -45,7 +45,7 @@ public function __construct(
 	 * @psalm-param BreakoutRoom::MODE_* $mode
 	 * @param int<1, 20> $amount Number of breakout rooms - Constants {@see BreakoutRoom::MINIMUM_ROOM_AMOUNT} and {@see BreakoutRoom::MAXIMUM_ROOM_AMOUNT}
 	 * @param string $attendeeMap Mapping of the attendees to breakout rooms
-	 * @return DataResponse<Http::STATUS_OK, TalkRoom[], array{}>|DataResponse<Http::STATUS_BAD_REQUEST, array{error: string}, array{}>
+	 * @return DataResponse<Http::STATUS_OK, list<TalkRoom>, array{}>|DataResponse<Http::STATUS_BAD_REQUEST, array{error: string}, array{}>
 	 *
 	 * 200: Breakout rooms configured successfully
 	 * 400: Configuring breakout rooms errored
@@ -87,7 +87,7 @@ public function removeBreakoutRooms(): DataResponse {
 	 * Broadcast a chat message to all breakout rooms
 	 *
 	 * @param string $message Message to broadcast
-	 * @return DataResponse<Http::STATUS_CREATED, TalkRoom[], array{}>|DataResponse<Http::STATUS_BAD_REQUEST|Http::STATUS_REQUEST_ENTITY_TOO_LARGE, array{error: string}, array{}>
+	 * @return DataResponse<Http::STATUS_CREATED, list<TalkRoom>, array{}>|DataResponse<Http::STATUS_BAD_REQUEST|Http::STATUS_REQUEST_ENTITY_TOO_LARGE, array{error: string}, array{}>
 	 *
 	 * 201: Chat message broadcasted successfully
 	 * 400: Broadcasting chat message is not possible
@@ -111,7 +111,7 @@ public function broadcastChatMessage(string $message): DataResponse {
 	 * Apply an attendee map to the breakout rooms
 	 *
 	 * @param string $attendeeMap JSON encoded mapping of the attendees to breakout rooms `array<int, int>`
-	 * @return DataResponse<Http::STATUS_OK, TalkRoom[], array{}>|DataResponse<Http::STATUS_BAD_REQUEST, array{error: string}, array{}>
+	 * @return DataResponse<Http::STATUS_OK, list<TalkRoom>, array{}>|DataResponse<Http::STATUS_BAD_REQUEST, array{error: string}, array{}>
 	 *
 	 * 200: Attendee map applied successfully
 	 * 400: Applying attendee map is not possible
@@ -181,7 +181,7 @@ public function resetRequestForAssistance(): DataResponse {
 	/**
 	 * Start the breakout rooms
 	 *
-	 * @return DataResponse<Http::STATUS_OK, TalkRoom[], array{}>|DataResponse<Http::STATUS_BAD_REQUEST, array{error: string}, array{}>
+	 * @return DataResponse<Http::STATUS_OK, list<TalkRoom>, array{}>|DataResponse<Http::STATUS_BAD_REQUEST, array{error: string}, array{}>
 	 *
 	 * 200: Breakout rooms started successfully
 	 * 400: Starting breakout rooms is not possible
@@ -202,7 +202,7 @@ public function startBreakoutRooms(): DataResponse {
 	/**
 	 * Stop the breakout rooms
 	 *
-	 * @return DataResponse<Http::STATUS_OK, TalkRoom[], array{}>|DataResponse<Http::STATUS_BAD_REQUEST, array{error: string}, array{}>
+	 * @return DataResponse<Http::STATUS_OK, list<TalkRoom>, array{}>|DataResponse<Http::STATUS_BAD_REQUEST, array{error: string}, array{}>
 	 *
 	 * 200: Breakout rooms stopped successfully
 	 * 400: Stopping breakout rooms is not possible
@@ -247,7 +247,7 @@ public function switchBreakoutRoom(string $target): DataResponse {
 	}
 
 	/**
-	 * @return TalkRoom[]
+	 * @return list<TalkRoom>
 	 */
 	protected function formatMultipleRooms(array $rooms): array {
 		$return = [];