MediaWiki  master
FormSpecialPage.php
Go to the documentation of this file.
1 <?php
25 
33 abstract class FormSpecialPage extends SpecialPage {
38  protected $par = null;
39 
44  protected $reauthPostData = null;
45 
50  abstract protected function getFormFields();
51 
57  protected function preHtml() {
58  return '';
59  }
60 
66  protected function postHtml() {
67  return '';
68  }
69 
75  protected function preText() {
76  return $this->preHtml();
77  }
78 
84  protected function postText() {
85  return $this->postHtml();
86  }
87 
92  protected function alterForm( HTMLForm $form ) {
93  }
94 
101  protected function getMessagePrefix() {
102  return strtolower( $this->getName() );
103  }
104 
111  protected function getDisplayFormat() {
112  return 'table';
113  }
114 
119  protected function getForm() {
120  $context = $this->getContext();
121  $onSubmit = [ $this, 'onSubmit' ];
122 
123  if ( $this->reauthPostData ) {
124  // Restore POST data
125  $context = new DerivativeContext( $context );
126  $oldRequest = $this->getRequest();
127  $context->setRequest( new DerivativeRequest(
128  $oldRequest, $this->reauthPostData + $oldRequest->getQueryValues(), true
129  ) );
130 
131  // But don't treat it as a "real" submission just in case of some
132  // crazy kind of CSRF.
133  $onSubmit = static function () {
134  return false;
135  };
136  }
137 
138  $form = HTMLForm::factory(
139  $this->getDisplayFormat(),
140  $this->getFormFields(),
141  $context,
142  $this->getMessagePrefix()
143  );
144  if ( !$this->requiresPost() ) {
145  $form->setMethod( 'get' );
146  }
147  $form->setSubmitCallback( $onSubmit );
148  if ( $this->getDisplayFormat() !== 'ooui' ) {
149  // No legend and wrapper by default in OOUI forms, but can be set manually
150  // from alterForm()
151  $form->setWrapperLegendMsg( $this->getMessagePrefix() . '-legend' );
152  }
153 
154  $headerMsg = $this->msg( $this->getMessagePrefix() . '-text' );
155  if ( !$headerMsg->isDisabled() ) {
156  $form->addHeaderText( $headerMsg->parseAsBlock() );
157  }
158 
159  // preText / postText are deprecated, but we need to keep calling them until the end of
160  // the deprecation process so a subclass overriding *Text and *Html both work
161  $form->addPreText( $this->preText() );
162  $form->addPostText( $this->postText() );
163 
164  // Give precedence to subpage syntax
165  $field = $this->getSubpageField();
166  if ( $this->par && $field ) {
167  $this->getRequest()->setVal( $form->getField( $field )->getName(), $this->par );
168  $form->setTitle( $this->getPageTitle() );
169  }
170  $this->alterForm( $form );
171  if ( $form->getMethod() == 'post' ) {
172  // Retain query parameters (uselang etc) on POST requests
173  $params = array_diff_key(
174  $this->getRequest()->getQueryValues(), [ 'title' => null ] );
175  $form->addHiddenField( 'redirectparams', wfArrayToCgi( $params ) );
176  }
177 
178  // Give hooks a chance to alter the form, adding extra fields or text etc
179  $this->getHookRunner()->onSpecialPageBeforeFormDisplay( $this->getName(), $form );
180 
181  return $form;
182  }
183 
193  abstract public function onSubmit( array $data /* HTMLForm $form = null */ );
194 
200  public function onSuccess() {
201  }
202 
208  public function execute( $par ) {
209  $this->setParameter( $par );
210  $this->setHeaders();
211  $this->outputHeader();
212 
213  // This will throw exceptions if there's a problem
214  $this->checkExecutePermissions( $this->getUser() );
215 
216  $securityLevel = $this->getLoginSecurityLevel();
217  if ( $securityLevel !== false && !$this->checkLoginSecurityLevel( $securityLevel ) ) {
218  return;
219  }
220 
221  $form = $this->getForm();
222  // GET forms can be set as includable
223  if ( !$this->including() ) {
224  $result = $this->getShowAlways() ? $form->showAlways() : $form->show();
225  } else {
226  $result = $form->prepareForm()->tryAuthorizedSubmit();
227  }
228  if ( $result === true || ( $result instanceof Status && $result->isGood() ) ) {
229  $this->onSuccess();
230  }
231  }
232 
238  protected function getShowAlways() {
239  return false;
240  }
241 
246  protected function setParameter( $par ) {
247  $this->par = $par;
248  }
249 
255  protected function getSubpageField() {
256  return false;
257  }
258 
265  protected function checkExecutePermissions( User $user ) {
266  $this->checkPermissions();
267 
268  if ( $this->requiresUnblock() ) {
269  $block = $user->getBlock();
270  if ( $block && $block->isSitewide() ) {
271  throw new UserBlockedError(
272  $block,
273  $user,
274  $this->getLanguage(),
275  $this->getRequest()->getIP()
276  );
277  }
278  }
279 
280  if ( $this->requiresWrite() ) {
281  $this->checkReadOnly();
282  }
283  }
284 
290  public function requiresPost() {
291  return true;
292  }
293 
298  public function requiresWrite() {
299  return $this->requiresPost();
300  }
301 
306  public function requiresUnblock() {
307  return $this->requiresPost();
308  }
309 
316  protected function setReauthPostData( array $data ) {
317  $this->reauthPostData = $data;
318  }
319 }
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 ...
Special page which uses an HTMLForm to handle processing.
string null $par
The sub-page of the special page.
array null $reauthPostData
POST data preserved across re-authentication.
getMessagePrefix()
Get message prefix for HTMLForm.
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.
getForm()
Get the HTMLForm to control behavior.
preText()
Add pre-text to the form.
alterForm(HTMLForm $form)
Play with the HTMLForm if you need to more substantially.
postText()
Add post-text to the form.
getDisplayFormat()
Get display format for the form.
preHtml()
Add pre-HTML to the form.
onSubmit(array $data)
Process the form on submission.
setReauthPostData(array $data)
Preserve POST data across reauthentication.
checkExecutePermissions(User $user)
Called from execute() to check if the given user can perform this action.
getSubpageField()
Override this function to set the field name used in the subpage syntax.
requiresUnblock()
Whether this action cannot be executed by a blocked user, default to requiresPost()
getShowAlways()
Whether the form should always be shown despite the success of submission.
postHtml()
Add post-HTML to the form.
getFormFields()
Get an HTMLForm descriptor array.
setParameter( $par)
Maybe do something interesting with the subpage parameter.
requiresWrite()
Whether this action requires the wiki not to be locked, default to requiresPost()
execute( $par)
Basic SpecialPage workflow: get a form, send it to the user; get some data back,.
Object handling generic submission, CSRF protection, layout and other logic for UI forms in a reusabl...
Definition: HTMLForm.php:155
static factory( $displayFormat, $descriptor, IContextSource $context, $messagePrefix='')
Construct a HTMLForm object for given display type.
Definition: HTMLForm.php:354
Similar to MediaWiki\Request\FauxRequest, but only fakes URL parameters and method (POST or GET) and ...
Parent class for all special pages.
Definition: SpecialPage.php:45
outputHeader( $summaryMessageKey='')
Outputs a summary message on top of special pages Per default the message key is the canonical name o...
getName()
Get the name of this Special Page.
setHeaders()
Sets headers - this should be called from the execute() method of all derived classes!
checkLoginSecurityLevel( $level=null)
Verifies that the user meets the security level, possibly reauthenticating them in the process.
getUser()
Shortcut to get the User executing this instance.
checkPermissions()
Checks if userCanExecute, and if not throws a PermissionsError.
getContext()
Gets the context this SpecialPage is executed in.
msg( $key,... $params)
Wrapper around wfMessage that sets the current context.
getRequest()
Get the WebRequest being used for this instance.
checkReadOnly()
If the wiki is currently in readonly mode, throws a ReadOnlyError.
getPageTitle( $subpage=false)
Get a self-referential title object.
getLanguage()
Shortcut to get user's language.
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.
isGood()
Returns whether the operation completed and didn't have any error or warnings.
Generic operation result class Has warning/error list, boolean status and arbitrary value.
Definition: Status.php:46
Show an error when the user tries to do something whilst blocked.
The User object encapsulates all of the user-specific settings (user_id, name, rights,...
Definition: User.php:71
getBlock( $freshness=self::READ_NORMAL, $disableIpBlockExemptChecking=false)
Get the block affecting the user, or null if the user is not blocked.
Definition: User.php:1525