MediaWiki master
ApiUnblock.php
Go to the documentation of this file.
1<?php
34
41class ApiUnblock extends ApiBase {
42
45
46 private BlockPermissionCheckerFactory $permissionCheckerFactory;
47 private UnblockUserFactory $unblockUserFactory;
48 private UserIdentityLookup $userIdentityLookup;
49 private WatchedItemStoreInterface $watchedItemStore;
50
51 public function __construct(
52 ApiMain $main,
53 $action,
54 BlockPermissionCheckerFactory $permissionCheckerFactory,
55 UnblockUserFactory $unblockUserFactory,
56 UserIdentityLookup $userIdentityLookup,
57 WatchedItemStoreInterface $watchedItemStore,
58 WatchlistManager $watchlistManager,
59 UserOptionsLookup $userOptionsLookup
60 ) {
61 parent::__construct( $main, $action );
62
63 $this->permissionCheckerFactory = $permissionCheckerFactory;
64 $this->unblockUserFactory = $unblockUserFactory;
65 $this->userIdentityLookup = $userIdentityLookup;
66 $this->watchedItemStore = $watchedItemStore;
67
68 // Variables needed in ApiWatchlistTrait trait
69 $this->watchlistExpiryEnabled = $this->getConfig()->get( MainConfigNames::WatchlistExpiry );
70 $this->watchlistMaxDuration =
71 $this->getConfig()->get( MainConfigNames::WatchlistExpiryMaxDuration );
72 $this->watchlistManager = $watchlistManager;
73 $this->userOptionsLookup = $userOptionsLookup;
74 }
75
79 public function execute() {
80 $performer = $this->getUser();
82
83 $this->requireOnlyOneParameter( $params, 'id', 'user', 'userid' );
84
85 if ( !$this->getAuthority()->isAllowed( 'block' ) ) {
86 $this->dieWithError( 'apierror-permissiondenied-unblock', 'permissiondenied' );
87 }
88
89 if ( $params['userid'] !== null ) {
90 $identity = $this->userIdentityLookup->getUserIdentityByUserId( $params['userid'] );
91 if ( !$identity ) {
92 $this->dieWithError( [ 'apierror-nosuchuserid', $params['userid'] ], 'nosuchuserid' );
93 }
94 $params['user'] = $identity->getName();
95 }
96
97 $target = $params['id'] === null ? $params['user'] : "#{$params['id']}";
98
99 # T17810: blocked admins should have limited access here
100 $status = $this->permissionCheckerFactory
101 ->newBlockPermissionChecker(
102 $target,
103 $this->getAuthority()
104 )->checkBlockPermissions();
105 if ( $status !== true ) {
106 $this->dieWithError(
107 $status,
108 null,
109 // @phan-suppress-next-line PhanTypeMismatchArgumentNullable Block is checked and not null
110 [ 'blockinfo' => $this->getBlockDetails( $performer->getBlock() ) ]
111 );
112 }
113
114 $status = $this->unblockUserFactory->newUnblockUser(
115 $target,
116 $this->getAuthority(),
117 $params['reason'],
118 $params['tags'] ?? []
119 )->unblock();
120
121 if ( !$status->isOK() ) {
122 $this->dieStatus( $status );
123 }
124
125 $block = $status->getValue();
126 $targetType = $block->getType();
127 $targetName = $targetType === Block::TYPE_AUTO ? '' : $block->getTargetName();
128 $targetUserId = $block->getTargetUserIdentity() ? $block->getTargetUserIdentity()->getId() : 0;
129
130 $watchlistExpiry = $this->getExpiryFromParams( $params );
131 $watchuser = $params['watchuser'];
132 $userPage = Title::makeTitle( NS_USER, $targetName );
133 if ( $watchuser && $targetType !== Block::TYPE_RANGE && $targetType !== Block::TYPE_AUTO ) {
134 $this->setWatch( 'watch', $userPage, $this->getUser(), null, $watchlistExpiry );
135 } else {
136 $watchuser = false;
137 $watchlistExpiry = null;
138 }
139
140 $res = [
141 'id' => $block->getId(),
142 'user' => $targetName,
143 'userid' => $targetUserId,
144 'reason' => $params['reason'],
145 'watchuser' => $watchuser,
146 ];
147 if ( $watchlistExpiry !== null ) {
148 $res['watchlistexpiry'] = $this->getWatchlistExpiry(
149 $this->watchedItemStore,
150 $userPage,
151 $this->getUser()
152 );
153 }
154 $this->getResult()->addValue( null, $this->getModuleName(), $res );
155 }
156
157 public function mustBePosted() {
158 return true;
159 }
160
161 public function isWriteMode() {
162 return true;
163 }
164
165 public function getAllowedParams() {
166 $params = [
167 'id' => [
168 ParamValidator::PARAM_TYPE => 'integer',
169 ],
170 'user' => [
171 ParamValidator::PARAM_TYPE => 'user',
172 UserDef::PARAM_ALLOWED_USER_TYPES => [ 'name', 'ip', 'temp', 'cidr', 'id' ],
173 ],
174 'userid' => [
175 ParamValidator::PARAM_TYPE => 'integer',
176 ParamValidator::PARAM_DEPRECATED => true,
177 ],
178 'reason' => '',
179 'tags' => [
180 ParamValidator::PARAM_TYPE => 'tags',
181 ParamValidator::PARAM_ISMULTI => true,
182 ],
183 'watchuser' => false,
184 ];
185
186 // Params appear in the docs in the order they are defined,
187 // which is why this is here and not at the bottom.
188 // @todo Find better way to support insertion at arbitrary position
189 if ( $this->watchlistExpiryEnabled ) {
190 $params += [
191 'watchlistexpiry' => [
192 ParamValidator::PARAM_TYPE => 'expiry',
193 ExpiryDef::PARAM_MAX => $this->watchlistMaxDuration,
194 ExpiryDef::PARAM_USE_MAX => true,
195 ]
196 ];
197 }
198
199 return $params;
200 }
201
202 public function needsToken() {
203 return 'csrf';
204 }
205
206 protected function getExamplesMessages() {
207 return [
208 'action=unblock&id=105'
209 => 'apihelp-unblock-example-id',
210 'action=unblock&user=Bob&reason=Sorry%20Bob'
211 => 'apihelp-unblock-example-user',
212 ];
213 }
214
215 public function getHelpUrls() {
216 return 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Block';
217 }
218}
getExpiryFromParams(array $params)
Get formatted expiry from the given parameters, or null if no expiry was provided.
setWatch(string $watch, Title $title, User $user, ?string $userOption=null, ?string $expiry=null)
Set a watch (or unwatch) based the based on a watchlist parameter.
getWatchlistExpiry(WatchedItemStoreInterface $store, Title $title, UserIdentity $user)
Get existing expiry from the database.
const NS_USER
Definition Defines.php:66
array $params
The job parameters.
This abstract class implements many basic API functions, and is the base of all API classes.
Definition ApiBase.php:64
dieWithError( $msg, $code=null, $data=null, $httpCode=0)
Abort execution with an error.
Definition ApiBase.php:1533
requireOnlyOneParameter( $params,... $required)
Die if 0 or more than one of a certain set of parameters is set and not false.
Definition ApiBase.php:950
getResult()
Get the result object.
Definition ApiBase.php:671
extractRequestParams( $options=[])
Using getAllowedParams(), this function makes an array of the values provided by the user,...
Definition ApiBase.php:811
getModuleName()
Get the name of the module being executed by this instance.
Definition ApiBase.php:532
dieStatus(StatusValue $status)
Throw an ApiUsageException based on the Status object.
Definition ApiBase.php:1589
This is the main API class, used for both external and internal processing.
Definition ApiMain.php:65
API module that facilitates the unblocking of users.
isWriteMode()
Indicates whether this module requires write mode.
needsToken()
Returns the token type this module requires in order to execute.
execute()
Unblocks the specified user or provides the reason the unblock failed.
getHelpUrls()
Return links to more detailed help pages about the module.
getAllowedParams()
Returns an array of allowed parameters (parameter name) => (default value) or (parameter name) => (ar...
mustBePosted()
Indicates whether this module must be called with a POST request.
__construct(ApiMain $main, $action, BlockPermissionCheckerFactory $permissionCheckerFactory, UnblockUserFactory $unblockUserFactory, UserIdentityLookup $userIdentityLookup, WatchedItemStoreInterface $watchedItemStore, WatchlistManager $watchlistManager, UserOptionsLookup $userOptionsLookup)
getExamplesMessages()
Returns usage examples for this module.
A class containing constants representing the names of configuration variables.
Type definition for user types.
Definition UserDef.php:27
Represents a title within MediaWiki.
Definition Title.php:78
Provides access to user options.
Service for formatting and validating API parameters.
Type definition for expiry timestamps.
Definition ExpiryDef.php:17
trait ApiBlockInfoTrait
trait ApiWatchlistTrait
An ApiWatchlistTrait adds class properties and convenience methods for APIs that allow you to watch a...
Represents a block that may prevent users from performing specific operations.
Definition Block.php:45