SpecialPage.php

Go to the documentation of this file.

<?php
class SpecialPage {
    // The canonical name of this special page
    // Also used for the default <h1> heading, @see getDescription()
    protected $mName;

    // The local name of this special page
    private $mLocalName;

    // Minimum user level required to access this page, or "" for anyone.
    // Also used to categorise the pages in Special:Specialpages
    private $mRestriction;

    // Listed in Special:Specialpages?
    private $mListed;

    // Function name called by the default execute()
    private $mFunction;

    // File which needs to be included before the function above can be called
    private $mFile;

    // Whether or not this special page is being included from an article
    protected $mIncluding;

    // Whether the special page can be included in an article
    protected $mIncludable;

    protected $mContext;

    static function initList() {
        wfDeprecated( __METHOD__, '1.18' );
        // Noop
    }

    static function initAliasList() {
        wfDeprecated( __METHOD__, '1.18' );
        // Noop
    }

    static function resolveAlias( $alias ) {
        wfDeprecated( __METHOD__, '1.18' );
        list( $name, /*...*/ ) = SpecialPageFactory::resolveAlias( $alias );
        return $name;
    }

    static function resolveAliasWithSubpage( $alias ) {
        return SpecialPageFactory::resolveAlias( $alias );
    }

    static function setGroup( $page, $group ) {
        wfDeprecated( __METHOD__, '1.18' );
        SpecialPageFactory::setGroup( $page, $group );
    }

    static function getGroup( &$page ) {
        wfDeprecated( __METHOD__, '1.18' );
        return SpecialPageFactory::getGroup( $page );
    }

    static function removePage( $name ) {
        wfDeprecated( __METHOD__, '1.18' );
        unset( SpecialPageFactory::getList()->$name );
    }

    static function exists( $name ) {
        wfDeprecated( __METHOD__, '1.18' );
        return SpecialPageFactory::exists( $name );
    }

    static function getPage( $name ) {
        wfDeprecated( __METHOD__, '1.18' );
        return SpecialPageFactory::getPage( $name );
    }

    static function getPageByAlias( $alias ) {
        wfDeprecated( __METHOD__, '1.18' );
        return SpecialPageFactory::getPage( $alias );
    }

    static function getUsablePages( User $user = null ) {
        wfDeprecated( __METHOD__, '1.18' );
        return SpecialPageFactory::getUsablePages( $user );
    }

    static function getRegularPages() {
        wfDeprecated( __METHOD__, '1.18' );
        return SpecialPageFactory::getRegularPages();
    }

    static function getRestrictedPages() {
        wfDeprecated( __METHOD__, '1.18' );
        return SpecialPageFactory::getRestrictedPages();
    }

    public static function executePath( &$title, IContextSource &$context, $including = false ) {
        wfDeprecated( __METHOD__, '1.18' );
        return SpecialPageFactory::executePath( $title, $context, $including );
    }

    static function getLocalNameFor( $name, $subpage = false ) {
        wfDeprecated( __METHOD__, '1.18' );
        return SpecialPageFactory::getLocalNameFor( $name, $subpage );
    }

    public static function getTitleFor( $name, $subpage = false, $fragment = '' ) {
        $name = SpecialPageFactory::getLocalNameFor( $name, $subpage );
        if ( $name ) {
            return Title::makeTitle( NS_SPECIAL, $name, $fragment );
        } else {
            throw new MWException( "Invalid special page name \"$name\"" );
        }
    }

    public static function getSafeTitleFor( $name, $subpage = false ) {
        $name = SpecialPageFactory::getLocalNameFor( $name, $subpage );
        if ( $name ) {
            return Title::makeTitleSafe( NS_SPECIAL, $name );
        } else {
            return null;
        }
    }

    static function getTitleForAlias( $alias ) {
        wfDeprecated( __METHOD__, '1.18' );
        return SpecialPageFactory::getTitleForAlias( $alias );
    }

    public function __construct(
        $name = '', $restriction = '', $listed = true,
        $function = false, $file = 'default', $includable = false
    ) {
        $this->init( $name, $restriction, $listed, $function, $file, $includable );
    }

    private function init( $name, $restriction, $listed, $function, $file, $includable ) {
        $this->mName = $name;
        $this->mRestriction = $restriction;
        $this->mListed = $listed;
        $this->mIncludable = $includable;
        if ( !$function ) {
            $this->mFunction = 'wfSpecial' . $name;
        } else {
            $this->mFunction = $function;
        }
        if ( $file === 'default' ) {
            $this->mFile = __DIR__ . "/specials/Special$name.php";
        } else {
            $this->mFile = $file;
        }
    }

