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 UserList.
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   Sudharma Kellampalli <skellamp@villanova.edu>
26 * @author   Demian Katz <demian.katz@villanova.edu>
27 * @license  http://opensource.org/licenses/gpl-2.0.php GNU General Public License
28 * @link     https://vufind.org/wiki/development:plugins:database_gateways Wiki
29 */
30
31namespace VuFind\Db\Service;
32
33use VuFind\Db\Entity\UserEntityInterface;
34use VuFind\Db\Entity\UserListEntityInterface;
35use VuFind\Exception\RecordMissing as RecordMissingException;
36
37/**
38 * Database service interface for UserList.
39 *
40 * @category VuFind
41 * @package  Database
42 * @author   Sudharma Kellampalli <skellamp@villanova.edu>
43 * @author   Demian Katz <demian.katz@villanova.edu>
44 * @license  http://opensource.org/licenses/gpl-2.0.php GNU General Public License
45 * @link     https://vufind.org/wiki/development:plugins:database_gateways Wiki
46 */
47interface UserListServiceInterface extends DbServiceInterface
48{
49    /**
50     * Create a UserList entity object.
51     *
52     * @return UserListEntityInterface
53     */
54    public function createEntity(): UserListEntityInterface;
55
56    /**
57     * Delete a user list entity.
58     *
59     * @param UserListEntityInterface|int $listOrId List entity object or ID to delete
60     *
61     * @return void
62     */
63    public function deleteUserList(UserListEntityInterface|int $listOrId): void;
64
65    /**
66     * Retrieve a list object.
67     *
68     * @param int $id Numeric ID for existing list.
69     *
70     * @return UserListEntityInterface
71     * @throws RecordMissingException
72     */
73    public function getUserListById(int $id): UserListEntityInterface;
74
75    /**
76     * Get public lists.
77     *
78     * @param array $includeFilter List of list ids or entities to include in result.
79     * @param array $excludeFilter List of list ids or entities to exclude from result.
80     *
81     * @return UserListEntityInterface[]
82     */
83    public function getPublicLists(array $includeFilter = [], array $excludeFilter = []): array;
84
85    /**
86     * Get lists belonging to the user and their count. Returns an array of arrays with
87     * list_entity and count keys.
88     *
89     * @param UserEntityInterface|int $userOrId User entity object or ID
90     *
91     * @return array
92     * @throws Exception
93     */
94    public function getUserListsAndCountsByUser(UserEntityInterface|int $userOrId): array;
95
96    /**
97     * Get lists associated with a particular tag and/or list of IDs. If IDs and
98     * tags are both provided, only the intersection of matches will be returned.
99     *
100     * @param string|string[]|null $tag               Tag or tags to match (by text, not ID; null for all)
101     * @param int|int[]|null       $listId            List ID or IDs to match (null for all)
102     * @param bool                 $publicOnly        Whether to return only public lists
103     * @param bool                 $andTags           Use AND operator when filtering by tag.
104     * @param bool                 $caseSensitiveTags Should we treat tags case-sensitively?
105     *
106     * @return UserListEntityInterface[]
107     */
108    public function getUserListsByTagAndId(
109        string|array|null $tag = null,
110        int|array|null $listId = null,
111        bool $publicOnly = true,
112        bool $andTags = true,
113        bool $caseSensitiveTags = false
114    ): array;
115
116    /**
117     * Get list objects belonging to the specified user.
118     *
119     * @param UserEntityInterface|int $userOrId User entity object or ID
120     *
121     * @return UserListEntityInterface[]
122     */
123    public function getUserListsByUser(UserEntityInterface|int $userOrId): array;
124
125    /**
126     * Get lists containing a specific record.
127     *
128     * @param string                       $recordId ID of record being checked.
129     * @param string                       $source   Source of record to look up
130     * @param UserEntityInterface|int|null $userOrId Optional user ID or entity object (to limit results
131     * to a particular user).
132     *
133     * @return UserListEntityInterface[]
134     */
135    public function getListsContainingRecord(
136        string $recordId,
137        string $source = DEFAULT_SEARCH_BACKEND,
138        UserEntityInterface|int|null $userOrId = null
139    ): array;
140}