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
103  $context = new DerivativeContext( $context );
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  $this->getHookRunner()->onSpecialPageBeforeFormDisplay( $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 }
FormSpecialPage\onSuccess
onSuccess()
Do something exciting on successful processing of the form, most likely to show a confirmation messag...
Definition: FormSpecialPage.php:166
DerivativeRequest
Similar to FauxRequest, but only fakes URL parameters and method (POST or GET) and use the base reque...
Definition: DerivativeRequest.php:36
FormSpecialPage\getFormFields
getFormFields()
Get an HTMLForm descriptor array.
FormSpecialPage\alterForm
alterForm(HTMLForm $form)
Play with the HTMLForm if you need to more substantially.
Definition: FormSpecialPage.php:70
SpecialPage\msg
msg( $key,... $params)
Wrapper around wfMessage that sets the current context.
Definition: SpecialPage.php:828
FormSpecialPage\requiresUnblock
requiresUnblock()
Whether this action cannot be executed by a blocked user.
Definition: FormSpecialPage.php:238
FormSpecialPage\onSubmit
onSubmit(array $data)
Process the form on POST submission.
FormSpecialPage\getForm
getForm()
Get the HTMLForm to control behavior.
Definition: FormSpecialPage.php:97
UserBlockedError
Show an error when the user tries to do something whilst blocked.
Definition: UserBlockedError.php:31
SpecialPage\checkPermissions
checkPermissions()
Checks if userCanExecute, and if not throws a PermissionsError.
Definition: SpecialPage.php:343
FormSpecialPage\requiresWrite
requiresWrite()
Whether this action requires the wiki not to be locked.
Definition: FormSpecialPage.php:230
FormSpecialPage\setParameter
setParameter( $par)
Maybe do something interesting with the subpage parameter.
Definition: FormSpecialPage.php:196
FormSpecialPage
Special page which uses an HTMLForm to handle processing.
Definition: FormSpecialPage.php:31
FormSpecialPage\preText
preText()
Add pre-text to the form.
Definition: FormSpecialPage.php:54
SpecialPage\getLanguage
getLanguage()
Shortcut to get user's language.
Definition: SpecialPage.php:774
SpecialPage\getName
getName()
Get the name of this Special Page.
Definition: SpecialPage.php:164
FormSpecialPage\postText
postText()
Add post-text to the form.
Definition: FormSpecialPage.php:62
FormSpecialPage\getMessagePrefix
getMessagePrefix()
Get message prefix for HTMLForm.
Definition: FormSpecialPage.php:79
DerivativeContext
An IContextSource implementation which will inherit context from another source but allow individual ...
Definition: DerivativeContext.php:31
SpecialPage\getHookRunner
getHookRunner()
Definition: SpecialPage.php:1010
FormSpecialPage\$reauthPostData
array null $reauthPostData
POST data preserved across re-authentication.
Definition: FormSpecialPage.php:42
SpecialPage\checkLoginSecurityLevel
checkLoginSecurityLevel( $level=null)
Verifies that the user meets the security level, possibly reauthenticating them in the process.
Definition: SpecialPage.php:436
FormSpecialPage\checkExecutePermissions
checkExecutePermissions(User $user)
Called from execute() to check if the given user can perform this action.
Definition: FormSpecialPage.php:206
FormSpecialPage\execute
execute( $par)
Basic SpecialPage workflow: get a form, send it to the user; get some data back,.
Definition: FormSpecialPage.php:174
SpecialPage\setHeaders
setHeaders()
Sets headers - this should be called from the execute() method of all derived classes!...
Definition: SpecialPage.php:571
SpecialPage\getUser
getUser()
Shortcut to get the User executing this instance.
Definition: SpecialPage.php:754
User\getBlock
getBlock( $fromReplica=true)
Get the block affecting the user, or null if the user is not blocked.
Definition: User.php:1922
SpecialPage\getContext
getContext()
Gets the context this SpecialPage is executed in.
Definition: SpecialPage.php:717
FormSpecialPage\$par
string null $par
The sub-page of the special page.
Definition: FormSpecialPage.php:36
FormSpecialPage\getDisplayFormat
getDisplayFormat()
Get display format for the form.
Definition: FormSpecialPage.php:89
SpecialPage
Parent class for all special pages.
Definition: SpecialPage.php:41
SpecialPage\getRequest
getRequest()
Get the WebRequest being used for this instance.
Definition: SpecialPage.php:734
SpecialPage\getLoginSecurityLevel
getLoginSecurityLevel()
Tells if the special page does something security-sensitive and needs extra defense against a stolen ...
Definition: SpecialPage.php:389
FormSpecialPage\setReauthPostData
setReauthPostData(array $data)
Preserve POST data across reauthentication.
Definition: FormSpecialPage.php:248
SpecialPage\checkReadOnly
checkReadOnly()
If the wiki is currently in readonly mode, throws a ReadOnlyError.
Definition: SpecialPage.php:356
User
The User object encapsulates all of the user-specific settings (user_id, name, rights,...
Definition: User.php:59
HTMLForm\factory
static factory( $displayFormat,... $arguments)
Construct a HTMLForm object for given display type.
Definition: HTMLForm.php:311
HTMLForm
Object handling generic submission, CSRF protection, layout and other logic for UI forms in a reusabl...
Definition: HTMLForm.php:133
wfArrayToCgi
wfArrayToCgi( $array1, $array2=null, $prefix='')
This function takes one or two arrays as input, and returns a CGI-style string, e....
Definition: GlobalFunctions.php:346