    public function __call( $fName, $a ) {
        // Deprecated messages now, remove in 1.19 or 1.20?
        wfDeprecated( __METHOD__, '1.17' );

        // Sometimes $fName is SpecialPage, sometimes it's specialpage. <3 PHP
        if ( strtolower( $fName ) == 'specialpage' ) {
            $name = isset( $a[0] ) ? $a[0] : '';
            $restriction = isset( $a[1] ) ? $a[1] : '';
            $listed = isset( $a[2] ) ? $a[2] : true;
            $function = isset( $a[3] ) ? $a[3] : false;
            $file = isset( $a[4] ) ? $a[4] : 'default';
            $includable = isset( $a[5] ) ? $a[5] : false;
            $this->init( $name, $restriction, $listed, $function, $file, $includable );
        } else {
            $className = get_class( $this );
            throw new MWException( "Call to undefined method $className::$fName" );
        }
    }

    function getName() {
        return $this->mName;
    }

    function getRestriction() {
        return $this->mRestriction;
    }

    function getFile() {
        wfDeprecated( __METHOD__, '1.18' );
        return $this->mFile;
    }

    // @todo FIXME: Decide which syntax to use for this, and stick to it
    function isListed() {
        return $this->mListed;
    }
    function setListed( $listed ) {
        return wfSetVar( $this->mListed, $listed );
    }
    function listed( $x = null ) {
        return wfSetVar( $this->mListed, $x );
    }

    public function isIncludable() {
        return $this->mIncludable;
    }

    function name( $x = null ) {
        wfDeprecated( __METHOD__, '1.18' );
        return wfSetVar( $this->mName, $x );
    }

    function restriction( $x = null ) {
        wfDeprecated( __METHOD__, '1.18' );
        return wfSetVar( $this->mRestriction, $x );
    }

    function func( $x = null ) {
        wfDeprecated( __METHOD__, '1.18' );
        return wfSetVar( $this->mFunction, $x );
    }

    function file( $x = null ) {
        wfDeprecated( __METHOD__, '1.18' );
        return wfSetVar( $this->mFile, $x );
    }

    function includable( $x = null ) {
        wfDeprecated( __METHOD__, '1.18' );
        return wfSetVar( $this->mIncludable, $x );
    }

    function including( $x = null ) {
        return wfSetVar( $this->mIncluding, $x );
    }

    function getLocalName() {
        if ( !isset( $this->mLocalName ) ) {
            $this->mLocalName = SpecialPageFactory::getLocalNameFor( $this->mName );
        }
        return $this->mLocalName;
    }

    public function isExpensive() {
        return false;
    }

    public function isCached() {
        return false;
    }

    public function isRestricted() {
        // DWIM: If anons can do something, then it is not restricted
        return $this->mRestriction != '' && !User::groupHasPermission( '*', $this->mRestriction );
    }

    public function userCanExecute( User $user ) {
        return $user->isAllowed( $this->mRestriction );
    }

    function displayRestrictionError() {
        throw new PermissionsError( $this->mRestriction );
    }

    public function checkPermissions() {
        if ( !$this->userCanExecute( $this->getUser() ) ) {
            $this->displayRestrictionError();
        }
    }

    public function checkReadOnly() {
        if ( wfReadOnly() ) {
            throw new ReadOnlyError;
        }
    }

    function setHeaders() {
        $out = $this->getOutput();
        $out->setArticleRelated( false );
        $out->setRobotPolicy( "noindex,nofollow" );
        $out->setPageTitle( $this->getDescription() );
    }

    final public function run( $subPage ) {
        wfRunHooks( 'SpecialPageBeforeExecute', array( $this, $subPage ) );

        $this->beforeExecute( $subPage );
        $this->execute( $subPage );
        $this->afterExecute( $subPage );

        wfRunHooks( 'SpecialPageAfterExecute', array( $this, $subPage ) );
    }

    protected function beforeExecute( $subPage ) {
        // No-op
    }

    protected function afterExecute( $subPage ) {
        // No-op
    }

    public function execute( $subPage ) {
        $this->setHeaders();
        $this->checkPermissions();

        $func = $this->mFunction;
        // only load file if the function does not exist
        if ( !is_callable( $func ) && $this->mFile ) {
            require_once $this->mFile;
        }
        $this->outputHeader();
        call_user_func( $func, $subPage, $this );
    }

