1	<?php
2
3	declare(strict_types=1);
4
5	namespace App\Modules\User\Domain\Repository;
6
7	use App\Modules\User\Domain\Model\User;
8
9	/**
10	* User Repository Contract Interface.
11	*
12	* Decouples domain logic from specific SQL database persistence implementation.
13	*
14	* @package App\Modules\User\Domain\Repository
15	*/
16	interface UserRepositoryInterface
17	{
18	/**
19	* Finds an active user by username or email address.
20	*
21	* @param string $usernameOrEmail Username or email string.
22	* @return User|null User entity if found, null otherwise.
23	*/
24	public function findByUsernameOrEmail(string $usernameOrEmail): ?User;
25
26	/**
27	* Finds an active user by primary ID.
28	*
29	* @param int $id Primary user identifier.
30	* @return User|null User entity if found, null otherwise.
31	*/
32	public function findById(int $id): ?User;
33
34	/**
35	* Inserts an audit log entry for an authentication attempt.
36	*
37	* @param int|null $userId User ID if identified, null otherwise.
38	* @param bool $status True for successful login, false for failure.
39	* @param int $failureReason Failure code from AuthFailureReason.
40	* @param string $ipAddress Client IP address.
41	* @param string|null $userAgent Client User-Agent string.
42	* @param string|null $httpProtocol HTTP protocol version.
43	* @return void
44	*/
45	public function logAuthAttempt(
46	?int $userId,
47	bool $status,
48	int $failureReason,
49	string $ipAddress,
50	?string $userAgent = null,
51	?string $httpProtocol = null
52	): void;
53	}