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 users.
5 *
6 * PHP version 8
7 *
8 * Copyright (C) The National Library of Finland 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   Aleksi Peebles <aleksi.peebles@helsinki.fi>
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\UserEntityInterface;
33
34/**
35 * Database service interface for users.
36 *
37 * @category VuFind
38 * @package  Database
39 * @author   Aleksi Peebles <aleksi.peebles@helsinki.fi>
40 * @license  http://opensource.org/licenses/gpl-2.0.php GNU General Public License
41 * @link     https://vufind.org/wiki/development:plugins:database_gateways Wiki
42 */
43interface UserServiceInterface extends DbServiceInterface
44{
45    /**
46     * Create an entity for the specified username.
47     *
48     * @param string $username Username
49     *
50     * @return UserEntityInterface
51     */
52    public function createEntityForUsername(string $username): UserEntityInterface;
53
54    /**
55     * Delete a user entity.
56     *
57     * @param UserEntityInterface|int $userOrId User entity object or ID to delete
58     *
59     * @return void
60     */
61    public function deleteUser(UserEntityInterface|int $userOrId): void;
62
63    /**
64     * Retrieve a user object from the database based on ID.
65     *
66     * @param int $id ID.
67     *
68     * @return ?UserEntityInterface
69     */
70    public function getUserById(int $id): ?UserEntityInterface;
71
72    /**
73     * Retrieve a user object from the database based on the given field.
74     * Field name must be id, username, email, verify_hash or cat_id.
75     *
76     * @param string          $fieldName  Field name
77     * @param int|string|null $fieldValue Field value
78     *
79     * @return ?UserEntityInterface
80     */
81    public function getUserByField(string $fieldName, int|string|null $fieldValue): ?UserEntityInterface;
82
83    /**
84     * Retrieve a user object by catalog ID. Returns null if no match is found.
85     *
86     * @param string $catId Catalog ID
87     *
88     * @return ?UserEntityInterface
89     */
90    public function getUserByCatId(string $catId): ?UserEntityInterface;
91
92    /**
93     * Retrieve a user object by email address. Returns null if no match is found.
94     *
95     * @param string $email Email address
96     *
97     * @return ?UserEntityInterface
98     */
99    public function getUserByEmail(string $email): ?UserEntityInterface;
100
101    /**
102     * Retrieve a user object by username. Returns null if no match is found.
103     *
104     * @param string $username Username
105     *
106     * @return ?UserEntityInterface
107     */
108    public function getUserByUsername(string $username): ?UserEntityInterface;
109
110    /**
111     * Retrieve a user object by verify hash. Returns null if no match is found.
112     *
113     * @param string $hash Verify hash
114     *
115     * @return ?UserEntityInterface
116     */
117    public function getUserByVerifyHash(string $hash): ?UserEntityInterface;
118
119    /**
120     * Update the user's email address, if appropriate. Note that this does NOT
121     * automatically save the row; it assumes a subsequent call will be made to
122     * persist the data.
123     *
124     * @param UserEntityInterface $user         User entity to update
125     * @param string              $email        New email address
126     * @param bool                $userProvided Was this email provided by the user (true) or
127     * an automated lookup (false)?
128     *
129     * @return void
130     */
131    public function updateUserEmail(
132        UserEntityInterface $user,
133        string $email,
134        bool $userProvided = false
135    ): void;
136
137    /**
138     * Get all rows with catalog usernames.
139     *
140     * @return UserEntityInterface[]
141     */
142    public function getAllUsersWithCatUsernames(): array;
143
144    /**
145     * Get user rows with insecure catalog passwords.
146     *
147     * @return UserEntityInterface[]
148     */
149    public function getInsecureRows(): array;
150
151    /**
152     * Create a new user entity.
153     *
154     * @return UserEntityInterface
155     */
156    public function createEntity(): UserEntityInterface;
157}