    function outputHeader( $summaryMessageKey = '' ) {
        global $wgContLang;

        if ( $summaryMessageKey == '' ) {
            $msg = $wgContLang->lc( $this->getName() ) . '-summary';
        } else {
            $msg = $summaryMessageKey;
        }
        if ( !$this->msg( $msg )->isDisabled() && !$this->including() ) {
            $this->getOutput()->wrapWikiMsg(
                "<div class='mw-specialpage-summary'>\n$1\n</div>", $msg );
        }

    }

    function getDescription() {
        return $this->msg( strtolower( $this->mName ) )->text();
    }

    function getTitle( $subpage = false ) {
        return self::getTitleFor( $this->mName, $subpage );
    }

    public function setContext( $context ) {
        $this->mContext = $context;
    }

    public function getContext() {
        if ( $this->mContext instanceof IContextSource ) {
            return $this->mContext;
        } else {
            wfDebug( __METHOD__ . " called and \$mContext is null. " .
                "Return RequestContext::getMain(); for sanity\n" );
            return RequestContext::getMain();
        }
    }

    public function getRequest() {
        return $this->getContext()->getRequest();
    }

    public function getOutput() {
        return $this->getContext()->getOutput();
    }

    public function getUser() {
        return $this->getContext()->getUser();
    }

    public function getSkin() {
        return $this->getContext()->getSkin();
    }

    public function getLang() {
        wfDeprecated( __METHOD__, '1.19' );
        return $this->getLanguage();
    }

    public function getLanguage() {
        return $this->getContext()->getLanguage();
    }

    public function getFullTitle() {
        return $this->getContext()->getTitle();
    }

    public function msg( /* $args */ ) {
        // Note: can't use func_get_args() directly as second or later item in
        // a parameter list until PHP 5.3 or you get a fatal error.
        // Works fine as the first parameter, which appears elsewhere in the
        // code base. Sighhhh.
        $args = func_get_args();
        $message = call_user_func_array( array( $this->getContext(), 'msg' ), $args );
        // RequestContext passes context to wfMessage, and the language is set from
        // the context, but setting the language for Message class removes the
        // interface message status, which breaks for example usernameless gender
        // invocations. Restore the flag when not including special page in content.
        if ( $this->including() ) {
            $message->setInterfaceMessageFlag( false );
        }
        return $message;
    }

    protected function addFeedLinks( $params ) {
        global $wgFeedClasses;

        $feedTemplate = wfScript( 'api' );

        foreach ( $wgFeedClasses as $format => $class ) {
            $theseParams = $params + array( 'feedformat' => $format );
            $url = wfAppendQuery( $feedTemplate, $theseParams );
            $this->getOutput()->addFeedLink( $format, $url );
        }
    }

    public function getFinalGroupName() {
        global $wgSpecialPageGroups;
        $name = $this->getName();
        $group = '-';

        // Allow overbidding the group from the wiki side
        $msg = $this->msg( 'specialpages-specialpagegroup-' . strtolower( $name ) )->inContentLanguage();
        if ( !$msg->isBlank() ) {
            $group = $msg->text();
        } else {
            // Than use the group from this object
            $group = $this->getGroupName();

            // Group '-' is used as default to have the chance to determine,
            // if the special pages overrides this method,
            // if not overridden, $wgSpecialPageGroups is checked for b/c
            if ( $group === '-' && isset( $wgSpecialPageGroups[$name] ) ) {
                $group = $wgSpecialPageGroups[$name];
            }
        }

        // never give '-' back, change to 'other'
        if ( $group === '-' ) {
            $group = 'other';
        }

        return $group;
    }

    protected function getGroupName() {
        // '-' used here to determine, if this group is overridden or has a hardcoded 'other'
        // Needed for b/c in getFinalGroupName
        return '-';
    }
}

abstract class FormSpecialPage extends SpecialPage {
    protected $par = null;

    abstract protected function getFormFields();

    protected function preText() {
        return '';
    }

    protected function postText() {
        return '';
    }

    protected function alterForm( HTMLForm $form ) {
    }

    protected function getMessagePrefix() {
        return strtolower( $this->getName() );
    }

