diff options
Diffstat (limited to 'lib/public/SystemTag/ISystemTagManager.php')
| -rw-r--r-- | lib/public/SystemTag/ISystemTagManager.php | 175 |
1 files changed, 175 insertions, 0 deletions
diff --git a/lib/public/SystemTag/ISystemTagManager.php b/lib/public/SystemTag/ISystemTagManager.php new file mode 100644 index 00000000000..96e775d6401 --- /dev/null +++ b/lib/public/SystemTag/ISystemTagManager.php @@ -0,0 +1,175 @@ +<?php + +declare(strict_types=1); +/** + * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-FileCopyrightText: 2016 ownCloud, Inc. + * SPDX-License-Identifier: AGPL-3.0-only + */ +namespace OCP\SystemTag; + +use OCP\IUser; + +/** + * Public interface to access and manage system-wide tags. + * + * @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 + * + * @since 9.0.0, optional parameter $user added in 28.0.0 + */ + public function getTagsByIds($tagIds, ?IUser $user = null): array; + + /** + * Returns the tag object matching the given attributes. + * + * @param string $tagName tag name + * @param bool $userVisible whether the tag is visible by users + * @param bool $userAssignable whether the tag is assignable by users + * + * @return ISystemTag system tag + * + * @throws TagNotFoundException if tag does not exist + * + * @since 9.0.0 + */ + public function getTag(string $tagName, bool $userVisible, bool $userAssignable): ISystemTag; + + /** + * Creates the tag object using the given attributes. + * + * @param string $tagName tag name + * @param bool $userVisible whether the tag is visible by users + * @param bool $userAssignable whether the tag is assignable by users + * + * @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; + + /** + * Returns all known tags, optionally filtered by visibility. + * + * @param bool|null $visibilityFilter filter by visibility if non-null + * @param string $nameSearchPattern optional search pattern for the tag name + * + * @return ISystemTag[] array of system tags or empty array if none found + * + * @since 9.0.0 + */ + public function getAllTags($visibilityFilter = null, $nameSearchPattern = null): array; + + /** + * Updates the given tag + * + * @param string $tagId tag id + * @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 + * + * @since 9.0.0 + * @since 31.0.0 `$color` parameter added + */ + public function updateTag(string $tagId, string $newName, bool $userVisible, bool $userAssignable, ?string $color); + + /** + * Delete the given tags from the database and all their relationships. + * + * @param string|array $tagIds array of tag ids + * + * @throws TagNotFoundException if at least one tag did not exist + * + * @since 9.0.0 + */ + public function deleteTags($tagIds); + + /** + * Checks whether the given user is allowed to assign/unassign the tag with the + * given id. + * + * @param ISystemTag $tag tag to check permission for + * @param IUser|null $user user to check permission for + * + * @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 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|null $user user to check permission for + * + * @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; + + /** + * Set groups that can assign a given tag. + * + * @param ISystemTag $tag tag for group assignment + * @param string[] $groupIds group ids of groups that can assign/unassign the tag + * + * @since 9.1.0 + */ + public function setTagGroups(ISystemTag $tag, array $groupIds); + + /** + * Get groups that can assign a given tag. + * + * @param ISystemTag $tag tag for group assignment + * + * @return string[] group ids of groups that can assign/unassign the tag + * + * @since 9.1.0 + */ + public function getTagGroups(ISystemTag $tag): array; +} |