1<?php 2 3declare(strict_types=1); 4 5/** 6 * @copyright Copyright (c) 2016, ownCloud, Inc. 7 * 8 * @author Joas Schilling <coding@schilljs.com> 9 * @author Roeland Jago Douma <roeland@famdouma.nl> 10 * @author Vincent Petry <vincent@nextcloud.com> 11 * 12 * @license AGPL-3.0 13 * 14 * This code is free software: you can redistribute it and/or modify 15 * it under the terms of the GNU Affero General Public License, version 3, 16 * as published by the Free Software Foundation. 17 * 18 * This program is distributed in the hope that it will be useful, 19 * but WITHOUT ANY WARRANTY; without even the implied warranty of 20 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 21 * GNU Affero General Public License for more details. 22 * 23 * You should have received a copy of the GNU Affero General Public License, version 3, 24 * along with this program. If not, see <http://www.gnu.org/licenses/> 25 * 26 */ 27namespace OCP\SystemTag; 28 29use OCP\IUser; 30 31/** 32 * Public interface to access and manage system-wide tags. 33 * 34 * @since 9.0.0 35 */ 36interface ISystemTagManager { 37 38 /** 39 * Returns the tag objects matching the given tag ids. 40 * 41 * @param array|string $tagIds id or array of unique ids of the tag to retrieve 42 * 43 * @return ISystemTag[] array of system tags with tag id as key 44 * 45 * @throws \InvalidArgumentException if at least one given tag ids is invalid (string instead of integer, etc.) 46 * @throws TagNotFoundException if at least one given tag ids did no exist 47 * The message contains a json_encoded array of the ids that could not be found 48 * 49 * @since 9.0.0 50 */ 51 public function getTagsByIds($tagIds): array; 52 53 /** 54 * Returns the tag object matching the given attributes. 55 * 56 * @param string $tagName tag name 57 * @param bool $userVisible whether the tag is visible by users 58 * @param bool $userAssignable whether the tag is assignable by users 59 * 60 * @return ISystemTag system tag 61 * 62 * @throws TagNotFoundException if tag does not exist 63 * 64 * @since 9.0.0 65 */ 66 public function getTag(string $tagName, bool $userVisible, bool $userAssignable): ISystemTag; 67 68 /** 69 * Creates the tag object using the given attributes. 70 * 71 * @param string $tagName tag name 72 * @param bool $userVisible whether the tag is visible by users 73 * @param bool $userAssignable whether the tag is assignable by users 74 * 75 * @return ISystemTag system tag 76 * 77 * @throws TagAlreadyExistsException if tag already exists 78 * 79 * @since 9.0.0 80 */ 81 public function createTag(string $tagName, bool $userVisible, bool $userAssignable): ISystemTag; 82 83 /** 84 * Returns all known tags, optionally filtered by visibility. 85 * 86 * @param bool|null $visibilityFilter filter by visibility if non-null 87 * @param string $nameSearchPattern optional search pattern for the tag name 88 * 89 * @return ISystemTag[] array of system tags or empty array if none found 90 * 91 * @since 9.0.0 92 */ 93 public function getAllTags($visibilityFilter = null, $nameSearchPattern = null): array; 94 95 /** 96 * Updates the given tag 97 * 98 * @param string $tagId tag id 99 * @param string $newName the new tag name 100 * @param bool $userVisible whether the tag is visible by users 101 * @param bool $userAssignable whether the tag is assignable by users 102 * 103 * @throws TagNotFoundException if tag with the given id does not exist 104 * @throws TagAlreadyExistsException if there is already another tag 105 * with the same attributes 106 * 107 * @since 9.0.0 108 */ 109 public function updateTag(string $tagId, string $newName, bool $userVisible, bool $userAssignable); 110 111 /** 112 * Delete the given tags from the database and all their relationships. 113 * 114 * @param string|array $tagIds array of tag ids 115 * 116 * @throws TagNotFoundException if at least one tag did not exist 117 * 118 * @since 9.0.0 119 */ 120 public function deleteTags($tagIds); 121 122 /** 123 * Checks whether the given user is allowed to assign/unassign the tag with the 124 * given id. 125 * 126 * @param ISystemTag $tag tag to check permission for 127 * @param IUser $user user to check permission for 128 * 129 * @return true if the user is allowed to assign/unassign the tag, false otherwise 130 * 131 * @since 9.1.0 132 */ 133 public function canUserAssignTag(ISystemTag $tag, IUser $user): bool; 134 135 /** 136 * Checks whether the given user is allowed to see the tag with the given id. 137 * 138 * @param ISystemTag $tag tag to check permission for 139 * @param IUser $user user to check permission for 140 * 141 * @return true if the user can see the tag, false otherwise 142 * 143 * @since 9.1.0 144 */ 145 public function canUserSeeTag(ISystemTag $tag, IUser $user): bool; 146 147 /** 148 * Set groups that can assign a given tag. 149 * 150 * @param ISystemTag $tag tag for group assignment 151 * @param string[] $groupIds group ids of groups that can assign/unassign the tag 152 * 153 * @since 9.1.0 154 */ 155 public function setTagGroups(ISystemTag $tag, array $groupIds); 156 157 /** 158 * Get groups that can assign a given tag. 159 * 160 * @param ISystemTag $tag tag for group assignment 161 * 162 * @return string[] group ids of groups that can assign/unassign the tag 163 * 164 * @since 9.1.0 165 */ 166 public function getTagGroups(ISystemTag $tag): array; 167} 168