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
54	/**
55	* Map block types to strings, to allow convenient logging.
56	*/
57	public const BLOCK_TYPES = [
58	self::TYPE_USER => 'user',
59	self::TYPE_IP => 'ip',
60	self::TYPE_RANGE => 'range',
61	self::TYPE_AUTO => 'autoblock',
62	];
63
64	/**
65	* Get the block ID
66	*
67	* @param string|false $wikiId (since 1.38)
68	* @return ?int
69	*/
70	public function getId( $wikiId = self::LOCAL ): ?int;
71
72	/**
73	* Get the information that identifies this block, such that a user could
74	* look up everything that can be found about this block. Typically a scalar ID (integer
75	* or string), but can also return a list of IDs, or an associative array encoding a composite
76	* ID. Must be safe to serialize as JSON.
77	*
78	* @param string|false $wikiId (since 1.38)
79	* @return mixed Identifying information
80	*/
81	public function getIdentifier( $wikiId = self::LOCAL );
82
83	/**
84	* Get the user who applied this block
85	*
86	* @return UserIdentity|null user identity or null. May be an external user.
87	*/
88	public function getBlocker(): ?UserIdentity;
89
90	/**
91	* Get the reason for creating the block.
92	*
93	* @return CommentStoreComment
94	*/
95	public function getReasonComment(): CommentStoreComment;
96
97	/**
98	* Get the target as an object.
99	*
100	* For autoblocks this can be either the IP address or the autoblock ID
101	* depending on how the block was loaded. Use getRedactedTarget() to safely
102	* get a target for display.
103	*
104	* @since 1.44
105	* @return BlockTarget|null
106	*/
107	public function getTarget(): ?BlockTarget;
108
109	/**
110	* Get the target, with the IP address hidden behind an AutoBlockTarget
111	* if the block is an autoblock.
112	*
113	* @since 1.44
114	* @return BlockTarget|null
115	*/
116	public function getRedactedTarget(): ?BlockTarget;
117
118	/**
119	* Get the UserIdentity identifying the blocked user,
120	* if the target is indeed a user (that is, if getType() returns TYPE_USER).
121	*
122	* @return ?UserIdentity
123	*/
124	public function getTargetUserIdentity(): ?UserIdentity;
125
126	/**
127	* Return the name of the block target as a string.
128	* Depending on the type returned by getType(), this could be a user name,
129	* an IP address or range, an internal ID, etc.
130	*
131	* @return string
132	*/
133	public function getTargetName(): string;
134
135	/**
136	* Determine whether this block is blocking the given target (and only that target).
137	*
138	* @param UserIdentity|string $target
139	*
140	* @return bool
141	*/
142	public function isBlocking( $target ): bool;
143
144	/**
145	* Get the block expiry time
146	*
147	* @return string
148	*/
149	public function getExpiry(): string;
150
151	/**
152	* Is the block indefinite (with no fixed expiry)?
153	*
154	* @since 1.44
155	* @return bool
156	*/
157	public function isIndefinite(): bool;
158
159	/**
160	* Get the type of target for this particular block.
161	* @return int|null Block::TYPE_ constant
162	*/
163	public function getType(): ?int;
164
165	/**
166	* Get the timestamp indicating when the block was created
167	*
168	* @return string
169	*/
170	public function getTimestamp(): string;
171
172	/**
173	* Get whether the block is a sitewide block. This means the user is
174	* prohibited from editing any page on the site (other than their own talk
175	* page).
176	*
177	* @return bool
178	*/
179	public function isSitewide(): bool;
180
181	/**
182	* Get the flag indicating whether this block blocks the target from
183	* creating an account. (Note that the flag may be overridden depending on
184	* global configs.)
185	*
186	* @return bool
187	*/
188	public function isCreateAccountBlocked(): bool;
189
190	/**
191	* Get whether the block is a hard block (affects logged-in users on a given IP/range).
192	*
193	* Note that temporary users are not considered logged-in here - they are always blocked
194	* by IP-address blocks.
195	*
196	* Note that user blocks are always hard blocks, since the target is logged in by definition.
197	*
198	* @return bool
199	*/
200	public function isHardblock(): bool;
201
202	/**
203	* Convert a block to an array of blocks. If the block is a composite
204	* block, return the array of original blocks. Otherwise, return [$this].
205	*
206	* @since 1.41
207	* @return Block[]
208	*/
209	public function toArray(): array;
210	}