MediaWiki master
FormSpecialPage.php
Go to the documentation of this file.
1<?php
24namespace MediaWiki\SpecialPage;
25
32
40abstract class FormSpecialPage extends SpecialPage {
45 protected $par = null;
46
51 protected $reauthPostData = null;
52
57 abstract protected function getFormFields();
58
64 protected function preHtml() {
65 return '';
66 }
67
73 protected function postHtml() {
74 return '';
75 }
76
80 protected function alterForm( HTMLForm $form ) {
81 }
82
89 protected function getMessagePrefix() {
90 return strtolower( $this->getName() );
91 }
92
99 protected function getDisplayFormat() {
100 return 'table';
101 }
102
107 protected function getForm() {
108 $context = $this->getContext();
109 $onSubmit = [ $this, 'onSubmit' ];
110
111 if ( $this->reauthPostData ) {
112 // Restore POST data
113 $context = new DerivativeContext( $context );
114 $oldRequest = $this->getRequest();
115 $context->setRequest( new DerivativeRequest(
116 $oldRequest, $this->reauthPostData + $oldRequest->getQueryValues(), true
117 ) );
118
119 // But don't treat it as a "real" submission just in case of some
120 // crazy kind of CSRF.
121 $onSubmit = static function () {
122 return false;
123 };
124 }
125
126 $form = HTMLForm::factory(
127 $this->getDisplayFormat(),
128 $this->getFormFields(),
129 $context,
130 $this->getMessagePrefix()
131 );
132 if ( !$this->requiresPost() ) {
133 $form->setMethod( 'get' );
134 }
135 $form->setSubmitCallback( $onSubmit );
136 if ( $this->getDisplayFormat() !== 'ooui' ) {
137 // No legend and wrapper by default in OOUI forms, but can be set manually
138 // from alterForm()
139 $form->setWrapperLegendMsg( $this->getMessagePrefix() . '-legend' );
140 }
141
142 $headerMsg = $this->msg( $this->getMessagePrefix() . '-text' );
143 if ( !$headerMsg->isDisabled() ) {
144 $form->addHeaderHtml( $headerMsg->parseAsBlock() );
145 }
146
147 $form->addPreHtml( $this->preHtml() );
148 $form->addPostHtml( $this->postHtml() );
149
150 // Give precedence to subpage syntax
151 $field = $this->getSubpageField();
152 // cast to string so that "0" is not thrown away
153 if ( strval( $this->par ) !== '' && $field ) {
154 $this->getRequest()->setVal( $form->getField( $field )->getName(), $this->par );
155 $form->setTitle( $this->getPageTitle() );
156 }
157 $this->alterForm( $form );
158 if ( $form->getMethod() == 'post' ) {
159 // Retain query parameters (uselang etc) on POST requests
160 $params = array_diff_key(
161 $this->getRequest()->getQueryValues(), [ 'title' => null ] );
162 $form->addHiddenField( 'redirectparams', wfArrayToCgi( $params ) );
163 }
164
165 // Give hooks a chance to alter the form, adding extra fields or text etc
166 $this->getHookRunner()->onSpecialPageBeforeFormDisplay( $this->getName(), $form );
167
168 return $form;
169 }
170
180 abstract public function onSubmit( array $data /* HTMLForm $form = null */ );
181
187 public function onSuccess() {
188 }
189
195 public function execute( $par ) {
196 $this->setParameter( $par );
197 $this->setHeaders();
198 $this->outputHeader();
199
200 // This will throw exceptions if there's a problem
201 $this->checkExecutePermissions( $this->getUser() );
202
203 $securityLevel = $this->getLoginSecurityLevel();
204 if ( $securityLevel !== false && !$this->checkLoginSecurityLevel( $securityLevel ) ) {
205 return;
206 }
207
208 $form = $this->getForm();
209 // GET forms can be set as includable
210 if ( !$this->including() ) {
211 $result = $this->getShowAlways() ? $form->showAlways() : $form->show();
212 } else {
213 $result = $form->prepareForm()->tryAuthorizedSubmit();
214 }
215 if ( $result === true || ( $result instanceof Status && $result->isGood() ) ) {
216 $this->onSuccess();
217 }
218 }
219
225 protected function getShowAlways() {
226 return false;
227 }
228
233 protected function setParameter( $par ) {
234 $this->par = $par;
235 }
236
242 protected function getSubpageField() {
243 return false;
244 }
245
252 protected function checkExecutePermissions( User $user ) {
253 $this->checkPermissions();
254
255 if ( $this->requiresUnblock() ) {
256 $block = $user->getBlock();
257 if ( $block && $block->isSitewide() ) {
258 throw new UserBlockedError(
259 $block,
260 $user,
261 $this->getLanguage(),
262 $this->getRequest()->getIP()
263 );
264 }
265 }
266
267 if ( $this->requiresWrite() ) {
268 $this->checkReadOnly();
269 }
270 }
271
277 public function requiresPost() {
278 return true;
279 }
280
285 public function requiresWrite() {
286 return $this->requiresPost();
287 }
288
293 public function requiresUnblock() {
294 return $this->requiresPost();
295 }
296
303 protected function setReauthPostData( array $data ) {
304 $this->reauthPostData = $data;
305 }
306}
307
309class_alias( FormSpecialPage::class, 'FormSpecialPage' );
wfArrayToCgi( $array1, $array2=null, $prefix='')
This function takes one or two arrays as input, and returns a CGI-style string, e....
An IContextSource implementation which will inherit context from another source but allow individual ...
Show an error when the user tries to do something whilst blocked.
Object handling generic submission, CSRF protection, layout and other logic for UI forms in a reusabl...
Definition HTMLForm.php:209
Similar to MediaWiki\Request\FauxRequest, but only fakes URL parameters and method (POST or GET) and ...
Special page which uses an HTMLForm to handle processing.
getMessagePrefix()
Get message prefix for HTMLForm.
requiresUnblock()
Whether this action cannot be executed by a blocked user, default to requiresPost()
onSuccess()
Do something exciting on successful processing of the form, most likely to show a confirmation messag...
requiresPost()
Whether this action should using POST method to submit, default to true.
getShowAlways()
Whether the form should always be shown despite the success of submission.
getForm()
Get the HTMLForm to control behavior.
setParameter( $par)
Maybe do something interesting with the subpage parameter.
execute( $par)
Basic SpecialPage workflow: get a form, send it to the user; get some data back,.
requiresWrite()
Whether this action requires the wiki not to be locked, default to requiresPost()
alterForm(HTMLForm $form)
Play with the HTMLForm if you need to more substantially.
setReauthPostData(array $data)
Preserve POST data across reauthentication.
string null $par
The subpage of the special page.
array null $reauthPostData
POST data preserved across re-authentication.
getSubpageField()
Override this function to set the field name used in the subpage syntax.
checkExecutePermissions(User $user)
Called from execute() to check if the given user can perform this action.
getFormFields()
Get an HTMLForm descriptor array.
preHtml()
Add pre-HTML to the form.
onSubmit(array $data)
Process the form on submission.
getDisplayFormat()
Get display format for the form.
postHtml()
Add post-HTML to the form.
Parent class for all special pages.
setHeaders()
Sets headers - this should be called from the execute() method of all derived classes!
getUser()
Shortcut to get the User executing this instance.
getPageTitle( $subpage=false)
Get a self-referential title object.
checkPermissions()
Checks if userCanExecute, and if not throws a PermissionsError.
checkReadOnly()
If the wiki is currently in readonly mode, throws a ReadOnlyError.
getContext()
Gets the context this SpecialPage is executed in.
getRequest()
Get the WebRequest being used for this instance.
msg( $key,... $params)
Wrapper around wfMessage that sets the current context.
getLoginSecurityLevel()
Tells if the special page does something security-sensitive and needs extra defense against a stolen ...
including( $x=null)
Whether the special page is being evaluated via transclusion.
getLanguage()
Shortcut to get user's language.
outputHeader( $summaryMessageKey='')
Outputs a summary message on top of special pages By default the message key is the canonical name of...
getName()
Get the canonical, unlocalized name of this special page without namespace.
checkLoginSecurityLevel( $level=null)
Verifies that the user meets the security level, possibly reauthenticating them in the process.
Generic operation result class Has warning/error list, boolean status and arbitrary value.
Definition Status.php:54
User class for the MediaWiki software.
Definition User.php:123
getBlock( $freshness=IDBAccessObject::READ_NORMAL, $disableIpBlockExemptChecking=false)
Get the block affecting the user, or null if the user is not blocked.
Definition User.php:1464
isGood()
Returns whether the operation completed and didn't have any error or warnings.