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 
55  protected function preHtml() {
56  return '';
57  }
58 
64  protected function postHtml() {
65  return '';
66  }
67 
73  protected function preText() {
74  return $this->preHtml();
75  }
76 
82  protected function postText() {
83  return $this->postHtml();
84  }
85 
90  protected function alterForm( HTMLForm $form ) {
91  }
92 
99  protected function getMessagePrefix() {
100  return strtolower( $this->getName() );
101  }
102 
109  protected function getDisplayFormat() {
110  return 'table';
111  }
112 
117  protected function getForm() {
118  $context = $this->getContext();
119  $onSubmit = [ $this, 'onSubmit' ];
120 
121  if ( $this->reauthPostData ) {
122  // Restore POST data
123  $context = new DerivativeContext( $context );
124  $oldRequest = $this->getRequest();
125  $context->setRequest( new DerivativeRequest(
126  $oldRequest, $this->reauthPostData + $oldRequest->getQueryValues(), true
127  ) );
128 
129  // But don't treat it as a "real" submission just in case of some
130  // crazy kind of CSRF.
131  $onSubmit = static function () {
132  return false;
133  };
134  }
135 
136  $form = HTMLForm::factory(
137  $this->getDisplayFormat(),
138  $this->getFormFields(),
139  $context,
140  $this->getMessagePrefix()
141  );
142  $form->setSubmitCallback( $onSubmit );
143  if ( $this->getDisplayFormat() !== 'ooui' ) {
144  // No legend and wrapper by default in OOUI forms, but can be set manually
145  // from alterForm()
146  $form->setWrapperLegendMsg( $this->getMessagePrefix() . '-legend' );
147  }
148 
149  $headerMsg = $this->msg( $this->getMessagePrefix() . '-text' );
150  if ( !$headerMsg->isDisabled() ) {
151  $form->addHeaderText( $headerMsg->parseAsBlock() );
152  }
153 
154  // preText / postText are deprecated, but we need to keep calling them until the end of
155  // the deprecation process so a subclass overriding *Text and *Html both work
156  $form->addPreText( $this->preText() );
157  $form->addPostText( $this->postText() );
158  $this->alterForm( $form );
159  if ( $form->getMethod() == 'post' ) {
160  // Retain query parameters (uselang etc) on POST requests
161  $params = array_diff_key(
162  $this->getRequest()->getQueryValues(), [ 'title' => null ] );
163  $form->addHiddenField( 'redirectparams', wfArrayToCgi( $params ) );
164  }
165 
166  // Give hooks a chance to alter the form, adding extra fields or text etc
167  $this->getHookRunner()->onSpecialPageBeforeFormDisplay( $this->getName(), $form );
168 
169  return $form;
170  }
171 
181  abstract public function onSubmit( array $data /* HTMLForm $form = null */ );
182 
188  public function onSuccess() {
189  }
190 
196  public function execute( $par ) {
197  $this->setParameter( $par );
198  $this->setHeaders();
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  if ( $form->show() ) {
210  $this->onSuccess();
211  }
212  }
213 
218  protected function setParameter( $par ) {
219  $this->par = $par;
220  }
221 
228  protected function checkExecutePermissions( User $user ) {
229  $this->checkPermissions();
230 
231  if ( $this->requiresUnblock() ) {
232  $block = $user->getBlock();
233  if ( $block && $block->isSitewide() ) {
234  throw new UserBlockedError(
235  $block,
236  $user,
237  $this->getLanguage(),
238  $this->getRequest()->getIP()
239  );
240  }
241  }
242 
243  if ( $this->requiresWrite() ) {
244  $this->checkReadOnly();
245  }
246  }
247 
252  public function requiresWrite() {
253  return true;
254  }
255 
260  public function requiresUnblock() {
261  return true;
262  }
263 
270  protected function setReauthPostData( array $data ) {
271  $this->reauthPostData = $data;
272  }
273 }
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 ...
Similar to FauxRequest, but only fakes URL parameters and method (POST or GET) and use the base reque...
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...
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 POST 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.
requiresUnblock()
Whether this action cannot be executed by a blocked user.
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.
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:150
static factory( $displayFormat, $descriptor, IContextSource $context, $messagePrefix='')
Construct a HTMLForm object for given display type.
Definition: HTMLForm.php:338
Parent class for all special pages.
Definition: SpecialPage.php:44
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.
getLanguage()
Shortcut to get user's language.
getLoginSecurityLevel()
Tells if the special page does something security-sensitive and needs extra defense against a stolen ...
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:68
getBlock( $freshness=self::READ_NORMAL, $disableIpBlockExemptChecking=false)
Get the block affecting the user, or null if the user is not blocked.
Definition: User.php:1742