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
30namespace VuFind\Db\Service;
31
32use VuFind\Db\Entity\TagsEntityInterface;
33use VuFind\Db\Entity\UserEntityInterface;
34use 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 */
45interface 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}