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  $form->setSubmitCallback( $onSubmit );
145  if ( $this->getDisplayFormat() !== 'ooui' ) {
146  // No legend and wrapper by default in OOUI forms, but can be set manually
147  // from alterForm()
148  $form->setWrapperLegendMsg( $this->getMessagePrefix() . '-legend' );
149  }
150 
151  $headerMsg = $this->msg( $this->getMessagePrefix() . '-text' );
152  if ( !$headerMsg->isDisabled() ) {
153  $form->addHeaderText( $headerMsg->parseAsBlock() );
154  }
155 
156  // preText / postText are deprecated, but we need to keep calling them until the end of
157  // the deprecation process so a subclass overriding *Text and *Html both work
158  $form->addPreText( $this->preText() );
159  $form->addPostText( $this->postText() );
160  $this->alterForm( $form );
161  if ( $form->getMethod() == 'post' ) {
162  // Retain query parameters (uselang etc) on POST requests
163  $params = array_diff_key(
164  $this->getRequest()->getQueryValues(), [ 'title' => null ] );
165  $form->addHiddenField( 'redirectparams', wfArrayToCgi( $params ) );
166  }
167 
168  // Give hooks a chance to alter the form, adding extra fields or text etc
169  $this->getHookRunner()->onSpecialPageBeforeFormDisplay( $this->getName(), $form );
170 
171  return $form;
172  }
173 
183  abstract public function onSubmit( array $data /* HTMLForm $form = null */ );
184 
190  public function onSuccess() {
191  }
192 
198  public function execute( $par ) {
199  $this->setParameter( $par );
200  $this->setHeaders();
201 
202  // This will throw exceptions if there's a problem
203  $this->checkExecutePermissions( $this->getUser() );
204 
205  $securityLevel = $this->getLoginSecurityLevel();
206  if ( $securityLevel !== false && !$this->checkLoginSecurityLevel( $securityLevel ) ) {
207  return;
208  }
209 
210  $form = $this->getForm();
211  if ( $form->show() ) {
212  $this->onSuccess();
213  }
214  }
215 
220  protected function setParameter( $par ) {
221  $this->par = $par;
222  }
223 
230  protected function checkExecutePermissions( User $user ) {
231  $this->checkPermissions();
232 
233  if ( $this->requiresUnblock() ) {
234  $block = $user->getBlock();
235  if ( $block && $block->isSitewide() ) {
236  throw new UserBlockedError(
237  $block,
238  $user,
239  $this->getLanguage(),
240  $this->getRequest()->getIP()
241  );
242  }
243  }
244 
245  if ( $this->requiresWrite() ) {
246  $this->checkReadOnly();
247  }
248  }
249 
254  public function requiresWrite() {
255  return true;
256  }
257 
262  public function requiresUnblock() {
263  return true;
264  }
265 
272  protected function setReauthPostData( array $data ) {
273  $this->reauthPostData = $data;
274  }
275 }
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...
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:349
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: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:70
getBlock( $freshness=self::READ_NORMAL, $disableIpBlockExemptChecking=false)
Get the block affecting the user, or null if the user is not blocked.
Definition: User.php:1508