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