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
30namespace VuFind\Db\Service;
31
32use DateTime;
33use Laminas\Paginator\Paginator;
34use VuFind\Db\Entity\ResourceEntityInterface;
35use VuFind\Db\Entity\ResourceTagsEntityInterface;
36use VuFind\Db\Entity\TagsEntityInterface;
37use VuFind\Db\Entity\UserEntityInterface;
38use 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 */
49interface 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}