FormSpecialPage.php

Go to the documentation of this file.

<?php
namespace MediaWiki\SpecialPage;
 
use MediaWiki\Context\DerivativeContext;
use MediaWiki\Exception\UserBlockedError;
use MediaWiki\HTMLForm\HTMLForm;
use MediaWiki\Request\DerivativeRequest;
use MediaWiki\Status\Status;
use MediaWiki\User\User;
use StatusValue;
 
abstract class FormSpecialPage extends SpecialPage {
    protected $par = null;
 
    protected $reauthPostData = null;
 
    abstract protected function getFormFields();
 
    protected function preHtml() {
        return '';
    }
 
    protected function postHtml() {
        return '';
    }
 
    protected function alterForm( HTMLForm $form ) {
    }
 
    protected function getMessagePrefix() {
        return strtolower( $this->getName() );
    }
 
    protected function getDisplayFormat() {
        return 'table';
    }
 
    protected function getForm() {
        $context = $this->getContext();
        $onSubmit = $this->onSubmit( ... );
 
        if ( $this->reauthPostData ) {
            // Restore POST data
            $context = new DerivativeContext( $context );
            $oldRequest = $this->getRequest();
            $context->setRequest( new DerivativeRequest(
                $oldRequest, $this->reauthPostData + $oldRequest->getQueryValues(), true
            ) );
 
            // But don't treat it as a "real" submission just in case of some
            // crazy kind of CSRF.
            $onSubmit = static fn () => false;
        }
 
        $form = HTMLForm::factory(
            $this->getDisplayFormat(),
            $this->getFormFields(),
            $context,
            $this->getMessagePrefix()
        );
        if ( !$this->requiresPost() ) {
            $form->setMethod( 'get' );
        }
        $form->setSubmitCallback( $onSubmit );
        if ( $this->getDisplayFormat() !== 'ooui' ) {
            // No legend and wrapper by default in OOUI forms, but can be set manually
            // from alterForm()
            $form->setWrapperLegendMsg( $this->getMessagePrefix() . '-legend' );
        }
 
        $headerMsg = $this->msg( $this->getMessagePrefix() . '-text' );
        if ( !$headerMsg->isDisabled() ) {
            $form->addHeaderHtml( $headerMsg->parseAsBlock() );
        }
 
        $form->addPreHtml( $this->preHtml() );
        $form->addPostHtml( $this->postHtml() );
 
        // Give precedence to subpage syntax
        $field = $this->getSubpageField();
        // cast to string so that "0" is not thrown away
        if ( strval( $this->par ) !== '' && $field ) {
            $this->getRequest()->setVal( $form->getField( $field )->getName(), $this->par );
            $form->setTitle( $this->getPageTitle() );
        }
        $this->alterForm( $form );
        if ( $form->getMethod() == 'post' ) {
            // Retain query parameters (uselang etc) on POST requests
            $params = array_diff_key(
                $this->getRequest()->getQueryValues(), [ 'title' => null ] );
            $form->addHiddenField( 'redirectparams', wfArrayToCgi( $params ) );
        }
 
        // Give hooks a chance to alter the form, adding extra fields or text etc
        $this->getHookRunner()->onSpecialPageBeforeFormDisplay( $this->getName(), $form );
 
        return $form;
    }
 
    abstract public function onSubmit( array $data /* HTMLForm $form = null */ );
 
    public function onSuccess() {
    }
 
    public function execute( $par ) {
        $this->setParameter( $par );
        $this->setHeaders();
        $this->outputHeader();
 
        // This will throw exceptions if there's a problem
        $this->checkExecutePermissions( $this->getUser() );
 
        $securityLevel = $this->getLoginSecurityLevel();
        if ( $securityLevel !== false && !$this->checkLoginSecurityLevel( $securityLevel ) ) {
            return;
        }
 
        $form = $this->getForm();
        // GET forms can be set as includable
        if ( !$this->including() ) {
            $result = $this->getShowAlways() ? $form->showAlways() : $form->show();
        } else {
            $result = $form->prepareForm()->tryAuthorizedSubmit();
        }
        if ( $result === true || ( $result instanceof StatusValue && $result->isGood() ) ) {
            $this->onSuccess();
        }
    }
 
    protected function getShowAlways() {
        return false;
    }
 
    protected function setParameter( $par ) {
        $this->par = $par;
    }
 
    protected function getSubpageField() {
        return false;
    }
 
    protected function checkExecutePermissions( User $user ) {
        $this->checkPermissions();
 
        if ( $this->requiresUnblock() ) {
            $block = $user->getBlock();
            if ( $block && $block->isSitewide() ) {
                throw new UserBlockedError(
                    $block,
                    $user,
                    $this->getLanguage(),
                    $this->getRequest()->getIP()
                );
            }
        }
 
        if ( $this->requiresWrite() ) {
            $this->checkReadOnly();
        }
    }
 
    public function requiresPost() {
        return true;
    }
 
    public function requiresWrite() {
        return $this->requiresPost();
    }
 
    public function requiresUnblock() {
        return $this->requiresPost();
    }
 
    protected function setReauthPostData( array $data ) {
        $this->reauthPostData = $data;
    }
}
 
class_alias( FormSpecialPage::class, 'FormSpecialPage' );