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 for UserCard.
5 *
6 * PHP version 8
7 *
8 * Copyright (C) Villanova University 2023.
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\UserCardEntityInterface;
34use VuFind\Db\Entity\UserEntityInterface;
35
36/**
37 * Database service for UserCard.
38 *
39 * @category VuFind
40 * @package  Database
41 * @author   Demian Katz <demian.katz@villanova.edu>
42 * @author   Demian Katz <demian.katz@villanova.edu>
43 * @license  http://opensource.org/licenses/gpl-2.0.php GNU General Public License
44 * @link     https://vufind.org/wiki/development:plugins:database_gateways Wiki
45 */
46interface UserCardServiceInterface extends DbServiceInterface
47{
48    /**
49     * Get user_card rows with insecure catalog passwords.
50     *
51     * @return UserCardEntityInterface[]
52     */
53    public function getInsecureRows(): array;
54
55    /**
56     * Get user_card rows with catalog usernames set.
57     *
58     * @return UserCardEntityInterface[]
59     */
60    public function getAllRowsWithUsernames(): array;
61
62    /**
63     * Get all library cards associated with the user.
64     *
65     * @param UserEntityInterface|int $userOrId    User object or identifier
66     * @param ?int                    $id          Optional card ID filter
67     * @param ?string                 $catUsername Optional catalog username filter
68     *
69     * @return UserCardEntityInterface[]
70     */
71    public function getLibraryCards(
72        UserEntityInterface|int $userOrId,
73        ?int $id = null,
74        ?string $catUsername = null
75    ): array;
76
77    /**
78     * Get or create library card data.
79     *
80     * @param UserEntityInterface|int $userOrId User object or identifier
81     * @param ?int                    $id       Card ID to fetch (or null to create a new card)
82     *
83     * @return UserCardEntityInterface Card data if found; throws exception otherwise
84     * @throws \VuFind\Exception\LibraryCard
85     */
86    public function getOrCreateLibraryCard(UserEntityInterface|int $userOrId, ?int $id = null): UserCardEntityInterface;
87
88    /**
89     * Delete library card.
90     *
91     * @param UserEntityInterface         $user     User owning card to delete
92     * @param UserCardEntityInterface|int $userCard UserCard id or object to be deleted
93     *
94     * @return bool
95     * @throws \Exception
96     */
97    public function deleteLibraryCard(UserEntityInterface $user, UserCardEntityInterface|int $userCard): bool;
98
99    /**
100     * Persist the provided library card data, either by updating a specified card
101     * or by creating a new one (when $card is null). Also updates the primary user
102     * row when appropriate. Will throw an exception if a duplicate $username value
103     * is provided; there should only be one card row per username.
104     *
105     * Returns the row that was added or updated.
106     *
107     * @param UserEntityInterface|int          $userOrId User object or identifier
108     * @param UserCardEntityInterface|int|null $cardOrId Card ID (null = create new)
109     * @param string                           $cardName Card name
110     * @param string                           $username Username
111     * @param string                           $password Password
112     * @param string                           $homeLib  Home Library
113     *
114     * @return UserCardEntityInterface
115     * @throws \VuFind\Exception\LibraryCard
116     */
117    public function persistLibraryCardData(
118        UserEntityInterface|int $userOrId,
119        UserCardEntityInterface|int|null $cardOrId,
120        string $cardName,
121        string $username,
122        string $password,
123        string $homeLib = ''
124    ): UserCardEntityInterface;
125
126    /**
127     * Verify that the user's current ILS settings exist in their library card data
128     * (if enabled) and are up to date. Designed to be called after updating the
129     * user row; will create or modify library card rows as needed.
130     *
131     * @param UserEntityInterface|int $userOrId User object or identifier
132     *
133     * @return bool
134     * @throws \VuFind\Exception\PasswordSecurity
135     */
136    public function synchronizeUserLibraryCardData(UserEntityInterface|int $userOrId): bool;
137
138    /**
139     * Activate a library card for the given username.
140     *
141     * @param UserEntityInterface|int $userOrId User owning card
142     * @param int                     $id       Library card ID to activate
143     *
144     * @return void
145     * @throws \VuFind\Exception\LibraryCard
146     */
147    public function activateLibraryCard(UserEntityInterface|int $userOrId, int $id): void;
148
149    /**
150     * Create a UserCard entity object.
151     *
152     * @return UserCardEntityInterface
153     */
154    public function createEntity(): UserCardEntityInterface;
155}