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 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 VuFind\Db\Entity\TagsEntityInterface; |
33 | use VuFind\Db\Entity\UserEntityInterface; |
34 | use VuFind\Db\Entity\UserListEntityInterface; |
35 | |
36 | /** |
37 | * Database service interface for tags. |
38 | * |
39 | * @category VuFind |
40 | * @package Database |
41 | * @author Demian Katz <demian.katz@villanova.edu> |
42 | * @license http://opensource.org/licenses/gpl-2.0.php GNU General Public License |
43 | * @link https://vufind.org/wiki/development:plugins:database_gateways Wiki |
44 | */ |
45 | interface TagServiceInterface extends DbServiceInterface |
46 | { |
47 | /** |
48 | * Get statistics on use of tags. |
49 | * |
50 | * @param bool $extended Include extended (unique/anonymous) stats. |
51 | * @param bool $caseSensitiveTags Should we treat tags case-sensitively? |
52 | * |
53 | * @return array |
54 | */ |
55 | public function getStatistics(bool $extended = false, bool $caseSensitiveTags = false): array; |
56 | |
57 | /** |
58 | * Get the tags that match a string |
59 | * |
60 | * @param string $text Tag to look up. |
61 | * @param string $sort Sort type |
62 | * @param int $limit Maximum results to retrieve |
63 | * @param bool $caseSensitive Should tags be treated as case-sensitive? |
64 | * |
65 | * @return array |
66 | */ |
67 | public function getNonListTagsFuzzilyMatchingString( |
68 | string $text, |
69 | string $sort = 'alphabetical', |
70 | int $limit = 100, |
71 | bool $caseSensitive = false |
72 | ): array; |
73 | |
74 | /** |
75 | * Get all matching tags by text. Normally, 0 or 1 results will be retrieved, but more |
76 | * may be retrieved under exceptional circumstances (e.g. if retrieving case-insensitively |
77 | * after storing data case-sensitively). |
78 | * |
79 | * @param string $text Tag text to match |
80 | * @param bool $caseSensitive Should tags be retrieved case-sensitively? |
81 | * |
82 | * @return TagsEntityInterface[] |
83 | */ |
84 | public function getTagsByText(string $text, bool $caseSensitive = false): array; |
85 | |
86 | /** |
87 | * Get the first available matching tag by text; return null if no match is found. |
88 | * |
89 | * @param string $text Tag text to match |
90 | * @param bool $caseSensitive Should tags be retrieved case-sensitively? |
91 | * |
92 | * @return TagsEntityInterface[] |
93 | */ |
94 | public function getTagByText(string $text, bool $caseSensitive = false): ?TagsEntityInterface; |
95 | |
96 | /** |
97 | * Get all resources associated with the provided tag query. |
98 | * |
99 | * @param string $q Search query |
100 | * @param string $source Record source (optional limiter) |
101 | * @param string $sort Resource field to sort on (optional) |
102 | * @param int $offset Offset for results |
103 | * @param ?int $limit Limit for results (null for none) |
104 | * @param bool $fuzzy Are we doing an exact (false) or fuzzy (true) search? |
105 | * @param ?bool $caseSensitive Should search be case sensitive? (Ignored when fuzzy = true) |
106 | * |
107 | * @return array |
108 | */ |
109 | public function getResourcesMatchingTagQuery( |
110 | string $q, |
111 | string $source = null, |
112 | string $sort = null, |
113 | int $offset = 0, |
114 | ?int $limit = null, |
115 | bool $fuzzy = true, |
116 | bool $caseSensitive = false |
117 | ): array; |
118 | |
119 | /** |
120 | * Get a list of tags for the browse interface. |
121 | * |
122 | * @param string $sort Sort/search parameter |
123 | * @param int $limit Maximum number of tags (default = 100, < 1 = no limit) |
124 | * @param bool $caseSensitive Treat tags as case-sensitive? |
125 | * |
126 | * @return array |
127 | */ |
128 | public function getTagBrowseList(string $sort, int $limit, bool $caseSensitive = false): array; |
129 | |
130 | /** |
131 | * Get all tags associated with the specified record (and matching provided filters). |
132 | * |
133 | * @param string $id Record ID to look up |
134 | * @param string $source Source of record to look up |
135 | * @param int $limit Max. number of tags to return (0 = no limit) |
136 | * @param UserListEntityInterface|int|null $listOrId ID of list to load tags from (null for no restriction) |
137 | * @param UserEntityInterface|int|null $userOrId ID of user to load tags from (null for all users) |
138 | * @param string $sort Sort type ('count' or 'tag') |
139 | * @param UserEntityInterface|int|null $ownerOrId ID of user to check for ownership |
140 | * @param bool $caseSensitive Treat tags as case-sensitive? |
141 | * |
142 | * @return array |
143 | */ |
144 | public function getRecordTags( |
145 | string $id, |
146 | string $source = DEFAULT_SEARCH_BACKEND, |
147 | int $limit = 0, |
148 | UserListEntityInterface|int|null $listOrId = null, |
149 | UserEntityInterface|int|null $userOrId = null, |
150 | string $sort = 'count', |
151 | UserEntityInterface|int|null $ownerOrId = null, |
152 | bool $caseSensitive = false |
153 | ): array; |
154 | |
155 | /** |
156 | * Get all tags from favorite lists associated with the specified record (and matching provided filters). |
157 | * |
158 | * @param string $id Record ID to look up |
159 | * @param string $source Source of record to look up |
160 | * @param int $limit Max. number of tags to return (0 = no limit) |
161 | * @param UserListEntityInterface|int|null $listOrId ID of list to load tags from (null for tags that |
162 | * are associated with ANY list, but excluding non-list tags) |
163 | * @param UserEntityInterface|int|null $userOrId ID of user to load tags from (null for all users) |
164 | * @param string $sort Sort type ('count' or 'tag') |
165 | * @param UserEntityInterface|int|null $ownerOrId ID of user to check for ownership |
166 | * (this will not filter the result list, but rows owned by this user will have an is_me column set to 1) |
167 | * @param bool $caseSensitive Treat tags as case-sensitive? |
168 | * |
169 | * @return array |
170 | */ |
171 | public function getRecordTagsFromFavorites( |
172 | string $id, |
173 | string $source = DEFAULT_SEARCH_BACKEND, |
174 | int $limit = 0, |
175 | UserListEntityInterface|int|null $listOrId = null, |
176 | UserEntityInterface|int|null $userOrId = null, |
177 | string $sort = 'count', |
178 | UserEntityInterface|int|null $ownerOrId = null, |
179 | bool $caseSensitive = false |
180 | ): array; |
181 | |
182 | /** |
183 | * Get all tags outside of favorite lists associated with the specified record (and matching provided filters). |
184 | * |
185 | * @param string $id Record ID to look up |
186 | * @param string $source Source of record to look up |
187 | * @param int $limit Max. number of tags to return (0 = no limit) |
188 | * @param UserEntityInterface|int|null $userOrId User entity/ID to load tags from (null for all users) |
189 | * @param string $sort Sort type ('count' or 'tag') |
190 | * @param UserEntityInterface|int|null $ownerOrId Entity/ID representing user to check for ownership |
191 | * (this will not filter the result list, but rows owned by this user will have an is_me column set to 1) |
192 | * @param bool $caseSensitive Treat tags as case-sensitive? |
193 | * |
194 | * @return array |
195 | */ |
196 | public function getRecordTagsNotInFavorites( |
197 | string $id, |
198 | string $source = DEFAULT_SEARCH_BACKEND, |
199 | int $limit = 0, |
200 | UserEntityInterface|int|null $userOrId = null, |
201 | string $sort = 'count', |
202 | UserEntityInterface|int|null $ownerOrId = null, |
203 | bool $caseSensitive = false |
204 | ): array; |
205 | |
206 | /** |
207 | * Get a list of duplicate tags (this should never happen, but past bugs and the introduction of case-insensitive |
208 | * tags have introduced problems). |
209 | * |
210 | * @param bool $caseSensitive Treat tags as case-sensitive? |
211 | * |
212 | * @return array |
213 | */ |
214 | public function getDuplicateTags(bool $caseSensitive = false): array; |
215 | |
216 | /** |
217 | * Get a list of all tags generated by the user in favorites lists. Note that the returned list WILL NOT include |
218 | * tags attached to records that are not saved in favorites lists. Returns an array of arrays with id and tag keys. |
219 | * |
220 | * @param UserEntityInterface|int $userOrId User ID to look up. |
221 | * @param UserListEntityInterface|int|null $listOrId Filter for tags tied to a specific list (null for no |
222 | * filter). |
223 | * @param ?string $recordId Filter for tags tied to a specific resource (null for no |
224 | * filter). |
225 | * @param ?string $source Filter for tags tied to a specific record source (null |
226 | * for no filter). |
227 | * @param bool $caseSensitive Treat tags as case-sensitive? |
228 | * |
229 | * @return array |
230 | */ |
231 | public function getUserTagsFromFavorites( |
232 | UserEntityInterface|int $userOrId, |
233 | UserListEntityInterface|int|null $listOrId = null, |
234 | ?string $recordId = null, |
235 | ?string $source = null, |
236 | bool $caseSensitive = false |
237 | ): array; |
238 | |
239 | /** |
240 | * Get tags assigned to a user list. Returns an array of arrays with id and tag keys. |
241 | * |
242 | * @param UserListEntityInterface|int $listOrId List ID or entity |
243 | * @param UserEntityInterface|int|null $userOrId User ID or entity to look up (null for no filter). |
244 | * @param bool $caseSensitive Treat tags as case-sensitive? |
245 | * |
246 | * @return array[] |
247 | */ |
248 | public function getListTags( |
249 | UserListEntityInterface|int $listOrId, |
250 | UserEntityInterface|int|null $userOrId = null, |
251 | $caseSensitive = false |
252 | ): array; |
253 | |
254 | /** |
255 | * Delete orphaned tags (those not present in resource_tags) from the tags table. |
256 | * |
257 | * @return void |
258 | */ |
259 | public function deleteOrphanedTags(): void; |
260 | |
261 | /** |
262 | * Retrieve a tag by ID. |
263 | * |
264 | * @param int $id Tag ID |
265 | * |
266 | * @return ?TagsEntityInterface |
267 | */ |
268 | public function getTagById(int $id): ?TagsEntityInterface; |
269 | |
270 | /** |
271 | * Create a new Tag entity. |
272 | * |
273 | * @return TagsEntityInterface |
274 | */ |
275 | public function createEntity(): TagsEntityInterface; |
276 | } |