Add endpoint to set the description of a conversation

Only moderators and guest moderators of group and public conversations
can set their description.

Signed-off-by: Daniel Calviño Sánchez <danxuliu@gmail.com>

appinfo/routes.php

@@ -236,6 +236,15 @@ return [
 				'token' => '^[a-z0-9]{4,30}$',
 			],
 		],
+		[
+			'name' => 'Room#setDescription',
+			'url' => '/api/{apiVersion}/room/{token}/description',
+			'verb' => 'PUT',
+			'requirements' => [
+				'apiVersion' => 'v3',
+				'token' => '^[a-z0-9]{4,30}$',
+			],
+		],
 		[
 			'name' => 'Room#setReadOnly',
 			'url' => '/api/{apiVersion}/room/{token}/read-only',

lib/Controller/RoomController.php

@@ -997,6 +997,27 @@ class RoomController extends AEnvironmentAwareController {
 		return new DataResponse();
 	}
 
+	/**
+	 * @PublicPage
+	 * @RequireModeratorParticipant
+	 *
+	 * @param string $description
+	 * @return DataResponse
+	 */
+	public function setDescription(string $description): DataResponse {
+		if ($this->room->getType() === Room::ONE_TO_ONE_CALL) {
+			return new DataResponse([], Http::STATUS_BAD_REQUEST);
+		}
+
+		try {
+			$this->room->setDescription($description);
+		} catch (\LengthException $exception) {
+			return new DataResponse([], Http::STATUS_BAD_REQUEST);
+		}
+
+		return new DataResponse();
+	}
+
 	/**
 	 * @PublicPage
 	 * @RequireModeratorParticipant

lib/Room.php

@@ -74,6 +74,8 @@ class Room {
 	public const EVENT_AFTER_ROOM_DELETE = self::class . '::postDeleteRoom';
 	public const EVENT_BEFORE_NAME_SET = self::class . '::preSetName';
 	public const EVENT_AFTER_NAME_SET = self::class . '::postSetName';
+	public const EVENT_BEFORE_DESCRIPTION_SET = self::class . '::preSetDescription';
+	public const EVENT_AFTER_DESCRIPTION_SET = self::class . '::postSetDescription';
 	public const EVENT_BEFORE_PASSWORD_SET = self::class . '::preSetPassword';
 	public const EVENT_AFTER_PASSWORD_SET = self::class . '::postSetPassword';
 	public const EVENT_BEFORE_TYPE_SET = self::class . '::preSetType';
@@ -550,6 +552,38 @@ class Room {
 		return true;
 	}
 
+	/**
+	 * @param string $description
+	 * @return bool True when the change was valid, false otherwise
+	 * @throws \LengthException when the given description is too long
+	 */
+	public function setDescription(string $description): bool {
+		$description = trim($description);
+
+		if (mb_strlen($description) > self::DESCRIPTION_MAXIMUM_LENGTH) {
+			throw new \LengthException('Conversation description is limited to ' . self::DESCRIPTION_MAXIMUM_LENGTH . ' characters');
+		}
+
+		$oldDescription = $this->getDescription();
+		if ($description === $oldDescription) {
+			return false;
+		}
+
+		$event = new ModifyRoomEvent($this, 'description', $description, $oldDescription);
+		$this->dispatcher->dispatch(self::EVENT_BEFORE_DESCRIPTION_SET, $event);
+
+		$query = $this->db->getQueryBuilder();
+		$query->update('talk_rooms')
+			->set('description', $query->createNamedParameter($description))
+			->where($query->expr()->eq('id', $query->createNamedParameter($this->getId(), IQueryBuilder::PARAM_INT)));
+		$query->execute();
+		$this->description = $description;
+
+		$this->dispatcher->dispatch(self::EVENT_AFTER_DESCRIPTION_SET, $event);
+
+		return true;
+	}
+
 	/**
 	 * @param string $password Currently it is only allowed to have a password for Room::PUBLIC_CALL
 	 * @return bool True when the change was valid, false otherwise