Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
100.00%
1 / 1
n/a
0 / 0
 CRAP
n/a
0 / 0
1<?php
2
3declare(strict_types=1);
4
5/** @license For full copyright and license information, please see the LICENSE.md file. */
6
7namespace App\Modules\User\Domain\Repository;
8
9defined('AMMONLY_APP') || exit('Direct script access is forbidden.');
10
11use App\Modules\User\Domain\Model\User;
12
13/**
14 * User Repository Contract Interface.
15 *
16 * Decouples domain logic from specific SQL database persistence implementation.
17 *
18 * @package App\Modules\User\Domain\Repository
19 */
20interface UserRepositoryInterface
21{
22    /**
23     * Finds an active user by username or email address.
24     *
25     * @param string $usernameOrEmail Username or email string.
26     * @return User|null User entity if found, null otherwise.
27     */
28    public function findByUsernameOrEmail(string $usernameOrEmail): ?User;
29
30    /**
31     * Finds an active user by primary ID.
32     *
33     * @param int $id Primary user identifier.
34     * @return User|null User entity if found, null otherwise.
35     */
36    public function findById(int $id): ?User;
37
38    /**
39     * Searches active users for autocomplete suggestions by username or email.
40     *
41     * @param string $query Partial search string.
42     * @param int $limit Maximum number of matches to return.
43     * @return array<int, array{id: int, username: string, email: string, label: string}> Matching user items.
44     */
45    public function searchAutocomplete(string $query, int $limit = 10): array;
46
47    /**
48     * Finds multiple active users by their primary identifiers.
49     *
50     * @param array<int, int> $ids Array of user identifiers.
51     * @return array<int, array{id: int, username: string, email: string, is_superuser: bool, label: string}> Users.
52     */
53    public function findUsersByIds(array $ids): array;
54
55    /**
56     * Retrieves list of all active users ordered by username.
57     *
58     * @param int $limit Maximum number of users to retrieve.
59     * @return array<int, array{id: int, username: string, email: string, is_superuser: bool, label: string}> Users.
60     */
61    public function getActiveUsers(int $limit = 200): array;
62
63    /**
64     * Inserts an audit log entry for an authentication attempt.
65     *
66     * @param \App\Modules\User\Domain\Model\AuthAttemptLog $attempt Authentication attempt value object.
67     * @return int Inserted log record ID.
68     */
69    public function logAuthAttempt(\App\Modules\User\Domain\Model\AuthAttemptLog $attempt): int;
70
71    /**
72     * Updates preferred locale for a user account.
73     *
74     * @param int $userId Primary user ID.
75     * @param string $locale Language code (e.g. 'en', 'pl').
76     * @return bool True if updated successfully.
77     */
78    public function updateLocale(int $userId, string $locale): bool;
79
80    /**
81     * Counts recent failed login attempts from a given IP address within a time window.
82     *
83     * @param string $ipAddress Client IP address.
84     * @param int $windowSeconds Time window in seconds (default: 900 = 15 minutes).
85     * @return int Number of failed attempts within the window.
86     */
87    public function countRecentFailedAttempts(string $ipAddress, int $windowSeconds = 900): int;
88
89    /**
90     * Counts recent failed login attempts for a given username or email within a time window.
91     *
92     * @param string $loginIdentifier Candidate username or email string.
93     * @param int    $windowSeconds   Time window in seconds (default: 900 = 15 minutes).
94     * @return int Number of failed attempts within the window.
95     */
96    public function countRecentFailedAttemptsByLogin(string $loginIdentifier, int $windowSeconds = 900): int;
97
98    /**
99     * Updates password hash for a user account.
100     *
101     * @param int $userId Primary user ID.
102     * @param string $passwordHash Hashed password string.
103     * @return bool True if updated successfully.
104     */
105    public function updatePassword(int $userId, string $passwordHash): bool;
106
107    /**
108     * Fetches detailed profile data for a user account.
109     *
110     * @param int $userId Primary user ID.
111     * @return array<string, mixed>|null Associative array of user profile columns or null if not found.
112     */
113    public function getUserProfile(int $userId): ?array;
114
115    /**
116     * Updates avatar URL for a user account.
117     *
118     * @param int $userId Primary user ID.
119     * @param string $avatarUrl Avatar URL or asset path.
120     * @return bool True if updated successfully.
121     */
122    public function updateAvatar(int $userId, string $avatarUrl): bool;
123
124    /**
125     * Retrieves active sessions for a user account.
126     *
127     * @param int $userId Primary user ID.
128     * @return array<int, array<string, mixed>> List of active session records.
129     */
130    public function getUserActiveSessions(int $userId): array;
131
132
133
134    /**
135     * Revokes a specific active session belonging to a user.
136     *
137     * @param int $userId Primary user ID.
138     * @param int $sessionId Primary session record ID.
139     * @return bool True if session existed and was revoked.
140     */
141    public function revokeUserSession(int $userId, int $sessionId): bool;
142
143    /**
144     * Revokes all other active sessions for a user except the current session token.
145     *
146     * @param int $userId Primary user ID.
147     * @param string $currentSessionToken Current session ID string.
148     * @return int Number of revoked sessions.
149     */
150    public function revokeOtherUserSessions(int $userId, string $currentSessionToken): int;
151}
152
153