diff options
Diffstat (limited to 'lib/public/Comments')
-rw-r--r-- | lib/public/Comments/CommentsEntityEvent.php | 41 | ||||
-rw-r--r-- | lib/public/Comments/CommentsEvent.php | 29 | ||||
-rw-r--r-- | lib/public/Comments/IComment.php | 88 | ||||
-rw-r--r-- | lib/public/Comments/ICommentsEventHandler.php | 26 | ||||
-rw-r--r-- | lib/public/Comments/ICommentsManager.php | 86 | ||||
-rw-r--r-- | lib/public/Comments/ICommentsManagerFactory.php | 26 | ||||
-rw-r--r-- | lib/public/Comments/IllegalIDChangeException.php | 25 | ||||
-rw-r--r-- | lib/public/Comments/MessageTooLongException.php | 24 | ||||
-rw-r--r-- | lib/public/Comments/NotFoundException.php | 25 |
9 files changed, 131 insertions, 239 deletions
diff --git a/lib/public/Comments/CommentsEntityEvent.php b/lib/public/Comments/CommentsEntityEvent.php index e4b4c78f03c..39568151b61 100644 --- a/lib/public/Comments/CommentsEntityEvent.php +++ b/lib/public/Comments/CommentsEntityEvent.php @@ -1,25 +1,9 @@ <?php + /** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Arthur Schiwon <blizzz@arthur-schiwon.de> - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author Joas Schilling <coding@schilljs.com> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Affero General Public License for more details. - * - * You should have received a copy of the GNU Affero General Public License, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * + * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-FileCopyrightText: 2016 ownCloud, Inc. + * SPDX-License-Identifier: AGPL-3.0-only */ namespace OCP\Comments; @@ -29,35 +13,34 @@ use OCP\EventDispatcher\Event; * Class CommentsEntityEvent * * @since 9.1.0 + * @since 28.0.0 Dispatched as a typed event */ class CommentsEntityEvent extends Event { /** - * @deprecated 22.0.0 + * @since 9.1.0 + * @deprecated 22.0.0 - Listen to the typed event instead. */ public const EVENT_ENTITY = 'OCP\Comments\ICommentsManager::registerEntity'; - /** @var string */ - protected $event; /** @var \Closure[] */ protected $collections; /** * DispatcherEvent constructor. * - * @param string $event * @since 9.1.0 */ - public function __construct($event) { - $this->event = $event; + public function __construct() { + parent::__construct(); $this->collections = []; } /** * @param string $name * @param \Closure $entityExistsFunction The closure should take one - * argument, which is the id of the entity, that comments - * should be handled for. The return should then be bool, - * depending on whether comments are allowed (true) or not. + * argument, which is the id of the entity, that comments + * should be handled for. The return should then be bool, + * depending on whether comments are allowed (true) or not. * @throws \OutOfBoundsException when the entity name is already taken * @since 9.1.0 */ diff --git a/lib/public/Comments/CommentsEvent.php b/lib/public/Comments/CommentsEvent.php index 244df0243f7..04d592d4f1e 100644 --- a/lib/public/Comments/CommentsEvent.php +++ b/lib/public/Comments/CommentsEvent.php @@ -1,25 +1,9 @@ <?php + /** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Arthur Schiwon <blizzz@arthur-schiwon.de> - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author Joas Schilling <coding@schilljs.com> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Affero General Public License for more details. - * - * You should have received a copy of the GNU Affero General Public License, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * + * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-FileCopyrightText: 2016 ownCloud, Inc. + * SPDX-License-Identifier: AGPL-3.0-only */ namespace OCP\Comments; @@ -31,23 +15,26 @@ use OCP\EventDispatcher\Event; * @since 9.0.0 */ class CommentsEvent extends Event { - /** + * @since 11.0.0 * @deprecated 22.0.0 */ public const EVENT_ADD = 'OCP\Comments\ICommentsManager::addComment'; /** + * @since 11.0.0 * @deprecated 22.0.0 */ public const EVENT_PRE_UPDATE = 'OCP\Comments\ICommentsManager::preUpdateComment'; /** + * @since 11.0.0 * @deprecated 22.0.0 */ public const EVENT_UPDATE = 'OCP\Comments\ICommentsManager::updateComment'; /** + * @since 11.0.0 * @deprecated 22.0.0 */ public const EVENT_DELETE = 'OCP\Comments\ICommentsManager::deleteComment'; diff --git a/lib/public/Comments/IComment.php b/lib/public/Comments/IComment.php index 8465eaf49f4..cdfcf188761 100644 --- a/lib/public/Comments/IComment.php +++ b/lib/public/Comments/IComment.php @@ -1,27 +1,9 @@ <?php + /** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Arthur Schiwon <blizzz@arthur-schiwon.de> - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author Joas Schilling <coding@schilljs.com> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * @author Thomas Müller <thomas.mueller@tmit.eu> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Affero General Public License for more details. - * - * You should have received a copy of the GNU Affero General Public License, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * + * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-FileCopyrightText: 2016 ownCloud, Inc. + * SPDX-License-Identifier: AGPL-3.0-only */ namespace OCP\Comments; @@ -33,6 +15,9 @@ namespace OCP\Comments; * @since 9.0.0 */ interface IComment { + /** + * @since 9.0.0 + */ public const MAX_MESSAGE_LENGTH = 1000; /** @@ -139,21 +124,12 @@ interface IComment { * returns an array containing mentions that are included in the comment * * @return array each mention provides a 'type' and an 'id', see example below + * @psalm-return list<array{type: 'guest'|'email'|'federated_group'|'group'|'federated_team'|'team'|'federated_user'|'user', id: non-empty-lowercase-string}> + * @since 30.0.2 Type 'email' is supported + * @since 29.0.0 Types 'federated_group', 'federated_team', 'team' and 'federated_user' are supported + * @since 23.0.0 Type 'group' is supported + * @since 17.0.0 Type 'guest' is supported * @since 11.0.0 - * - * The return array looks like: - * [ - * [ - * 'type' => 'user', - * 'id' => 'citizen4' - * ], - * [ - * 'type' => 'group', - * 'id' => 'media' - * ], - * … - * ] - * */ public function getMentions(); @@ -230,11 +206,11 @@ interface IComment { /** * sets the date of the most recent child * - * @param \DateTime $dateTime + * @param \DateTime|null $dateTime * @return IComment * @since 9.0.0 */ - public function setLatestChildDateTime(\DateTime $dateTime); + public function setLatestChildDateTime(?\DateTime $dateTime = null); /** * returns the object type the comment is attached to @@ -280,6 +256,25 @@ interface IComment { public function setReferenceId(?string $referenceId): IComment; /** + * Returns the metadata of the comment + * + * @return array|null + * @since 29.0.0 + */ + public function getMetaData(): ?array; + + /** + * Sets (overwrites) the metadata of the comment + * Data as a json encoded array + * + * @param array|null $metaData + * @return IComment + * @throws \JsonException When the metadata can not be converted to a json encoded string + * @since 29.0.0 + */ + public function setMetaData(?array $metaData): IComment; + + /** * Returns the reactions array if exists * * The keys is the emoji of reaction and the value is the total. @@ -299,4 +294,21 @@ interface IComment { * @since 24.0.0 */ public function setReactions(?array $reactions): IComment; + + /** + * Set message expire date + * + * @param \DateTime|null $dateTime + * @return IComment + * @since 25.0.0 + */ + public function setExpireDate(?\DateTime $dateTime): IComment; + + /** + * Get message expire date + * + * @return ?\DateTime + * @since 25.0.0 + */ + public function getExpireDate(): ?\DateTime; } diff --git a/lib/public/Comments/ICommentsEventHandler.php b/lib/public/Comments/ICommentsEventHandler.php index 4e19a3aaadc..148ead2c367 100644 --- a/lib/public/Comments/ICommentsEventHandler.php +++ b/lib/public/Comments/ICommentsEventHandler.php @@ -1,25 +1,8 @@ <?php + /** - * @copyright Copyright (c) 2016 Arthur Schiwon <blizzz@arthur-schiwon.de> - * - * @author Arthur Schiwon <blizzz@arthur-schiwon.de> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @license GNU AGPL version 3 or any later version - * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License as - * published by the Free Software Foundation, either version 3 of the - * License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Affero General Public License for more details. - * - * You should have received a copy of the GNU Affero General Public License - * along with this program. If not, see <http://www.gnu.org/licenses/>. - * + * SPDX-FileCopyrightText: 2016 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ namespace OCP\Comments; @@ -27,12 +10,13 @@ namespace OCP\Comments; * Interface ICommentsEventHandler * * @since 11.0.0 + * @deprecated 30.0.0 Register a listener for the CommentsEvent through the IEventDispatcher */ interface ICommentsEventHandler { - /** * @param CommentsEvent $event * @since 11.0.0 + * @deprecated 30.0.0 Register a listener for the CommentsEvent through the IEventDispatcher */ public function handle(CommentsEvent $event); } diff --git a/lib/public/Comments/ICommentsManager.php b/lib/public/Comments/ICommentsManager.php index c34bd4718cc..7e59b5c7b06 100644 --- a/lib/public/Comments/ICommentsManager.php +++ b/lib/public/Comments/ICommentsManager.php @@ -1,30 +1,9 @@ <?php + /** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Arthur Schiwon <blizzz@arthur-schiwon.de> - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author Joas Schilling <coding@schilljs.com> - * @author John Molakvoæ <skjnldsv@protonmail.com> - * @author Lukas Reschke <lukas@statuscode.ch> - * @author Robin Appelman <robin@icewind.nl> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * @author Thomas Müller <thomas.mueller@tmit.eu> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Affero General Public License for more details. - * - * You should have received a copy of the GNU Affero General Public License, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * + * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-FileCopyrightText: 2016 ownCloud, Inc. + * SPDX-License-Identifier: AGPL-3.0-only */ namespace OCP\Comments; @@ -39,7 +18,6 @@ use OCP\PreConditionNotMetException; * @since 9.0.0 */ interface ICommentsManager { - /** * @const DELETED_USER type and id for a user that has been deleted * @see deleteReferencesOfActor @@ -62,12 +40,12 @@ interface ICommentsManager { public function get($id); /** - * returns the comment specified by the id and all it's child comments + * Returns the comment specified by the id and all it's child comments * * @param string $id * @param int $limit max number of entries to return, 0 returns all * @param int $offset the start entry - * @return array + * @return array{comment: IComment, replies: list<array{comment: IComment, replies: array<empty, empty>}>} * @since 9.0.0 * * The return array looks like this @@ -107,19 +85,19 @@ interface ICommentsManager { * @param string $objectType the object type, e.g. 'files' * @param string $objectId the id of the object * @param int $limit optional, number of maximum comments to be returned. if - * not specified, all comments are returned. + * not specified, all comments are returned. * @param int $offset optional, starting point * @param \DateTime|null $notOlderThan optional, timestamp of the oldest comments - * that may be returned - * @return IComment[] + * that may be returned + * @return list<IComment> * @since 9.0.0 */ public function getForObject( - $objectType, - $objectId, - $limit = 0, - $offset = 0, - \DateTime $notOlderThan = null + $objectType, + $objectId, + $limit = 0, + $offset = 0, + ?\DateTime $notOlderThan = null, ); /** @@ -128,9 +106,10 @@ interface ICommentsManager { * @param int $lastKnownCommentId the last known comment (will be used as offset) * @param string $sortDirection direction of the comments (`asc` or `desc`) * @param int $limit optional, number of maximum comments to be returned. if - * set to 0, all comments are returned. + * set to 0, all comments are returned. * @param bool $includeLastKnown - * @return IComment[] + * @param string $topmostParentId Limit the comments to a list of replies and its original root comment + * @return list<IComment> * @since 14.0.0 * @deprecated 24.0.0 - Use getCommentsWithVerbForObjectSinceComment instead */ @@ -140,7 +119,8 @@ interface ICommentsManager { int $lastKnownCommentId, string $sortDirection = 'asc', int $limit = 30, - bool $includeLastKnown = false + bool $includeLastKnown = false, + string $topmostParentId = '', ): array; /** @@ -150,9 +130,10 @@ interface ICommentsManager { * @param int $lastKnownCommentId the last known comment (will be used as offset) * @param string $sortDirection direction of the comments (`asc` or `desc`) * @param int $limit optional, number of maximum comments to be returned. if - * set to 0, all comments are returned. + * set to 0, all comments are returned. * @param bool $includeLastKnown - * @return IComment[] + * @param string $topmostParentId Limit the comments to a list of replies and its original root comment + * @return list<IComment> * @since 24.0.0 */ public function getCommentsWithVerbForObjectSinceComment( @@ -162,7 +143,8 @@ interface ICommentsManager { int $lastKnownCommentId, string $sortDirection = 'asc', int $limit = 30, - bool $includeLastKnown = false + bool $includeLastKnown = false, + string $topmostParentId = '', ): array; /** @@ -174,7 +156,7 @@ interface ICommentsManager { * @param string $verb Limit the verb of the comment * @param int $offset * @param int $limit - * @return IComment[] + * @return list<IComment> * @since 14.0.0 */ public function search(string $search, string $objectType, string $objectId, string $verb, int $offset, int $limit = 50): array; @@ -197,12 +179,12 @@ interface ICommentsManager { * @param $objectType string the object type, e.g. 'files' * @param $objectId string the id of the object * @param \DateTime|null $notOlderThan optional, timestamp of the oldest comments - * that may be returned + * that may be returned * @param string $verb Limit the verb of the comment - Added in 14.0.0 * @return Int * @since 9.0.0 */ - public function getNumberOfCommentsForObject($objectType, $objectId, \DateTime $notOlderThan = null, $verb = ''); + public function getNumberOfCommentsForObject($objectType, $objectId, ?\DateTime $notOlderThan = null, $verb = ''); /** * @param string $objectType the object type, e.g. 'files' @@ -262,7 +244,7 @@ interface ICommentsManager { string $objectId, string $verb, string $actorType, - array $actors + array $actors, ): array; /** @@ -272,6 +254,7 @@ interface ICommentsManager { * @param IUser $user * @return array [$fileId => $unreadCount] * @since 12.0.0 + * @deprecated 29.0.0 use getNumberOfUnreadCommentsForObjects instead */ public function getNumberOfUnreadCommentsForFolder($folderId, IUser $user); @@ -482,4 +465,15 @@ interface ICommentsManager { * @since 21.0.0 */ public function load(): void; + + /** + * Delete comments with field expire_date less than current date + * Only will delete the message related with the object. + * + * @param string $objectType the object type (e.g. 'files') + * @param string $objectId e.g. the file id, leave empty to expire on all objects of this type + * @return boolean true if at least one row was deleted + * @since 25.0.0 + */ + public function deleteCommentsExpiredAtObject(string $objectType, string $objectId = ''): bool; } diff --git a/lib/public/Comments/ICommentsManagerFactory.php b/lib/public/Comments/ICommentsManagerFactory.php index e6f69807b05..bfe6154a48f 100644 --- a/lib/public/Comments/ICommentsManagerFactory.php +++ b/lib/public/Comments/ICommentsManagerFactory.php @@ -1,26 +1,9 @@ <?php + /** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Arthur Schiwon <blizzz@arthur-schiwon.de> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * @author Thomas Müller <thomas.mueller@tmit.eu> - * @author Vincent Petry <vincent@nextcloud.com> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Affero General Public License for more details. - * - * You should have received a copy of the GNU Affero General Public License, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * + * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-FileCopyrightText: 2016 ownCloud, Inc. + * SPDX-License-Identifier: AGPL-3.0-only */ namespace OCP\Comments; @@ -35,7 +18,6 @@ use OCP\IServerContainer; * @since 9.0.0 */ interface ICommentsManagerFactory { - /** * Constructor for the comments manager factory * diff --git a/lib/public/Comments/IllegalIDChangeException.php b/lib/public/Comments/IllegalIDChangeException.php index 76b0ced6bc6..08eddfc6fa4 100644 --- a/lib/public/Comments/IllegalIDChangeException.php +++ b/lib/public/Comments/IllegalIDChangeException.php @@ -1,26 +1,9 @@ <?php + /** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Arthur Schiwon <blizzz@arthur-schiwon.de> - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * @author Thomas Müller <thomas.mueller@tmit.eu> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Affero General Public License for more details. - * - * You should have received a copy of the GNU Affero General Public License, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * + * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-FileCopyrightText: 2016 ownCloud, Inc. + * SPDX-License-Identifier: AGPL-3.0-only */ namespace OCP\Comments; diff --git a/lib/public/Comments/MessageTooLongException.php b/lib/public/Comments/MessageTooLongException.php index 39d86881183..4358dc2e291 100644 --- a/lib/public/Comments/MessageTooLongException.php +++ b/lib/public/Comments/MessageTooLongException.php @@ -1,25 +1,9 @@ <?php + /** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Arthur Schiwon <blizzz@arthur-schiwon.de> - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Affero General Public License for more details. - * - * You should have received a copy of the GNU Affero General Public License, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * + * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-FileCopyrightText: 2016 ownCloud, Inc. + * SPDX-License-Identifier: AGPL-3.0-only */ namespace OCP\Comments; diff --git a/lib/public/Comments/NotFoundException.php b/lib/public/Comments/NotFoundException.php index e9f7a07aa52..4f25fdbf09f 100644 --- a/lib/public/Comments/NotFoundException.php +++ b/lib/public/Comments/NotFoundException.php @@ -1,26 +1,9 @@ <?php + /** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Arthur Schiwon <blizzz@arthur-schiwon.de> - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * @author Thomas Müller <thomas.mueller@tmit.eu> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Affero General Public License for more details. - * - * You should have received a copy of the GNU Affero General Public License, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * + * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-FileCopyrightText: 2016 ownCloud, Inc. + * SPDX-License-Identifier: AGPL-3.0-only */ namespace OCP\Comments; |