1	<?php
2	/**
3	* This program is free software; you can redistribute it and/or modify
4	* it under the terms of the GNU General Public License as published by
5	* the Free Software Foundation; either version 2 of the License, or
6	* (at your option) any later version.
7	*
8	* This program is distributed in the hope that it will be useful,
9	* but WITHOUT ANY WARRANTY; without even the implied warranty of
10	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11	* GNU General Public License for more details.
12	*
13	* You should have received a copy of the GNU General Public License along
14	* with this program; if not, write to the Free Software Foundation, Inc.,
15	* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
16	* http://www.gnu.org/copyleft/gpl.html
17	*
18	* @file
19	*/
20
21	namespace MediaWiki\Permissions;
22
23	use IDBAccessObject;
24	use MediaWiki\Block\Block;
25	use MediaWiki\Page\PageIdentity;
26	use MediaWiki\User\UserIdentity;
27
28	/**
29	* This interface represents the authority associated with the current execution context,
30	* such as a web request. The authority determines which actions can or cannot be performed
31	* within that execution context.
32	*
33	* See the individual implementations for information on how that authority is determined.
34	*
35	* @since 1.36
36	*/
37	interface Authority {
38
39	/**
40	* @var int Fetch information quickly, slightly stale data is acceptable.
41	* @see IDBAccessObject::READ_NORMAL
42	*/
43	public const READ_NORMAL = IDBAccessObject::READ_NORMAL;
44
45	/**
46	* @var int Fetch information reliably, stale data is not acceptable.
47	* @see IDBAccessObject::READ_LATEST
48	*/
49	public const READ_LATEST = IDBAccessObject::READ_LATEST;
50
51	/**
52	* Returns the performer of the actions associated with this authority.
53	*
54	* Actions performed under this authority should generally be attributed
55	* to the user identity returned by this method.
56	*
57	* @return UserIdentity
58	*/
59	public function getUser(): UserIdentity;
60
61	/**
62	* Returns any user block affecting the Authority.
63	*
64	* @param int $freshness Indicates whether slightly stale data is acceptable in,
65	*        exchange for a fast response.
66	*
67	* @return ?Block
68	* @since 1.37
69	*/
70	public function getBlock( int $freshness = IDBAccessObject::READ_NORMAL ): ?Block;
71
72	/**
73	* Checks whether this authority has the given permission in general.
74	* For some permissions, exceptions may exist, both positive and negative, on a per-target basis.
75	* This method offers a fast, lightweight check, but may produce false positives.
76	* It is intended for determining which UI elements should be offered to the user.
77	*
78	* This method will not apply rate limit checks or evaluate user blocks.
79	*
80	* @param string $permission
81	* @param PermissionStatus|null $status
82	*
83	* @return bool
84	* @see isDefinitelyAllowed
85	*
86	* @see probablyCan
87	*/
88	public function isAllowed( string $permission, PermissionStatus $status = null ): bool;
89
90	/**
91	* Checks whether this authority has any of the given permissions in general.
92	*
93	* Implementations must ensure that this method returns true if isAllowed would return true
94	* for any of the given permissions. Calling isAllowedAny() with one parameter must be
95	* equivalent to calling isAllowed(). Calling isAllowedAny() with no parameter is not allowed.
96	*
97	* @see isAllowed
98	*
99	* @param string ...$permissions Permissions to test. At least one must be given.
100	* @return bool True if user is allowed to perform *any* of the given actions
101	*/
102	public function isAllowedAny( ...$permissions ): bool;
103
104	/**
105	* Checks whether this authority has any of the given permissions in general.
106	*
107	* Implementations must ensure that this method returns false if isAllowed would return false
108	* for any of the given permissions. Calling isAllowedAll() with one parameter must be
109	* equivalent to calling isAllowed(). Calling isAllowedAny() with no parameter is not allowed.
110	*
111	* @see isAllowed
112	*
113	* @param string ...$permissions Permissions to test. At least one must be given.
114	* @return bool True if the user is allowed to perform *all* of the given actions
115	*/
116	public function isAllowedAll( ...$permissions ): bool;
117
118	/**
119	* Checks whether this authority can probably perform the given action on the given target page.
120	* This method offers a fast, lightweight check, but may produce false positives.
121	* It is intended for determining which UI elements should be offered to the user.
122	* This method will not apply rate limit checks or evaluate user blocks.
123	*
124	* @see definitelyCan
125	* @see isAllowed
126	*
127	* @param string $action
128	* @param PageIdentity $target
129	* @param PermissionStatus|null $status aggregator for failures
130	*
131	* @return bool
132	*/
133	public function probablyCan(
134	string $action,
135	PageIdentity $target,
136	PermissionStatus $status = null
137	): bool;
138
139	/**
140	* Checks whether this authority can perform the given action on the given target page.
141	* This method performs a thorough check, but does not protect against race conditions.
142	* It is intended to be used when a user is intending to perform an action, but has not
143	* yet committed to it. For example, when a user goes to the edit page of an article, this
144	* method may be used to determine whether the user should be presented with a warning and
145	* a read-only view instead.
146	*
147	* This method may apply rate limit checks and evaluate user blocks.
148	*
149	* @see probablyCan
150	* @see isDefinitelyAllowed
151	*
152	* @param string $action
153	* @param PageIdentity $target
154	* @param PermissionStatus|null $status aggregator for failures
155	*
156	* @return bool
157	*/
158	public function definitelyCan(
159	string $action,
160	PageIdentity $target,
161	PermissionStatus $status = null
162	): bool;
163
164	/**
165	* Checks whether this authority is allowed to perform the given action.
166	* This method performs a thorough check, but does not protect against race conditions.
167	* It is intended to be used when a user is intending to perform an action, but has not
168	* yet committed to it. For example, when a user visits their preferences page, this
169	* method may be used to determine whether the user should have the option to change their
170	* email address.
171	*
172	* This method may apply rate limit checks and evaluate user blocks.
173	*
174	* @since 1.41
175	*
176	* @see isAllowed
177	* @see definitelyCan
178	*
179	* @param string $action
180	* @param PermissionStatus|null $status aggregator for failures
181	*
182	* @return bool
183	*/
184	public function isDefinitelyAllowed(
185	string $action,
186	PermissionStatus $status = null
187	): bool;
188
189	/**
190	* Authorize an action. This should be used immediately before performing the action.
191	*
192	* Calling this method may have non-trivial side-effects, such as incrementing a rate limit
193	* counter.
194	*
195	* @since 1.41
196	*
197	* @see isDefinitelyAllowed
198	* @see authorizeRead
199	* @see authorizeWrite
200	*
201	* @param string $action
202	* @param PermissionStatus|null $status aggregator for failures
203	*
204	* @return bool
205	*/
206	public function authorizeAction(
207	string $action,
208	PermissionStatus $status = null
209	): bool;
210
211	/**
212	* Authorize read access. This should be used immediately before performing read access on
213	* restricted information.
214	*
215	* Calling this method may have non-trivial side-effects, such as incrementing a rate limit
216	* counter.
217	*
218	* @param string $action
219	* @param PageIdentity $target
220	* @param PermissionStatus|null $status aggregator for failures
221	*
222	* @return bool If the user can perform the action
223	* @see authorizeAction
224	* @see authorizeWrite
225	*
226	* @see definitelyCan
227	*/
228	public function authorizeRead(
229	string $action,
230	PageIdentity $target,
231	PermissionStatus $status = null
232	): bool;
233
234	/**
235	* Authorize write access. This should be used immediately before updating
236	* persisted information.
237	*
238	* Calling this method may have non-trivial side-effects, such as incrementing a rate limit
239	* counter.
240	*
241	* @param string $action
242	* @param PageIdentity $target
243	* @param PermissionStatus|null $status aggregator for failures
244	*
245	* @return bool If the user can perform the action
246	* @see authorizeAction
247	* @see authorizeRead
248	*
249	* @see definitelyCan
250	*/
251	public function authorizeWrite(
252	string $action,
253	PageIdentity $target,
254	PermissionStatus $status = null
255	): bool;
256
257	/**
258	* Get whether the user is registered.
259	*
260	* @return bool
261	* @since 1.39
262	*/
263	public function isRegistered(): bool;
264
265	/**
266	* Is the user an autocreated temporary user?
267	*
268	* @since 1.39
269	* @return bool
270	*/
271	public function isTemp(): bool;
272
273	/**
274	* Is the user a normal non-temporary registered user?
275	*
276	* @since 1.39
277	* @return bool
278	*/
279	public function isNamed(): bool;
280	}