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 all 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 = $feedTemplate . wfArrayToCgi( $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 {

        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' ) );
                $form->setWrapperLegend( $this->msg( $this->getMessagePrefix() . '-legend' ) );
                $form->addHeaderText(
                        $this->msg( $this->getMessagePrefix() . '-text' )->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 );

        abstract 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 ) {}

        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;
                // Redirect to index.php with query parameters
                } elseif ( $redirect === true ) {
                        global $wgScript;
                        $url = $wgScript . '?' . wfArrayToCgi( $query );
                        $this->getOutput()->redirect( $url );
                        return $redirect;
                } else {
                        $class = __CLASS__;
                        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 {
        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( 'uselang' ) );
        }
}
abstract class RedirectSpecialArticle extends RedirectSpecialPage {
        function __construct( $name ) {
                parent::__construct( $name );
                $redirectParams = array(
                        'action',
                        'redirect', 'rdfrom',
                        # Options for preloaded edits
                        'preload', 'editintro', 'preloadtitle', 'summary',
                        # Options for overriding user settings
                        'preview', 'internaledit', 'externaledit', 'mode',
                        # 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' );
        }

        function getRedirect( $subpage ) {
                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;
        }
}