    protected function getForm() {
        $this->fields = $this->getFormFields();

        $form = new HTMLForm( $this->fields, $this->getContext(), $this->getMessagePrefix() );
        $form->setSubmitCallback( array( $this, 'onSubmit' ) );
        // If the form is a compact vertical form, then don't output this ugly
        // fieldset surrounding it.
        // XXX Special pages can setDisplayFormat to 'vform' in alterForm(), but that
        // is called after this.
        if ( !$form->isVForm() ) {
            $form->setWrapperLegendMsg( $this->getMessagePrefix() . '-legend' );
        }

        $headerMsg = $this->msg( $this->getMessagePrefix() . '-text' );
        if ( !$headerMsg->isDisabled() ) {
            $form->addHeaderText( $headerMsg->parseAsBlock() );
        }

        // Retain query parameters (uselang etc)
        $params = array_diff_key(
            $this->getRequest()->getQueryValues(), array( 'title' => null ) );
        $form->addHiddenField( 'redirectparams', wfArrayToCgi( $params ) );

        $form->addPreText( $this->preText() );
        $form->addPostText( $this->postText() );
        $this->alterForm( $form );

        // Give hooks a chance to alter the form, adding extra fields or text etc
        wfRunHooks( "Special{$this->getName()}BeforeFormDisplay", array( &$form ) );

        return $form;
    }

    abstract public function onSubmit( array $data );

    public function onSuccess() {
    }

    public function execute( $par ) {
        $this->setParameter( $par );
        $this->setHeaders();

        // This will throw exceptions if there's a problem
        $this->checkExecutePermissions( $this->getUser() );

        $form = $this->getForm();
        if ( $form->show() ) {
            $this->onSuccess();
        }
    }

    protected function setParameter( $par ) {
        $this->par = $par;
    }

    protected function checkExecutePermissions( User $user ) {
        $this->checkPermissions();

        if ( $this->requiresUnblock() && $user->isBlocked() ) {
            $block = $user->getBlock();
            throw new UserBlockedError( $block );
        }

        if ( $this->requiresWrite() ) {
            $this->checkReadOnly();
        }

        return true;
    }

    public function requiresWrite() {
        return true;
    }

    public function requiresUnblock() {
        return true;
    }
}

class UnlistedSpecialPage extends SpecialPage {
    function __construct( $name, $restriction = '', $function = false, $file = 'default' ) {
        parent::__construct( $name, $restriction, false, $function, $file );
    }

    public function isListed() {
        return false;
    }
}

class IncludableSpecialPage extends SpecialPage {
    function __construct(
        $name, $restriction = '', $listed = true, $function = false, $file = 'default'
    ) {
        parent::__construct( $name, $restriction, $listed, $function, $file, true );
    }

    public function isIncludable() {
        return true;
    }
}

abstract class RedirectSpecialPage extends UnlistedSpecialPage {

    // Query parameters that can be passed through redirects
    protected $mAllowedRedirectParams = array();

    // Query parameters added by redirects
    protected $mAddedRedirectParams = array();

    public function execute( $par ) {
        $redirect = $this->getRedirect( $par );
        $query = $this->getRedirectQuery();
        // Redirect to a page title with possible query parameters
        if ( $redirect instanceof Title ) {
            $url = $redirect->getFullURL( $query );
            $this->getOutput()->redirect( $url );
            return $redirect;
        } elseif ( $redirect === true ) {
            // Redirect to index.php with query parameters
            $url = wfAppendQuery( wfScript( 'index' ), $query );
            $this->getOutput()->redirect( $url );
            return $redirect;
        } else {
            $class = get_class( $this );
            throw new MWException( "RedirectSpecialPage $class doesn't redirect!" );
        }
    }

    abstract public function getRedirect( $par );

    public function getRedirectQuery() {
        $params = array();

        foreach ( $this->mAllowedRedirectParams as $arg ) {
            if ( $this->getRequest()->getVal( $arg, null ) !== null ) {
                $params[$arg] = $this->getRequest()->getVal( $arg );
            }
        }

        foreach ( $this->mAddedRedirectParams as $arg => $val ) {
            $params[$arg] = $val;
        }

        return count( $params )
            ? $params
            : false;
    }
}

abstract class SpecialRedirectToSpecial extends RedirectSpecialPage {
    // @todo FIXME: Visibility must be declared
    var $redirName, $redirSubpage;

    function __construct(
        $name, $redirName, $redirSubpage = false,
        $allowedRedirectParams = array(), $addedRedirectParams = array()
    ) {
        parent::__construct( $name );
        $this->redirName = $redirName;
        $this->redirSubpage = $redirSubpage;
        $this->mAllowedRedirectParams = $allowedRedirectParams;
        $this->mAddedRedirectParams = $addedRedirectParams;
    }

