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 search.
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\SearchEntityInterface;
33use VuFind\Db\Entity\UserEntityInterface;
34
35/**
36 * Database service interface for search.
37 *
38 * @category VuFind
39 * @package  Database
40 * @author   Demian Katz <demian.katz@villanova.edu>
41 * @license  http://opensource.org/licenses/gpl-2.0.php GNU General Public License
42 * @link     https://vufind.org/wiki/development:plugins:database_gateways interface
43 */
44interface SearchServiceInterface extends DbServiceInterface
45{
46    /**
47     * Create a search entity.
48     *
49     * @return SearchEntityInterface
50     */
51    public function createEntity(): SearchEntityInterface;
52
53    /**
54     * Create a search entity containing the specified checksum, persist it to the database,
55     * and return a fully populated object. Throw an exception if something goes wrong during
56     * the process.
57     *
58     * @param int $checksum Checksum
59     *
60     * @return SearchEntityInterface
61     * @throws Exception
62     */
63    public function createAndPersistEntityWithChecksum(int $checksum): SearchEntityInterface;
64
65    /**
66     * Destroy unsaved searches belonging to the specified session/user.
67     *
68     * @param string                       $sessionId Session ID of current user.
69     * @param UserEntityInterface|int|null $userOrId  User entity or ID of current user (optional).
70     *
71     * @return void
72     */
73    public function destroySession(string $sessionId, UserEntityInterface|int|null $userOrId = null): void;
74
75    /**
76     * Get a SearchEntityInterface object by ID.
77     *
78     * @param int $id Search identifier
79     *
80     * @return ?SearchEntityInterface
81     */
82    public function getSearchById(int $id): ?SearchEntityInterface;
83
84    /**
85     * Get a SearchEntityInterface object by ID and owner.
86     *
87     * @param int                          $id        Search identifier
88     * @param string                       $sessionId Session ID of current user.
89     * @param UserEntityInterface|int|null $userOrId  User entity or ID of current user (optional).
90     *
91     * @return ?SearchEntityInterface
92     */
93    public function getSearchByIdAndOwner(
94        int $id,
95        string $sessionId,
96        UserEntityInterface|int|null $userOrId
97    ): ?SearchEntityInterface;
98
99    /**
100     * Get an array of rows for the specified user.
101     *
102     * @param string                       $sessionId Session ID of current user.
103     * @param UserEntityInterface|int|null $userOrId  User entity or ID of current user (optional).
104     *
105     * @return SearchEntityInterface[]
106     */
107    public function getSearches(string $sessionId, UserEntityInterface|int|null $userOrId = null): array;
108
109    /**
110     * Get scheduled searches.
111     *
112     * @return SearchEntityInterface[]
113     */
114    public function getScheduledSearches(): array;
115
116    /**
117     * Retrieve all searches matching the specified checksum and belonging to the user specified by session or user
118     * entity/ID.
119     *
120     * @param int                          $checksum  Checksum to match
121     * @param string                       $sessionId Current session ID
122     * @param UserEntityInterface|int|null $userOrId  Entity or ID representing current user (optional).
123     *
124     * @return SearchEntityInterface[]
125     * @throws Exception
126     */
127    public function getSearchesByChecksumAndOwner(
128        int $checksum,
129        string $sessionId,
130        UserEntityInterface|int|null $userOrId = null
131    ): array;
132
133    /**
134     * Set invalid user_id values in the table to null; return count of affected rows.
135     *
136     * @return int
137     */
138    public function cleanUpInvalidUserIds(): int;
139
140    /**
141     * Get saved searches with missing checksums (used for cleaning up legacy data).
142     *
143     * @return SearchEntityInterface[]
144     */
145    public function getSavedSearchesWithMissingChecksums(): array;
146}