MediaWiki  master
FormSpecialPage.php
Go to the documentation of this file.
1 <?php
31 abstract class FormSpecialPage extends SpecialPage {
36  protected $par = null;
37 
42  protected $reauthPostData = null;
43 
48  abstract protected function getFormFields();
49 
54  protected function preText() {
55  return '';
56  }
57 
62  protected function postText() {
63  return '';
64  }
65 
70  protected function alterForm( HTMLForm $form ) {
71  }
72 
79  protected function getMessagePrefix() {
80  return strtolower( $this->getName() );
81  }
82 
89  protected function getDisplayFormat() {
90  return 'table';
91  }
92 
97  protected function getForm() {
98  $context = $this->getContext();
99  $onSubmit = [ $this, 'onSubmit' ];
100 
101  if ( $this->reauthPostData ) {
102  // Restore POST data
104  $oldRequest = $this->getRequest();
105  $context->setRequest( new DerivativeRequest(
106  $oldRequest, $this->reauthPostData + $oldRequest->getQueryValues(), true
107  ) );
108 
109  // But don't treat it as a "real" submission just in case of some
110  // crazy kind of CSRF.
111  $onSubmit = function () {
112  return false;
113  };
114  }
115 
116  $form = HTMLForm::factory(
117  $this->getDisplayFormat(),
118  $this->getFormFields(),
119  $context,
120  $this->getMessagePrefix()
121  );
122  $form->setSubmitCallback( $onSubmit );
123  if ( $this->getDisplayFormat() !== 'ooui' ) {
124  // No legend and wrapper by default in OOUI forms, but can be set manually
125  // from alterForm()
126  $form->setWrapperLegendMsg( $this->getMessagePrefix() . '-legend' );
127  }
128 
129  $headerMsg = $this->msg( $this->getMessagePrefix() . '-text' );
130  if ( !$headerMsg->isDisabled() ) {
131  $form->addHeaderText( $headerMsg->parseAsBlock() );
132  }
133 
134  $form->addPreText( $this->preText() );
135  $form->addPostText( $this->postText() );
136  $this->alterForm( $form );
137  if ( $form->getMethod() == 'post' ) {
138  // Retain query parameters (uselang etc) on POST requests
139  $params = array_diff_key(
140  $this->getRequest()->getQueryValues(), [ 'title' => null ] );
141  $form->addHiddenField( 'redirectparams', wfArrayToCgi( $params ) );
142  }
143 
144  // Give hooks a chance to alter the form, adding extra fields or text etc
145  Hooks::run( 'SpecialPageBeforeFormDisplay', [ $this->getName(), &$form ] );
146 
147  return $form;
148  }
149 
159  abstract public function onSubmit( array $data /* HTMLForm $form = null */ );
160 
166  public function onSuccess() {
167  }
168 
174  public function execute( $par ) {
175  $this->setParameter( $par );
176  $this->setHeaders();
177 
178  // This will throw exceptions if there's a problem
179  $this->checkExecutePermissions( $this->getUser() );
180 
181  $securityLevel = $this->getLoginSecurityLevel();
182  if ( $securityLevel !== false && !$this->checkLoginSecurityLevel( $securityLevel ) ) {
183  return;
184  }
185 
186  $form = $this->getForm();
187  if ( $form->show() ) {
188  $this->onSuccess();
189  }
190  }
191 
196  protected function setParameter( $par ) {
197  $this->par = $par;
198  }
199 
206  protected function checkExecutePermissions( User $user ) {
207  $this->checkPermissions();
208 
209  if ( $this->requiresUnblock() ) {
210  $block = $user->getBlock();
211  if ( $block && $block->isSitewide() ) {
212  throw new UserBlockedError(
213  $block,
214  $user,
215  $this->getLanguage(),
216  $this->getRequest()->getIP()
217  );
218  }
219  }
220 
221  if ( $this->requiresWrite() ) {
222  $this->checkReadOnly();
223  }
224  }
225 
230  public function requiresWrite() {
231  return true;
232  }
233 
238  public function requiresUnblock() {
239  return true;
240  }
241 
248  protected function setReauthPostData( array $data ) {
249  $this->reauthPostData = $data;
250  }
251 }
getLoginSecurityLevel()
Tells if the special page does something security-sensitive and needs extra defense against a stolen ...
$context
Definition: load.php:45
getContext()
Gets the context this SpecialPage is executed in.
setParameter( $par)
Maybe do something interesting with the subpage parameter.
array null $reauthPostData
POST data preserved across re-authentication.
preText()
Add pre-text to the form.
execute( $par)
Basic SpecialPage workflow: get a form, send it to the user; get some data back,. ...
onSubmit(array $data)
Process the form on POST submission.
An IContextSource implementation which will inherit context from another source but allow individual ...
Similar to FauxRequest, but only fakes URL parameters and method (POST or GET) and use the base reque...
getBlock( $fromReplica=true)
Get the block affecting the user, or null if the user is not blocked.
Definition: User.php:2065
getDisplayFormat()
Get display format for the form.
Special page which uses an HTMLForm to handle processing.
checkExecutePermissions(User $user)
Called from execute() to check if the given user can perform this action.
getFormFields()
Get an HTMLForm descriptor array.
alterForm(HTMLForm $form)
Play with the HTMLForm if you need to more substantially.
The User object encapsulates all of the user-specific settings (user_id, name, rights, email address, options, last login time).
Definition: User.php:51
wfArrayToCgi( $array1, $array2=null, $prefix='')
This function takes one or two arrays as input, and returns a CGI-style string, e.g.
msg( $key,... $params)
Wrapper around wfMessage that sets the current context.
static factory( $displayFormat,... $arguments)
Construct a HTMLForm object for given display type.
Definition: HTMLForm.php:307
postText()
Add post-text to the form.
setHeaders()
Sets headers - this should be called from the execute() method of all derived classes! ...
Show an error when the user tries to do something whilst blocked.
setReauthPostData(array $data)
Preserve POST data across reauthentication.
getMessagePrefix()
Get message prefix for HTMLForm.
string null $par
The sub-page of the special page.
getName()
Get the name of this Special Page.
requiresUnblock()
Whether this action cannot be executed by a blocked user.
getUser()
Shortcut to get the User executing this instance.
getForm()
Get the HTMLForm to control behavior.
getLanguage()
Shortcut to get user&#39;s language.
checkLoginSecurityLevel( $level=null)
Verifies that the user meets the security level, possibly reauthenticating them in the process...
checkPermissions()
Checks if userCanExecute, and if not throws a PermissionsError.
getRequest()
Get the WebRequest being used for this instance.
onSuccess()
Do something exciting on successful processing of the form, most likely to show a confirmation messag...
requiresWrite()
Whether this action requires the wiki not to be locked.
checkReadOnly()
If the wiki is currently in readonly mode, throws a ReadOnlyError.
return true
Definition: router.php:92
static run( $event, array $args=[], $deprecatedVersion=null)
Call hook functions defined in Hooks::register and $wgHooks.
Definition: Hooks.php:200