diff options
Diffstat (limited to 'lib/public/SystemTag/ISystemTagManager.php')
| -rw-r--r-- | lib/public/SystemTag/ISystemTagManager.php | 74 |
1 files changed, 41 insertions, 33 deletions
diff --git a/lib/public/SystemTag/ISystemTagManager.php b/lib/public/SystemTag/ISystemTagManager.php index 500d80ea278..96e775d6401 100644 --- a/lib/public/SystemTag/ISystemTagManager.php +++ b/lib/public/SystemTag/ISystemTagManager.php @@ -1,28 +1,10 @@ <?php declare(strict_types=1); - /** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Joas Schilling <coding@schilljs.com> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * @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\SystemTag; @@ -34,21 +16,21 @@ use OCP\IUser; * @since 9.0.0 */ interface ISystemTagManager { - /** * Returns the tag objects matching the given tag ids. * * @param array|string $tagIds id or array of unique ids of the tag to retrieve + * @param ?IUser $user optional user to run a visibility check against for each tag * * @return ISystemTag[] array of system tags with tag id as key * * @throws \InvalidArgumentException if at least one given tag ids is invalid (string instead of integer, etc.) * @throws TagNotFoundException if at least one given tag ids did no exist - * The message contains a json_encoded array of the ids that could not be found + * The message contains a json_encoded array of the ids that could not be found * - * @since 9.0.0 + * @since 9.0.0, optional parameter $user added in 28.0.0 */ - public function getTagsByIds($tagIds): array; + public function getTagsByIds($tagIds, ?IUser $user = null): array; /** * Returns the tag object matching the given attributes. @@ -75,8 +57,10 @@ interface ISystemTagManager { * @return ISystemTag system tag * * @throws TagAlreadyExistsException if tag already exists + * @throws TagCreationForbiddenException if user doesn't have the right to create a new tag * * @since 9.0.0 + * @since 31.0.0 Can throw TagCreationForbiddenExceptionif user doesn't have the right to create a new tag */ public function createTag(string $tagName, bool $userVisible, bool $userAssignable): ISystemTag; @@ -99,14 +83,16 @@ interface ISystemTagManager { * @param string $newName the new tag name * @param bool $userVisible whether the tag is visible by users * @param bool $userAssignable whether the tag is assignable by users + * @param string $color color * * @throws TagNotFoundException if tag with the given id does not exist * @throws TagAlreadyExistsException if there is already another tag - * with the same attributes + * with the same attributes * * @since 9.0.0 + * @since 31.0.0 `$color` parameter added */ - public function updateTag(string $tagId, string $newName, bool $userVisible, bool $userAssignable); + public function updateTag(string $tagId, string $newName, bool $userVisible, bool $userAssignable, ?string $color); /** * Delete the given tags from the database and all their relationships. @@ -124,25 +110,47 @@ interface ISystemTagManager { * given id. * * @param ISystemTag $tag tag to check permission for - * @param IUser $user user to check permission for + * @param IUser|null $user user to check permission for * - * @return true if the user is allowed to assign/unassign the tag, false otherwise + * @return bool true if the user is allowed to assign/unassign the tag, false otherwise * * @since 9.1.0 + * @since 31.0.0 `$user` can be null to check anonymous permissions + */ + public function canUserAssignTag(ISystemTag $tag, ?IUser $user): bool; + + /** + * Checks whether the given user is allowed to create new tags + * + * @param IUser|null $user user to check permission for + * @return bool true if the user is allowed to create a new tag, false otherwise + * + * @since 31.0.0 + */ + public function canUserCreateTag(?IUser $user): bool; + + /** + * Checks whether the given user is allowed to update tags + * + * @param IUser|null $user user to check permission for + * @return bool true if the user is allowed to update a tag, false otherwise + * + * @since 31.0.0 */ - public function canUserAssignTag(ISystemTag $tag, IUser $user): bool; + public function canUserUpdateTag(?IUser $user): bool; /** * Checks whether the given user is allowed to see the tag with the given id. * * @param ISystemTag $tag tag to check permission for - * @param IUser $user user to check permission for + * @param IUser|null $user user to check permission for * - * @return true if the user can see the tag, false otherwise + * @return bool true if the user can see the tag, false otherwise * * @since 9.1.0 + * @since 31.0.0 `$user` can be null to check anonymous permissions */ - public function canUserSeeTag(ISystemTag $tag, IUser $user): bool; + public function canUserSeeTag(ISystemTag $tag, ?IUser $user): bool; /** * Set groups that can assign a given tag. |