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