Code Coverage |
||||||||||
Lines |
Functions and Methods |
Classes and Traits |
||||||||
Total | n/a |
0 / 0 |
n/a |
0 / 0 |
CRAP | n/a |
0 / 0 |
1 | <?php |
2 | |
3 | /** |
4 | * Database service interface for resource_tags. |
5 | * |
6 | * PHP version 8 |
7 | * |
8 | * Copyright (C) Villanova University 2024. |
9 | * |
10 | * This program is free software; you can redistribute it and/or modify |
11 | * it under the terms of the GNU General Public License version 2, |
12 | * as published by the Free Software Foundation. |
13 | * |
14 | * This program is distributed in the hope that it will be useful, |
15 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
16 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
17 | * GNU General Public License for more details. |
18 | * |
19 | * You should have received a copy of the GNU General Public License |
20 | * along with this program; if not, write to the Free Software |
21 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA |
22 | * |
23 | * @category VuFind |
24 | * @package Database |
25 | * @author Demian Katz <demian.katz@villanova.edu> |
26 | * @license http://opensource.org/licenses/gpl-2.0.php GNU General Public License |
27 | * @link https://vufind.org/wiki/development:plugins:database_gateways Wiki |
28 | */ |
29 | |
30 | namespace VuFind\Db\Service; |
31 | |
32 | use DateTime; |
33 | use Laminas\Paginator\Paginator; |
34 | use VuFind\Db\Entity\ResourceEntityInterface; |
35 | use VuFind\Db\Entity\ResourceTagsEntityInterface; |
36 | use VuFind\Db\Entity\TagsEntityInterface; |
37 | use VuFind\Db\Entity\UserEntityInterface; |
38 | use VuFind\Db\Entity\UserListEntityInterface; |
39 | |
40 | /** |
41 | * Database service interface for resource_tags. |
42 | * |
43 | * @category VuFind |
44 | * @package Database |
45 | * @author Demian Katz <demian.katz@villanova.edu> |
46 | * @license http://opensource.org/licenses/gpl-2.0.php GNU General Public License |
47 | * @link https://vufind.org/wiki/development:plugins:database_gateways Wiki |
48 | */ |
49 | interface ResourceTagsServiceInterface extends DbServiceInterface |
50 | { |
51 | /** |
52 | * Get Resource Tags Paginator |
53 | * |
54 | * @param ?int $userId ID of user (null for any) |
55 | * @param ?int $resourceId ID of the resource (null for any) |
56 | * @param ?int $tagId ID of the tag (null for any) |
57 | * @param ?string $order The order in which to return the data |
58 | * @param ?int $page The page number to select |
59 | * @param int $limit The number of items to fetch |
60 | * @param bool $caseSensitiveTags Should we treat tags as case-sensitive? |
61 | * |
62 | * @return Paginator |
63 | */ |
64 | public function getResourceTagsPaginator( |
65 | ?int $userId = null, |
66 | ?int $resourceId = null, |
67 | ?int $tagId = null, |
68 | ?string $order = null, |
69 | ?int $page = null, |
70 | int $limit = 20, |
71 | bool $caseSensitiveTags = false |
72 | ): Paginator; |
73 | |
74 | /** |
75 | * Create a ResourceTagsEntityInterface object. |
76 | * |
77 | * @return ResourceTagsEntityInterface |
78 | */ |
79 | public function createEntity(): ResourceTagsEntityInterface; |
80 | |
81 | /** |
82 | * Create a resource_tags row linking the specified resources |
83 | * |
84 | * @param ResourceEntityInterface|int|null $resourceOrId Resource entity or ID to link up (optional) |
85 | * @param TagsEntityInterface|int $tagOrId Tag entity or ID to link up |
86 | * @param UserEntityInterface|int|null $userOrId User entity or ID creating link (optional but recommended) |
87 | * @param UserListEntityInterface|int|null $listOrId List entity or ID to link up (optional) |
88 | * @param ?DateTime $posted Posted date (optional -- omit for current) |
89 | * |
90 | * @return void |
91 | */ |
92 | public function createLink( |
93 | ResourceEntityInterface|int|null $resourceOrId, |
94 | TagsEntityInterface|int $tagOrId, |
95 | UserEntityInterface|int|null $userOrId = null, |
96 | UserListEntityInterface|int|null $listOrId = null, |
97 | ?DateTime $posted = null |
98 | ); |
99 | |
100 | /** |
101 | * Remove links from the resource_tags table based on an array of IDs. |
102 | * |
103 | * @param string[] $ids Identifiers from resource_tags to delete. |
104 | * |
105 | * @return int Count of $ids |
106 | */ |
107 | public function deleteLinksByResourceTagsIdArray(array $ids): int; |
108 | |
109 | /** |
110 | * Unlink tag rows for the specified resource and user. |
111 | * |
112 | * @param int|int[]|null $resourceId ID (or array of IDs) of resource(s) to |
113 | * unlink (null for ALL matching resources) |
114 | * @param UserEntityInterface|int $userOrId ID or entity representing user |
115 | * @param UserListEntityInterface|int|null $listOrId ID of list to unlink (null for ALL matching tags) |
116 | * @param int|int[]|null $tagId ID or array of IDs of tag(s) to unlink (null |
117 | * for ALL matching tags) |
118 | * |
119 | * @return void |
120 | */ |
121 | public function destroyResourceTagsLinksForUser( |
122 | int|array|null $resourceId, |
123 | UserEntityInterface|int $userOrId, |
124 | UserListEntityInterface|int|null $listOrId = null, |
125 | int|array|null $tagId = null |
126 | ): void; |
127 | |
128 | /** |
129 | * Unlink tag rows that are not associated with a favorite list for the specified resource and user. |
130 | * |
131 | * @param int|int[]|null $resourceId ID (or array of IDs) of resource(s) to unlink (null for ALL matching |
132 | * resources) |
133 | * @param UserEntityInterface|int $userOrId ID or entity representing user |
134 | * @param int|int[]|null $tagId ID or array of IDs of tag(s) to unlink (null for ALL matching tags) |
135 | * |
136 | * @return void |
137 | */ |
138 | public function destroyNonListResourceTagsLinksForUser( |
139 | int|array|null $resourceId, |
140 | UserEntityInterface|int $userOrId, |
141 | int|array|null $tagId = null |
142 | ): void; |
143 | |
144 | /** |
145 | * Unlink all tag rows associated with favorite lists for the specified resource and user. Tags added directly |
146 | * to records outside of favorites will not be impacted. |
147 | * |
148 | * @param int|int[]|null $resourceId ID (or array of IDs) of resource(s) to unlink (null for ALL matching |
149 | * resources) |
150 | * @param UserEntityInterface|int $userOrId ID or entity representing user |
151 | * @param int|int[]|null $tagId ID or array of IDs of tag(s) to unlink (null for ALL matching tags) |
152 | * |
153 | * @return void |
154 | */ |
155 | public function destroyAllListResourceTagsLinksForUser( |
156 | int|array|null $resourceId, |
157 | UserEntityInterface|int $userOrId, |
158 | int|array|null $tagId = null |
159 | ): void; |
160 | |
161 | /** |
162 | * Unlink rows for the specified user list. This removes tags ON THE LIST ITSELF, not tags on |
163 | * resources within the list. |
164 | * |
165 | * @param UserListEntityInterface|int $listOrId ID or entity representing list |
166 | * @param UserEntityInterface|int $userOrId ID or entity representing user |
167 | * @param int|int[]|null $tagId ID or array of IDs of tag(s) to unlink (null for ALL matching tags) |
168 | * |
169 | * @return void |
170 | */ |
171 | public function destroyUserListLinks( |
172 | UserListEntityInterface|int $listOrId, |
173 | UserEntityInterface|int $userOrId, |
174 | int|array|null $tagId = null |
175 | ): void; |
176 | |
177 | /** |
178 | * Gets unique tagged resources from the database. |
179 | * |
180 | * @param ?int $userId ID of user (null for any) |
181 | * @param ?int $resourceId ID of the resource (null for any) |
182 | * @param ?int $tagId ID of the tag (null for any) |
183 | * |
184 | * @return array[] |
185 | */ |
186 | public function getUniqueResources( |
187 | ?int $userId = null, |
188 | ?int $resourceId = null, |
189 | ?int $tagId = null |
190 | ): array; |
191 | |
192 | /** |
193 | * Gets unique tags from the database. |
194 | * |
195 | * @param ?int $userId ID of user (null for any) |
196 | * @param ?int $resourceId ID of the resource (null for any) |
197 | * @param ?int $tagId ID of the tag (null for any) |
198 | * @param bool $caseSensitive Should we treat tags in a case-sensitive manner? |
199 | * |
200 | * @return array[] |
201 | */ |
202 | public function getUniqueTags( |
203 | ?int $userId = null, |
204 | ?int $resourceId = null, |
205 | ?int $tagId = null, |
206 | bool $caseSensitive = false |
207 | ): array; |
208 | |
209 | /** |
210 | * Gets unique users from the database. |
211 | * |
212 | * @param ?int $userId ID of user (null for any) |
213 | * @param ?int $resourceId ID of the resource (null for any) |
214 | * @param ?int $tagId ID of the tag (null for any) |
215 | * |
216 | * @return array[] |
217 | */ |
218 | public function getUniqueUsers( |
219 | ?int $userId = null, |
220 | ?int $resourceId = null, |
221 | ?int $tagId = null |
222 | ): array; |
223 | |
224 | /** |
225 | * Delete resource tags rows matching specified filter(s). Return count of IDs deleted. |
226 | * |
227 | * @param ?int $userId ID of user (null for any) |
228 | * @param ?int $resourceId ID of the resource (null for any) |
229 | * @param ?int $tagId ID of the tag (null for any) |
230 | * |
231 | * @return int |
232 | */ |
233 | public function deleteResourceTags( |
234 | ?int $userId = null, |
235 | ?int $resourceId = null, |
236 | ?int $tagId = null |
237 | ): int; |
238 | |
239 | /** |
240 | * Get count of anonymous tags |
241 | * |
242 | * @return int count |
243 | */ |
244 | public function getAnonymousCount(): int; |
245 | |
246 | /** |
247 | * Assign anonymous tags to the specified user. |
248 | * |
249 | * @param UserEntityInterface|int $userOrId User entity or ID to own anonymous tags. |
250 | * |
251 | * @return void |
252 | */ |
253 | public function assignAnonymousTags(UserEntityInterface|int $userOrId): void; |
254 | |
255 | /** |
256 | * Change all matching rows to use the new resource ID instead of the old one (called when an ID changes). |
257 | * |
258 | * @param int $old Original resource ID |
259 | * @param int $new New resource ID |
260 | * |
261 | * @return void |
262 | */ |
263 | public function changeResourceId(int $old, int $new): void; |
264 | |
265 | /** |
266 | * Deduplicate rows (sometimes necessary after merging foreign key IDs). |
267 | * |
268 | * @return void |
269 | */ |
270 | public function deduplicate(): void; |
271 | } |