    public function getRedirect( $subpage ) {
        if ( $this->redirSubpage === false ) {
            return SpecialPage::getTitleFor( $this->redirName, $subpage );
        } else {
            return SpecialPage::getTitleFor( $this->redirName, $this->redirSubpage );
        }
    }
}

class SpecialListAdmins extends SpecialRedirectToSpecial {
    function __construct() {
        parent::__construct( 'Listadmins', 'Listusers', 'sysop' );
    }
}

class SpecialListBots extends SpecialRedirectToSpecial {
    function __construct() {
        parent::__construct( 'Listbots', 'Listusers', 'bot' );
    }
}

class SpecialCreateAccount extends SpecialRedirectToSpecial {
    function __construct() {
        parent::__construct( 'CreateAccount', 'Userlogin', 'signup', array( 'returnto', 'returntoquery', 'uselang' ) );
    }

    // No reason to hide this link on Special:Specialpages
    public function isListed() {
        return true;
    }

    protected function getGroupName() {
        return 'login';
    }
}
abstract class RedirectSpecialArticle extends RedirectSpecialPage {
    function __construct( $name ) {
        parent::__construct( $name );
        $redirectParams = array(
            'action',
            'redirect', 'rdfrom',
            # Options for preloaded edits
            'preload', 'editintro', 'preloadtitle', 'summary', 'nosummary',
            # Options for overriding user settings
            'preview', 'internaledit', 'externaledit', 'mode', 'minor', 'watchthis',
            # Options for history/diffs
            'section', 'oldid', 'diff', 'dir',
            'limit', 'offset', 'feed',
            # Misc options
            'redlink', 'debug',
            # Options for action=raw; missing ctype can break JS or CSS in some browsers
            'ctype', 'maxage', 'smaxage',
        );

        wfRunHooks( "RedirectSpecialArticleRedirectParams", array( &$redirectParams ) );
        $this->mAllowedRedirectParams = $redirectParams;
    }
}

class SpecialMypage extends RedirectSpecialArticle {
    function __construct() {
        parent::__construct( 'Mypage' );
    }

    function getRedirect( $subpage ) {
        if ( strval( $subpage ) !== '' ) {
            return Title::makeTitle( NS_USER, $this->getUser()->getName() . '/' . $subpage );
        } else {
            return Title::makeTitle( NS_USER, $this->getUser()->getName() );
        }
    }
}

class SpecialMytalk extends RedirectSpecialArticle {
    function __construct() {
        parent::__construct( 'Mytalk' );
    }

    function getRedirect( $subpage ) {
        if ( strval( $subpage ) !== '' ) {
            return Title::makeTitle( NS_USER_TALK, $this->getUser()->getName() . '/' . $subpage );
        } else {
            return Title::makeTitle( NS_USER_TALK, $this->getUser()->getName() );
        }
    }
}

class SpecialMycontributions extends RedirectSpecialPage {
    function __construct() {
        parent::__construct( 'Mycontributions' );
        $this->mAllowedRedirectParams = array( 'limit', 'namespace', 'tagfilter',
            'offset', 'dir', 'year', 'month', 'feed' );
    }

    function getRedirect( $subpage ) {
        return SpecialPage::getTitleFor( 'Contributions', $this->getUser()->getName() );
    }
}

class SpecialMyuploads extends RedirectSpecialPage {
    function __construct() {
        parent::__construct( 'Myuploads' );
        $this->mAllowedRedirectParams = array( 'limit', 'ilshowall', 'ilsearch' );
    }

    function getRedirect( $subpage ) {
        return SpecialPage::getTitleFor( 'Listfiles', $this->getUser()->getName() );
    }
}

class SpecialAllMyUploads extends RedirectSpecialPage {
    function __construct() {
        parent::__construct( 'AllMyUploads' );
        $this->mAllowedRedirectParams = array( 'limit', 'ilsearch' );
    }

    function getRedirect( $subpage ) {
        $this->mAddedRedirectParams['ilshowall'] = 1;
        return SpecialPage::getTitleFor( 'Listfiles', $this->getUser()->getName() );
    }
}


class SpecialPermanentLink extends RedirectSpecialPage {
    function __construct() {
        parent::__construct( 'PermanentLink' );
        $this->mAllowedRedirectParams = array();
    }

    function getRedirect( $subpage ) {
        $subpage = intval( $subpage );
        if ( $subpage === 0 ) {
            # throw an error page when no subpage was given
            throw new ErrorPageError( 'nopagetitle', 'nopagetext' );
        }
        $this->mAddedRedirectParams['oldid'] = $subpage;
        return true;
    }
}