3 * SpecialPage: handling special pages and lists thereof.
5 * To add a special page in an extension, add to $wgSpecialPages either
6 * an object instance or an array containing the name and constructor
7 * parameters. The latter is preferred for performance reasons.
9 * The object instantiated must be either an instance of SpecialPage or a
10 * sub-class thereof. It must have an execute() method, which sends the HTML
11 * for the special page to $wgOut. The parent class has an execute() method
12 * which distributes the call to the historical global functions. Additionally,
13 * execute() also checks if the user has the necessary access privileges
14 * and bails out if not.
16 * To add a core special page, use the similar static list in
17 * SpecialPage::$mList. To remove a core static special page at runtime, use
18 * a SpecialPage_initList hook.
21 * @ingroup SpecialPage
22 * @defgroup SpecialPage SpecialPage
26 * Parent special page class, also static functions for handling the special
28 * @ingroup SpecialPage
32 // The canonical name of this special page
33 // Also used for the default <h1> heading, @see getDescription()
34 /*private*/ var $mName;
36 // The local name of this special page
39 // Minimum user level required to access this page, or "" for anyone.
40 // Also used to categorise the pages in Special:Specialpages
41 private $mRestriction;
43 // Listed in Special:Specialpages?
46 // Function name called by the default execute()
49 // File which needs to be included before the function above can be called
52 // Whether or not this special page is being included from an article
53 protected $mIncluding;
55 // Whether the special page can be included in an article
56 protected $mIncludable;
59 * Current request context
65 * Initialise the special page list
66 * This must be called before accessing SpecialPage::$mList
67 * @deprecated since 1.18
69 static function initList() {
74 * @deprecated since 1.18
76 static function initAliasList() {
81 * Given a special page alias, return the special page name.
82 * Returns false if there is no such alias.
84 * @param $alias String
85 * @return String or false
86 * @deprecated since 1.18 call SpecialPageFactory method directly
88 static function resolveAlias( $alias ) {
89 list( $name, /*...*/ ) = SpecialPageFactory
::resolveAlias( $alias );
94 * Given a special page name with a possible subpage, return an array
95 * where the first element is the special page name and the second is the
98 * @param $alias String
100 * @deprecated since 1.18 call SpecialPageFactory method directly
102 static function resolveAliasWithSubpage( $alias ) {
103 return SpecialPageFactory
::resolveAlias( $alias );
107 * Add a page to the list of valid special pages. This used to be the preferred
108 * method for adding special pages in extensions. It's now suggested that you add
109 * an associative record to $wgSpecialPages. This avoids autoloading SpecialPage.
111 * @param $page SpecialPage
112 * @deprecated in 1.7, warnings in 1.17, might be removed in 1.20
114 static function addPage( &$page ) {
115 wfDeprecated( __METHOD__
);
116 SpecialPageFactory
::getList()->{$page->mName
} = $page;
120 * Add a page to a certain display group for Special:SpecialPages
122 * @param $page Mixed: SpecialPage or string
123 * @param $group String
124 * @deprecated since 1.18 call SpecialPageFactory method directly
126 static function setGroup( $page, $group ) {
127 return SpecialPageFactory
::setGroup( $page, $group );
131 * Add a page to a certain display group for Special:SpecialPages
133 * @param $page SpecialPage
134 * @deprecated since 1.18 call SpecialPageFactory method directly
136 static function getGroup( &$page ) {
137 return SpecialPageFactory
::getGroup( $page );
141 * Remove a special page from the list
142 * Formerly used to disable expensive or dangerous special pages. The
143 * preferred method is now to add a SpecialPage_initList hook.
144 * @deprecated since 1.18
146 static function removePage( $name ) {
147 unset( SpecialPageFactory
::getList()->$name );
151 * Check if a given name exist as a special page or as a special page alias
153 * @param $name String: name of a special page
154 * @return Boolean: true if a special page exists with this name
155 * @deprecated since 1.18 call SpecialPageFactory method directly
157 static function exists( $name ) {
158 return SpecialPageFactory
::exists( $name );
162 * Find the object with a given name and return it (or NULL)
164 * @param $name String
165 * @return SpecialPage object or null if the page doesn't exist
166 * @deprecated since 1.18 call SpecialPageFactory method directly
168 static function getPage( $name ) {
169 return SpecialPageFactory
::getPage( $name );
173 * Get a special page with a given localised name, or NULL if there
174 * is no such special page.
176 * @return SpecialPage object or null if the page doesn't exist
177 * @deprecated since 1.18 call SpecialPageFactory method directly
179 static function getPageByAlias( $alias ) {
180 return SpecialPageFactory
::getPage( $alias );
184 * Return categorised listable special pages which are available
185 * for the current user, and everyone.
187 * @return Associative array mapping page's name to its SpecialPage object
188 * @deprecated since 1.18 call SpecialPageFactory method directly
190 static function getUsablePages() {
191 return SpecialPageFactory
::getUsablePages();
195 * Return categorised listable special pages for all users
197 * @return Associative array mapping page's name to its SpecialPage object
198 * @deprecated since 1.18 call SpecialPageFactory method directly
200 static function getRegularPages() {
201 return SpecialPageFactory
::getRegularPages();
205 * Return categorised listable special pages which are available
206 * for the current user, but not for everyone
208 * @return Associative array mapping page's name to its SpecialPage object
209 * @deprecated since 1.18 call SpecialPageFactory method directly
211 static function getRestrictedPages() {
212 return SpecialPageFactory
::getRestrictedPages();
216 * Execute a special page path.
217 * The path may contain parameters, e.g. Special:Name/Params
218 * Extracts the special page name and call the execute method, passing the parameters
220 * Returns a title object if the page is redirected, false if there was no such special
221 * page, and true if it was successful.
223 * @param $title Title object
224 * @param $context RequestContext
225 * @param $including Bool output is being captured for use in {{special:whatever}}
226 * @deprecated since 1.18 call SpecialPageFactory method directly
228 public static function executePath( &$title, RequestContext
&$context, $including = false ) {
229 return SpecialPageFactory
::executePath( $title, $context, $including );
233 * Just like executePath() except it returns the HTML instead of outputting it
234 * Returns false if there was no such special page, or a title object if it was
237 * @return String: HTML fragment
238 * @deprecated since 1.18 call SpecialPageFactory method directly
240 static function capturePath( &$title ) {
241 return SpecialPageFactory
::capturePath( $title );
245 * Get the local name for a specified canonical name
247 * @param $name String
248 * @param $subpage Mixed: boolean false, or string
251 * @deprecated since 1.18 call SpecialPageFactory method directly
253 static function getLocalNameFor( $name, $subpage = false ) {
254 return SpecialPageFactory
::getLocalNameFor( $name, $subpage );
258 * Get a localised Title object for a specified special page name
260 * @return Title object
262 public static function getTitleFor( $name, $subpage = false ) {
263 $name = SpecialPageFactory
::getLocalNameFor( $name, $subpage );
265 return Title
::makeTitle( NS_SPECIAL
, $name );
267 throw new MWException( "Invalid special page name \"$name\"" );
272 * Get a localised Title object for a page name with a possibly unvalidated subpage
274 * @return Title object or null if the page doesn't exist
276 public static function getSafeTitleFor( $name, $subpage = false ) {
277 $name = SpecialPageFactory
::getLocalNameFor( $name, $subpage );
279 return Title
::makeTitleSafe( NS_SPECIAL
, $name );
286 * Get a title for a given alias
288 * @return Title or null if there is no such alias
289 * @deprecated since 1.18 call SpecialPageFactory method directly
291 static function getTitleForAlias( $alias ) {
292 return SpecialPageFactory
::getTitleForAlias( $alias );
296 * Default constructor for special pages
297 * Derivative classes should call this from their constructor
298 * Note that if the user does not have the required level, an error message will
299 * be displayed by the default execute() method, without the global function ever
302 * If you override execute(), you can recover the default behaviour with userCanExecute()
303 * and displayRestrictionError()
305 * @param $name String: name of the special page, as seen in links and URLs
306 * @param $restriction String: user right required, e.g. "block" or "delete"
307 * @param $listed Boolean: whether the page is listed in Special:Specialpages
308 * @param $function Callback: function called by execute(). By default it is constructed from $name
309 * @param $file String: file which is included by execute(). It is also constructed from $name by default
310 * @param $includable Boolean: whether the page can be included in normal pages
312 public function __construct( $name = '', $restriction = '', $listed = true, $function = false, $file = 'default', $includable = false ) {
313 $this->init( $name, $restriction, $listed, $function, $file, $includable );
317 * Do the real work for the constructor, mainly so __call() can intercept
318 * calls to SpecialPage()
319 * @see __construct() for param docs
321 private function init( $name, $restriction, $listed, $function, $file, $includable ) {
322 $this->mName
= $name;
323 $this->mRestriction
= $restriction;
324 $this->mListed
= $listed;
325 $this->mIncludable
= $includable;
327 $this->mFunction
= 'wfSpecial'.$name;
329 $this->mFunction
= $function;
331 if ( $file === 'default' ) {
332 $this->mFile
= dirname(__FILE__
) . "/specials/Special$name.php";
334 $this->mFile
= $file;
339 * Use PHP's magic __call handler to get calls to the old PHP4 constructor
340 * because PHP E_STRICT yells at you for having __construct() and SpecialPage()
342 * @param $fName String Name of called method
343 * @param $a Array Arguments to the method
344 * @deprecated since 1.17, call parent::__construct()
346 public function __call( $fName, $a ) {
347 // Sometimes $fName is SpecialPage, sometimes it's specialpage. <3 PHP
348 if( strtolower( $fName ) == 'specialpage' ) {
349 // Deprecated messages now, remove in 1.19 or 1.20?
350 wfDeprecated( __METHOD__
);
352 $name = isset( $a[0] ) ?
$a[0] : '';
353 $restriction = isset( $a[1] ) ?
$a[1] : '';
354 $listed = isset( $a[2] ) ?
$a[2] : true;
355 $function = isset( $a[3] ) ?
$a[3] : false;
356 $file = isset( $a[4] ) ?
$a[4] : 'default';
357 $includable = isset( $a[5] ) ?
$a[5] : false;
358 $this->init( $name, $restriction, $listed, $function, $file, $includable );
360 $className = get_class( $this );
361 throw new MWException( "Call to undefined method $className::$fName" );
366 * Get the name of this Special Page.
374 * Get the permission that a user must have to execute this page
377 function getRestriction() {
378 return $this->mRestriction
;
382 * Get the file which will be included by SpecialPage::execute() if your extension is
383 * still stuck in the past and hasn't overridden the execute() method. No modern code
384 * should want or need to know this.
386 * @deprecated since 1.18
392 // FIXME: decide which syntax to use for this, and stick to it
394 * Whether this special page is listed in Special:SpecialPages
395 * @since r3583 (v1.3)
398 function isListed() {
399 return $this->mListed
;
402 * Set whether this page is listed in Special:Specialpages, at run-time
403 * @since r3583 (v1.3)
406 function setListed( $listed ) {
407 return wfSetVar( $this->mListed
, $listed );
410 * Get or set whether this special page is listed in Special:SpecialPages
411 * @since r11308 (v1.6)
414 function listed( $x = null) {
415 return wfSetVar( $this->mListed
, $x );
419 * Whether it's allowed to transclude the special page via {{Special:Foo/params}}
422 public function isIncludable(){
423 return $this->mIncludable
;
427 * These mutators are very evil, as the relevant variables should not mutate. So
429 * @deprecated since 1.18
431 function name( $x = null ) { return wfSetVar( $this->mName
, $x ); }
432 function restriction( $x = null) { return wfSetVar( $this->mRestriction
, $x ); }
433 function func( $x = null) { return wfSetVar( $this->mFunction
, $x ); }
434 function file( $x = null) { return wfSetVar( $this->mFile
, $x ); }
435 function includable( $x = null ) { return wfSetVar( $this->mIncludable
, $x ); }
438 * Whether the special page is being evaluated via transclusion
441 function including( $x = null ) {
442 return wfSetVar( $this->mIncluding
, $x );
446 * Get the localised name of the special page
448 function getLocalName() {
449 if ( !isset( $this->mLocalName
) ) {
450 $this->mLocalName
= SpecialPageFactory
::getLocalNameFor( $this->mName
);
452 return $this->mLocalName
;
456 * Is this page expensive (for some definition of expensive)?
457 * Expensive pages are disabled or cached in miser mode. Originally used
458 * (and still overridden) by QueryPage and subclasses, moved here so that
459 * Special:SpecialPages can safely call it for all special pages.
463 public function isExpensive() {
468 * Can be overridden by subclasses with more complicated permissions
471 * @return Boolean: should the page be displayed with the restricted-access
474 public function isRestricted() {
475 global $wgGroupPermissions;
476 // DWIM: If all anons can do something, then it is not restricted
477 return $this->mRestriction
!= '' && empty($wgGroupPermissions['*'][$this->mRestriction
]);
481 * Checks if the given user (identified by an object) can execute this
482 * special page (as defined by $mRestriction). Can be overridden by sub-
483 * classes with more complicated permissions schemes.
485 * @param $user User: the user to check
486 * @return Boolean: does the user have permission to view the page?
488 public function userCanExecute( User
$user ) {
489 return $user->isAllowed( $this->mRestriction
);
493 * Output an error message telling the user what access level they have to have
495 function displayRestrictionError() {
496 throw new PermissionsError( $this->mRestriction
);
500 * Sets headers - this should be called from the execute() method of all derived classes!
502 function setHeaders() {
503 $out = $this->getOutput();
504 $out->setArticleRelated( false );
505 $out->setRobotPolicy( "noindex,nofollow" );
506 $out->setPageTitle( $this->getDescription() );
510 * Default execute method
511 * Checks user permissions, calls the function given in mFunction
513 * This must be overridden by subclasses; it will be made abstract in a future version
515 function execute( $par ) {
518 if ( $this->userCanExecute( $this->getUser() ) ) {
519 $func = $this->mFunction
;
520 // only load file if the function does not exist
521 if(!is_callable($func) and $this->mFile
) {
522 require_once( $this->mFile
);
524 $this->outputHeader();
525 call_user_func( $func, $par, $this );
527 $this->displayRestrictionError();
532 * Outputs a summary message on top of special pages
533 * Per default the message key is the canonical name of the special page
534 * May be overriden, i.e. by extensions to stick with the naming conventions
535 * for message keys: 'extensionname-xxx'
537 * @param $summaryMessageKey String: message key of the summary
539 function outputHeader( $summaryMessageKey = '' ) {
542 if( $summaryMessageKey == '' ) {
543 $msg = $wgContLang->lc( $this->getName() ) . '-summary';
545 $msg = $summaryMessageKey;
547 if ( !wfMessage( $msg )->isBlank() and ! $this->including() ) {
548 $this->getOutput()->wrapWikiMsg( "<div class='mw-specialpage-summary'>\n$1\n</div>", $msg );
554 * Returns the name that goes in the \<h1\> in the special page itself, and
555 * also the name that will be listed in Special:Specialpages
557 * Derived classes can override this, but usually it is easier to keep the
558 * default behaviour. Messages can be added at run-time, see
563 function getDescription() {
564 return wfMsg( strtolower( $this->mName
) );
568 * Get a self-referential title object
570 * @return Title object
572 function getTitle( $subpage = false ) {
573 return self
::getTitleFor( $this->mName
, $subpage );
577 * Sets the context this SpecialPage is executed in
579 * @param $context RequestContext
582 public function setContext( $context ) {
583 $this->mContext
= $context;
587 * Gets the context this SpecialPage is executed in
589 * @return RequestContext
592 public function getContext() {
593 if ( $this->mContext
instanceof RequestContext
) {
594 return $this->mContext
;
596 wfDebug( __METHOD__
. " called and \$mContext is null. Return RequestContext::getMain(); for sanity\n" );
597 return RequestContext
::getMain();
602 * Get the WebRequest being used for this instance
607 public function getRequest() {
608 return $this->getContext()->getRequest();
612 * Get the OutputPage being used for this instance
617 public function getOutput() {
618 return $this->getContext()->getOutput();
622 * Shortcut to get the skin being used for this instance
627 public function getUser() {
628 return $this->getContext()->getUser();
632 * Shortcut to get the skin being used for this instance
637 public function getSkin() {
638 return $this->getContext()->getSkin();
642 * Return the full title, including $par
647 public function getFullTitle() {
648 return $this->getContext()->getTitle();
652 * Wrapper around wfMessage that sets the current context. Currently this
657 public function msg( /* $args */ ) {
658 return call_user_func_array( 'wfMessage', func_get_args() )->title( $this->getFullTitle() );
663 * Shortcut to construct a special page which is unlisted by default
664 * @ingroup SpecialPage
666 class UnlistedSpecialPage
extends SpecialPage
668 function __construct( $name, $restriction = '', $function = false, $file = 'default' ) {
669 parent
::__construct( $name, $restriction, false, $function, $file );
672 public function isListed(){
678 * Shortcut to construct an includable special page
679 * @ingroup SpecialPage
681 class IncludableSpecialPage
extends SpecialPage
683 function __construct( $name, $restriction = '', $listed = true, $function = false, $file = 'default' ) {
684 parent
::__construct( $name, $restriction, $listed, $function, $file, true );
687 public function isIncludable(){
693 * Shortcut to construct a special page alias.
694 * @ingroup SpecialPage
696 abstract class RedirectSpecialPage
extends UnlistedSpecialPage
{
698 // Query parameters that can be passed through redirects
699 protected $mAllowedRedirectParams = array();
701 // Query parameteres added by redirects
702 protected $mAddedRedirectParams = array();
704 public function execute( $par ){
705 $redirect = $this->getRedirect( $par );
706 $query = $this->getRedirectQuery();
707 // Redirect to a page title with possible query parameters
708 if ( $redirect instanceof Title
) {
709 $url = $redirect->getFullUrl( $query );
710 $this->getContext()->output
->redirect( $url );
711 wfProfileOut( __METHOD__
);
713 // Redirect to index.php with query parameters
714 } elseif ( $redirect === true ) {
716 $url = $wgScript . '?' . wfArrayToCGI( $query );
717 $this->getContext()->output
->redirect( $url );
718 wfProfileOut( __METHOD__
);
722 throw new MWException( "RedirectSpecialPage $class doesn't redirect!" );
727 * If the special page is a redirect, then get the Title object it redirects to.
730 * @return Title|false
732 abstract public function getRedirect( $par );
735 * Return part of the request string for a special redirect page
736 * This allows passing, e.g. action=history to Special:Mypage, etc.
740 public function getRedirectQuery() {
743 foreach( $this->mAllowedRedirectParams
as $arg ) {
744 if( $this->getContext()->request
->getVal( $arg, null ) !== null ){
745 $params[$arg] = $this->getContext()->request
->getVal( $arg );
749 foreach( $this->mAddedRedirectParams
as $arg => $val ) {
750 $params[$arg] = $val;
753 return count( $params )
759 abstract class SpecialRedirectToSpecial
extends RedirectSpecialPage
{
761 var $redirName, $redirSubpage;
763 function __construct( $name, $redirName, $redirSubpage = false, $allowedRedirectParams = array(), $addedRedirectParams = array() ) {
764 parent
::__construct( $name );
765 $this->redirName
= $redirName;
766 $this->redirSubpage
= $redirSubpage;
767 $this->mAllowedRedirectParams
= $allowedRedirectParams;
768 $this->mAddedRedirectParams
= $addedRedirectParams;
771 public function getRedirect( $subpage ) {
772 if ( $this->redirSubpage
=== false ) {
773 return SpecialPage
::getTitleFor( $this->redirName
, $subpage );
775 return SpecialPage
::getTitleFor( $this->redirName
, $this->redirSubpage
);
781 * ListAdmins --> ListUsers/admin
783 class SpecialListAdmins
extends SpecialRedirectToSpecial
{
784 function __construct(){
785 parent
::__construct( 'ListAdmins', 'ListUsers', 'sysop' );
790 * ListBots --> ListUsers/admin
792 class SpecialListBots
extends SpecialRedirectToSpecial
{
793 function __construct(){
794 parent
::__construct( 'ListAdmins', 'ListUsers', 'bot' );
799 * CreateAccount --> UserLogin/signup
800 * FIXME: this (and the rest of the login frontend) needs to die a horrible painful death
802 class SpecialCreateAccount
extends SpecialRedirectToSpecial
{
803 function __construct(){
804 parent
::__construct( 'CreateAccount', 'Userlogin', 'signup', array( 'uselang' ) );
808 * SpecialMypage, SpecialMytalk and SpecialMycontributions special pages
809 * are used to get user independant links pointing to the user page, talk
810 * page and list of contributions.
811 * This can let us cache a single copy of any generated content for all
816 * Shortcut to construct a special page pointing to current user user's page.
817 * @ingroup SpecialPage
819 class SpecialMypage
extends RedirectSpecialPage
{
820 function __construct() {
821 parent
::__construct( 'Mypage' );
822 $this->mAllowedRedirectParams
= array( 'action' , 'preload' , 'editintro',
823 'section', 'oldid', 'diff', 'dir' );
826 function getRedirect( $subpage ) {
828 if ( strval( $subpage ) !== '' ) {
829 return Title
::makeTitle( NS_USER
, $wgUser->getName() . '/' . $subpage );
831 return Title
::makeTitle( NS_USER
, $wgUser->getName() );
837 * Shortcut to construct a special page pointing to current user talk page.
838 * @ingroup SpecialPage
840 class SpecialMytalk
extends RedirectSpecialPage
{
841 function __construct() {
842 parent
::__construct( 'Mytalk' );
843 $this->mAllowedRedirectParams
= array( 'action' , 'preload' , 'editintro',
844 'section', 'oldid', 'diff', 'dir' );
847 function getRedirect( $subpage ) {
849 if ( strval( $subpage ) !== '' ) {
850 return Title
::makeTitle( NS_USER_TALK
, $wgUser->getName() . '/' . $subpage );
852 return Title
::makeTitle( NS_USER_TALK
, $wgUser->getName() );
858 * Shortcut to construct a special page pointing to current user contributions.
859 * @ingroup SpecialPage
861 class SpecialMycontributions
extends RedirectSpecialPage
{
862 function __construct() {
863 parent
::__construct( 'Mycontributions' );
864 $this->mAllowedRedirectParams
= array( 'limit', 'namespace', 'tagfilter',
865 'offset', 'dir', 'year', 'month', 'feed' );
868 function getRedirect( $subpage ) {
870 return SpecialPage
::getTitleFor( 'Contributions', $wgUser->getName() );
875 * Redirect to Special:Listfiles?user=$wgUser
877 class SpecialMyuploads
extends RedirectSpecialPage
{
878 function __construct() {
879 parent
::__construct( 'Myuploads' );
880 $this->mAllowedRedirectParams
= array( 'limit' );
883 function getRedirect( $subpage ) {
885 return SpecialPage
::getTitleFor( 'Listfiles', $wgUser->getName() );
890 * Redirect from Special:PermanentLink/### to index.php?oldid=###
892 class SpecialPermanentLink
extends RedirectSpecialPage
{
893 function __construct() {
894 parent
::__construct( 'PermanentLink' );
895 $this->mAllowedRedirectParams
= array();
898 function getRedirect( $subpage ) {
899 $subpage = intval( $subpage );
900 $this->mAddedRedirectParams
['oldid'] = $subpage;