1	<?php
2
3	/**
4	* This program is free software; you can redistribute it and/or modify
5	* it under the terms of the GNU General Public License as published by
6	* the Free Software Foundation; either version 2 of the License, or
7	* (at your option) any later version.
8	*
9	* This program is distributed in the hope that it will be useful,
10	* but WITHOUT ANY WARRANTY; without even the implied warranty of
11	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12	* GNU General Public License for more details.
13	*
14	* You should have received a copy of the GNU General Public License along
15	* with this program; if not, write to the Free Software Foundation, Inc.,
16	* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
17	* http://www.gnu.org/copyleft/gpl.html
18	*
19	* @file
20	*/
21
22	namespace MediaWiki\Block;
23
24	use MediaWiki\CommentStore\CommentStoreComment;
25	use MediaWiki\DAO\WikiAwareEntity;
26	use MediaWiki\User\UserIdentity;
27
28	/**
29	* Represents a block that may prevent users from performing specific operations.
30	* The block may apply to a specific user, to a network address, network range,
31	* or some other aspect of a web request.
32	*
33	* The block may apply to the entire site, or may be limited to specific pages
34	* or namespaces.
35	*
36	* @since 1.37
37	*
38	* Extracted from the AbstractBlock base class, which was in turn factored out
39	* of DatabaseBlock in 1.34. Block was introduced as a narrow interface for
40	* Authority. It avoids legacy types such as User and Title. However, all
41	* implementations should continue to extend AbstractBlock.
42	*
43	* Extends WikiAwareEntity since 1.38.
44	*/
45	interface Block extends WikiAwareEntity {
46
47	# TYPE constants
48	# Do not introduce negative constants without changing BlockUser command object.
49	public const TYPE_USER = 1;
50	public const TYPE_IP = 2;
51	public const TYPE_RANGE = 3;
52	public const TYPE_AUTO = 4;
53	public const TYPE_ID = 5;
54
55	/**
56	* Map block types to strings, to allow convenient logging.
57	*/
58	public const BLOCK_TYPES = [
59	self::TYPE_USER => 'user',
60	self::TYPE_IP => 'ip',
61	self::TYPE_RANGE => 'range',
62	self::TYPE_AUTO => 'autoblock',
63	self::TYPE_ID => 'id',
64	];
65
66	/**
67	* Get the block ID
68	*
69	* @param string|false $wikiId (since 1.38)
70	* @return ?int
71	*/
72	public function getId( $wikiId = self::LOCAL ): ?int;
73
74	/**
75	* Get the information that identifies this block, such that a user could
76	* look up everything that can be found about this block. Typically a scalar ID (integer
77	* or string), but can also return a list of IDs, or an associative array encoding a composite
78	* ID. Must be safe to serialize as JSON.
79	*
80	* @param string|false $wikiId (since 1.38)
81	* @return mixed Identifying information
82	*/
83	public function getIdentifier( $wikiId = self::LOCAL );
84
85	/**
86	* Get the user who applied this block
87	*
88	* @return UserIdentity|null user identity or null. May be an external user.
89	*/
90	public function getBlocker(): ?UserIdentity;
91
92	/**
93	* Get the reason for creating the block.
94	*
95	* @return CommentStoreComment
96	*/
97	public function getReasonComment(): CommentStoreComment;
98
99	/**
100	* Get the UserIdentity identifying the blocked user,
101	* if the target is indeed a user (that is, if getType() returns TYPE_USER).
102	*
103	* @return ?UserIdentity
104	*/
105	public function getTargetUserIdentity(): ?UserIdentity;
106
107	/**
108	* Return the name of the block target as a string.
109	* Depending on the type returned by getType(), this could be a user name,
110	* an IP address or range, an internal ID, etc.
111	*
112	* @return string
113	*/
114	public function getTargetName(): string;
115
116	/**
117	* Determine whether this block is blocking the given target (and only that target).
118	*
119	* @param UserIdentity|string $target
120	*
121	* @return bool
122	*/
123	public function isBlocking( $target ): bool;
124
125	/**
126	* Get the block expiry time
127	*
128	* @return string
129	*/
130	public function getExpiry(): string;
131
132	/**
133	* Get the type of target for this particular block.
134	* @return int|null Block::TYPE_ constant, will never be TYPE_ID
135	*/
136	public function getType(): ?int;
137
138	/**
139	* Get the timestamp indicating when the block was created
140	*
141	* @return string
142	*/
143	public function getTimestamp(): string;
144
145	/**
146	* Get whether the block is a sitewide block. This means the user is
147	* prohibited from editing any page on the site (other than their own talk
148	* page).
149	*
150	* @return bool
151	*/
152	public function isSitewide(): bool;
153
154	/**
155	* Get the flag indicating whether this block blocks the target from
156	* creating an account. (Note that the flag may be overridden depending on
157	* global configs.)
158	*
159	* @return bool
160	*/
161	public function isCreateAccountBlocked(): bool;
162
163	/**
164	* Get whether the block is a hard block (affects logged-in users on a given IP/range).
165	*
166	* Note that temporary users are not considered logged-in here - they are always blocked
167	* by IP-address blocks.
168	*
169	* Note that user blocks are always hard blocks, since the target is logged in by definition.
170	*
171	* @return bool
172	*/
173	public function isHardblock(): bool;
174
175	/**
176	* Convert a block to an array of blocks. If the block is a composite
177	* block, return the array of original blocks. Otherwise, return [$this].
178	*
179	* @since 1.41
180	* @return Block[]
181	*/
182	public function toArray(): array;
183	}