1	<?php
2
3	/**
4	* Interface for phpMyFAQ permission classes.
5	*
6	* This Source Code Form is subject to the terms of the Mozilla Public License,
7	* v. 2.0. If a copy of the MPL was not distributed with this file, You can
8	* obtain one at https://mozilla.org/MPL/2.0/.
9	*
10	* @package   phpMyFAQ
11	* @author    Thorsten Rinne <thorsten@phpmyfaq.de>
12	* @copyright 2022-2026 phpMyFAQ Team
13	* @license   https://www.mozilla.org/MPL/2.0/ Mozilla Public License Version 2.0
14	* @link      https://www.phpmyfaq.de
15	* @since     2022-12-23
16	*/
17
18	declare(strict_types=1);
19
20	namespace phpMyFAQ\Permission;
21
22	use phpMyFAQ\User\CurrentUser;
23
24	interface PermissionInterface
25	{
26	/**
27	* Returns true, if the user given by $userId owns the right
28	* specified by $right. It does not matter if the user owns this
29	* right as a user-right or because of a group-membership.
30	* The parameter $right may be a right-ID (recommended for
31	* performance) or a right-name.
32	*
33	* @param int   $userId User ID
34	* @param mixed $right  Rights
35	*/
36	public function hasPermission(int $userId, mixed $right): bool;
37
38	/**
39	* Gives the user a new user-right.
40	* Returns true on success, otherwise false.
41	*/
42	public function grantUserRight(int $userId, int $rightId): bool;
43
44	/**
45	* Returns an associative array with all data stored in the database
46	* for the specified right, keyed by field name.
47	*
48	* @return array<string, mixed>
49	*/
50	public function getRightData(int $rightId): array;
51
52	/**
53	* Returns the right-ID for the given right-name, or 0 if unknown.
54	*/
55	public function getRightId(string $name): int;
56
57	/**
58	* Returns true if the user owns the right given by ID as a direct
59	* user-right (group rights are not taken into account).
60	*/
61	public function checkUserRight(int $userId, int $rightId): bool;
62
63	/**
64	* Returns an array with the IDs of all rights the user owns.
65	*
66	* @return array<int>
67	*/
68	public function getAllUserRights(int $userId): array;
69
70	/**
71	* Returns the number of user-rights the given user owns.
72	*/
73	public function getUserRightsCount(CurrentUser $currentUser): int;
74
75	/**
76	* Returns an array with the IDs of all direct user-rights the user
77	* owns. Group rights are not taken into account.
78	*
79	* @return array<int>
80	*/
81	public function getUserRights(int $userId): array;
82
83	/**
84	* Adds a new right and returns its ID, or 0 when the right exists.
85	*
86	* @param array<string, mixed> $rightData
87	*/
88	public function addRight(array $rightData): int;
89
90	/**
91	* Validates the given right data, replacing missing or invalid
92	* fields with defaults.
93	*
94	* @param array<string, mixed> $rightData
95	* @return array<string, mixed>
96	*/
97	public function checkRightData(array $rightData): array;
98
99	/**
100	* Renames a right, only used for updates.
101	*/
102	public function renameRight(string $oldName, string $newName): bool;
103
104	/**
105	* Returns all rights stored in the database as complete right-data
106	* arrays.
107	*
108	* @return array<int, array>
109	*/
110	public function getAllRightsData(string $order = 'ASC'): array;
111
112	/**
113	* Refuses all user rights.
114	* Returns true on success, otherwise false.
115	*/
116	public function refuseAllUserRights(int $userId): bool;
117
118	/**
119	* Returns an array with the IDs of all groups the user belongs to;
120	* empty for permission levels without group support.
121	*
122	* @return array<int>
123	*/
124	public function getUserGroups(int $userId): array;
125	}