Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
15.19% covered (danger)
15.19%
12 / 79
5.56% covered (danger)
5.56%
1 / 18
CRAP
0.00% covered (danger)
0.00%
0 / 1
FormSpecialPage
15.38% covered (danger)
15.38%
12 / 78
5.56% covered (danger)
5.56%
1 / 18
821.15
0.00% covered (danger)
0.00%
0 / 1
 getFormFields
n/a
0 / 0
n/a
0 / 0
0
 preHtml
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
2
 postHtml
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
2
 preText
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
2
 postText
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
2
 alterForm
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
2
 getMessagePrefix
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
2
 getDisplayFormat
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
2
 getForm
0.00% covered (danger)
0.00%
0 / 38
0.00% covered (danger)
0.00%
0 / 1
72
 onSubmit
n/a
0 / 0
n/a
0 / 0
0
 onSuccess
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
2
 execute
0.00% covered (danger)
0.00%
0 / 13
0.00% covered (danger)
0.00%
0 / 1
72
 getShowAlways
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
2
 setParameter
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
2
 getSubpageField
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
2
 checkExecutePermissions
100.00% covered (success)
100.00%
12 / 12
100.00% covered (success)
100.00%
1 / 1
5
 requiresPost
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
2
 requiresWrite
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
2
 requiresUnblock
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
2
 setReauthPostData
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
2
1<?php
2/**
3 * Special page which uses an HTMLForm to handle processing.
4 *
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or
8 * (at your option) any later version.
9 *
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
14 *
15 * You should have received a copy of the GNU General Public License along
16 * with this program; if not, write to the Free Software Foundation, Inc.,
17 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18 * http://www.gnu.org/copyleft/gpl.html
19 *
20 * @file
21 * @ingroup SpecialPage
22 */
23
24namespace MediaWiki\SpecialPage;
25
26use MediaWiki\Context\DerivativeContext;
27use MediaWiki\HTMLForm\HTMLForm;
28use MediaWiki\Request\DerivativeRequest;
29use MediaWiki\Status\Status;
30use MediaWiki\User\User;
31use UserBlockedError;
32
33/**
34 * Special page which uses an HTMLForm to handle processing.  This is mostly a
35 * clone of FormAction.  More special pages should be built this way; maybe this could be
36 * a new structure for SpecialPages.
37 *
38 * @ingroup SpecialPage
39 */
40abstract class FormSpecialPage extends SpecialPage {
41    /**
42     * The sub-page of the special page.
43     * @var string|null
44     */
45    protected $par = null;
46
47    /**
48     * @var array|null POST data preserved across re-authentication
49     * @since 1.32
50     */
51    protected $reauthPostData = null;
52
53    /**
54     * Get an HTMLForm descriptor array
55     * @return array
56     */
57    abstract protected function getFormFields();
58
59    /**
60     * Add pre-HTML to the form
61     * @return string HTML which will be sent to $form->addPreHtml()
62     * @since 1.38
63     */
64    protected function preHtml() {
65        return '';
66    }
67
68    /**
69     * Add post-HTML to the form
70     * @return string HTML which will be sent to $form->addPostHtml()
71     * @since 1.38
72     */
73    protected function postHtml() {
74        return '';
75    }
76
77    /**
78     * Add pre-text to the form
79     * @return string HTML which will be sent to $form->addPreHtml()
80     * @deprecated since 1.38, use preHtml() instead
81     */
82    protected function preText() {
83        return $this->preHtml();
84    }
85
86    /**
87     * Add post-text to the form
88     * @return string HTML which will be sent to $form->addPostHtml()
89     * @deprecated since 1.38, use postHtml() instead
90     */
91    protected function postText() {
92        return $this->postHtml();
93    }
94
95    /**
96     * Play with the HTMLForm if you need to more substantially
97     * @param HTMLForm $form
98     */
99    protected function alterForm( HTMLForm $form ) {
100    }
101
102    /**
103     * Get message prefix for HTMLForm
104     *
105     * @since 1.21
106     * @return string
107     */
108    protected function getMessagePrefix() {
109        return strtolower( $this->getName() );
110    }
111
112    /**
113     * Get display format for the form. See HTMLForm documentation for available values.
114     *
115     * @since 1.25
116     * @return string
117     */
118    protected function getDisplayFormat() {
119        return 'table';
120    }
121
122    /**
123     * Get the HTMLForm to control behavior
124     * @return HTMLForm|null
125     */
126    protected function getForm() {
127        $context = $this->getContext();
128        $onSubmit = [ $this, 'onSubmit' ];
129
130        if ( $this->reauthPostData ) {
131            // Restore POST data
132            $context = new DerivativeContext( $context );
133            $oldRequest = $this->getRequest();
134            $context->setRequest( new DerivativeRequest(
135                $oldRequest, $this->reauthPostData + $oldRequest->getQueryValues(), true
136            ) );
137
138            // But don't treat it as a "real" submission just in case of some
139            // crazy kind of CSRF.
140            $onSubmit = static function () {
141                return false;
142            };
143        }
144
145        $form = HTMLForm::factory(
146            $this->getDisplayFormat(),
147            $this->getFormFields(),
148            $context,
149            $this->getMessagePrefix()
150        );
151        if ( !$this->requiresPost() ) {
152            $form->setMethod( 'get' );
153        }
154        $form->setSubmitCallback( $onSubmit );
155        if ( $this->getDisplayFormat() !== 'ooui' ) {
156            // No legend and wrapper by default in OOUI forms, but can be set manually
157            // from alterForm()
158            $form->setWrapperLegendMsg( $this->getMessagePrefix() . '-legend' );
159        }
160
161        $headerMsg = $this->msg( $this->getMessagePrefix() . '-text' );
162        if ( !$headerMsg->isDisabled() ) {
163            $form->addHeaderHtml( $headerMsg->parseAsBlock() );
164        }
165
166        // preText / postText are deprecated, but we need to keep calling them until the end of
167        // the deprecation process so a subclass overriding *Text and *Html both work
168        $form->addPreHtml( $this->preText() );
169        $form->addPostHtml( $this->postText() );
170
171        // Give precedence to subpage syntax
172        $field = $this->getSubpageField();
173        // cast to string so that "0" is not thrown away
174        if ( strval( $this->par ) !== '' && $field ) {
175            $this->getRequest()->setVal( $form->getField( $field )->getName(), $this->par );
176            $form->setTitle( $this->getPageTitle() );
177        }
178        $this->alterForm( $form );
179        if ( $form->getMethod() == 'post' ) {
180            // Retain query parameters (uselang etc) on POST requests
181            $params = array_diff_key(
182                $this->getRequest()->getQueryValues(), [ 'title' => null ] );
183            $form->addHiddenField( 'redirectparams', wfArrayToCgi( $params ) );
184        }
185
186        // Give hooks a chance to alter the form, adding extra fields or text etc
187        $this->getHookRunner()->onSpecialPageBeforeFormDisplay( $this->getName(), $form );
188
189        return $form;
190    }
191
192    /**
193     * Process the form on submission.
194     * @phpcs:disable MediaWiki.Commenting.FunctionComment.ExtraParamComment
195     * @param array $data
196     * @param HTMLForm|null $form
197     * @suppress PhanCommentParamWithoutRealParam Many implementations don't have $form
198     * @return bool|string|array|Status As documented for HTMLForm::trySubmit.
199     * @phpcs:enable MediaWiki.Commenting.FunctionComment.ExtraParamComment
200     */
201    abstract public function onSubmit( array $data /* HTMLForm $form = null */ );
202
203    /**
204     * Do something exciting on successful processing of the form, most likely to show a
205     * confirmation message
206     * @since 1.22 Default is to do nothing
207     */
208    public function onSuccess() {
209    }
210
211    /**
212     * Basic SpecialPage workflow: get a form, send it to the user; get some data back,
213     *
214     * @param string|null $par Subpage string if one was specified
215     */
216    public function execute( $par ) {
217        $this->setParameter( $par );
218        $this->setHeaders();
219        $this->outputHeader();
220
221        // This will throw exceptions if there's a problem
222        $this->checkExecutePermissions( $this->getUser() );
223
224        $securityLevel = $this->getLoginSecurityLevel();
225        if ( $securityLevel !== false && !$this->checkLoginSecurityLevel( $securityLevel ) ) {
226            return;
227        }
228
229        $form = $this->getForm();
230        // GET forms can be set as includable
231        if ( !$this->including() ) {
232            $result = $this->getShowAlways() ? $form->showAlways() : $form->show();
233        } else {
234            $result = $form->prepareForm()->tryAuthorizedSubmit();
235        }
236        if ( $result === true || ( $result instanceof Status && $result->isGood() ) ) {
237            $this->onSuccess();
238        }
239    }
240
241    /**
242     * Whether the form should always be shown despite the success of submission.
243     * @since 1.40
244     * @return bool
245     */
246    protected function getShowAlways() {
247        return false;
248    }
249
250    /**
251     * Maybe do something interesting with the subpage parameter
252     * @param string|null $par
253     */
254    protected function setParameter( $par ) {
255        $this->par = $par;
256    }
257
258    /**
259     * Override this function to set the field name used in the subpage syntax.
260     * @since 1.40
261     * @return false|string
262     */
263    protected function getSubpageField() {
264        return false;
265    }
266
267    /**
268     * Called from execute() to check if the given user can perform this action.
269     * Failures here must throw subclasses of ErrorPageError.
270     * @param User $user
271     * @throws UserBlockedError
272     */
273    protected function checkExecutePermissions( User $user ) {
274        $this->checkPermissions();
275
276        if ( $this->requiresUnblock() ) {
277            $block = $user->getBlock();
278            if ( $block && $block->isSitewide() ) {
279                throw new UserBlockedError(
280                    $block,
281                    $user,
282                    $this->getLanguage(),
283                    $this->getRequest()->getIP()
284                );
285            }
286        }
287
288        if ( $this->requiresWrite() ) {
289            $this->checkReadOnly();
290        }
291    }
292
293    /**
294     * Whether this action should using POST method to submit, default to true
295     * @since 1.40
296     * @return bool
297     */
298    public function requiresPost() {
299        return true;
300    }
301
302    /**
303     * Whether this action requires the wiki not to be locked, default to requiresPost()
304     * @return bool
305     */
306    public function requiresWrite() {
307        return $this->requiresPost();
308    }
309
310    /**
311     * Whether this action cannot be executed by a blocked user, default to requiresPost()
312     * @return bool
313     */
314    public function requiresUnblock() {
315        return $this->requiresPost();
316    }
317
318    /**
319     * Preserve POST data across reauthentication
320     *
321     * @since 1.32
322     * @param array $data
323     */
324    protected function setReauthPostData( array $data ) {
325        $this->reauthPostData = $data;
326    }
327}
328
329/** @deprecated class alias since 1.41 */
330class_alias( FormSpecialPage::class, 'FormSpecialPage' );