3 * Provide things related to namespaces.
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.
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.
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
23 use MediaWiki\Config\ServiceOptions
;
24 use MediaWiki\Linker\LinkTarget
;
25 use MediaWiki\MediaWikiServices
;
28 * This is a utility class for dealing with namespaces that encodes all the "magic" behaviors of
29 * them based on index. The textual names of the namespaces are handled by Language.php.
36 * These namespaces should always be first-letter capitalized, now and
37 * forevermore. Historically, they could've probably been lowercased too,
38 * but some things are just too ingrained now. :)
40 private $alwaysCapitalizedNamespaces = [ NS_SPECIAL
, NS_USER
, NS_MEDIAWIKI
];
42 /** @var string[]|null Canonical namespaces cache */
43 private $canonicalNamespaces = null;
45 /** @var array|false Canonical namespaces index cache */
46 private $namespaceIndexes = false;
48 /** @var int[]|null Valid namespaces cache */
49 private $validNamespaces = null;
51 /** @var ServiceOptions */
55 * Definitions of the NS_ constants are in Defines.php
57 * @todo Make this const when HHVM support is dropped (T192166)
62 public static $canonicalNames = [
64 NS_SPECIAL
=> 'Special',
67 NS_USER_TALK
=> 'User_talk',
68 NS_PROJECT
=> 'Project',
69 NS_PROJECT_TALK
=> 'Project_talk',
71 NS_FILE_TALK
=> 'File_talk',
72 NS_MEDIAWIKI
=> 'MediaWiki',
73 NS_MEDIAWIKI_TALK
=> 'MediaWiki_talk',
74 NS_TEMPLATE
=> 'Template',
75 NS_TEMPLATE_TALK
=> 'Template_talk',
77 NS_HELP_TALK
=> 'Help_talk',
78 NS_CATEGORY
=> 'Category',
79 NS_CATEGORY_TALK
=> 'Category_talk',
83 * TODO Make this const when HHVM support is dropped (T192166)
88 public static $constructorOptions = [
90 'CanonicalNamespaceNames',
91 'CapitalLinkOverrides',
95 'ExtraSignatureNamespaces',
96 'NamespaceContentModels',
97 'NamespacesWithSubpages',
98 'NonincludableNamespaces',
102 * @param ServiceOptions $options
104 public function __construct( ServiceOptions
$options ) {
105 $options->assertRequiredOptions( self
::$constructorOptions );
106 $this->options
= $options;
110 * Throw an exception when trying to get the subject or talk page
111 * for a given namespace where it does not make sense.
112 * Special namespaces are defined in includes/Defines.php and have
113 * a value below 0 (ex: NS_SPECIAL = -1 , NS_MEDIA = -2)
116 * @param string $method
118 * @throws MWException
121 private function isMethodValidFor( $index, $method ) {
122 if ( $index < NS_MAIN
) {
123 throw new MWException( "$method does not make any sense for given namespace $index" );
129 * Can pages in the given namespace be moved?
131 * @param int $index Namespace index
134 public function isMovable( $index ) {
135 $result = $index >= NS_MAIN
&&
136 ( $index != NS_FILE ||
$this->options
->get( 'AllowImageMoving' ) );
141 Hooks
::run( 'NamespaceIsMovable', [ $index, &$result ] );
147 * Is the given namespace is a subject (non-talk) namespace?
149 * @param int $index Namespace index
152 public function isSubject( $index ) {
153 return !$this->isTalk( $index );
157 * Is the given namespace a talk namespace?
159 * @param int $index Namespace index
162 public function isTalk( $index ) {
163 return $index > NS_MAIN
168 * Get the talk namespace index for a given namespace
170 * @param int $index Namespace index
172 * @throws MWException if the given namespace doesn't have an associated talk namespace
175 public function getTalk( $index ) {
176 $this->isMethodValidFor( $index, __METHOD__
);
177 return $this->isTalk( $index )
183 * Get a LinkTarget referring to the talk page of $target.
185 * @see canHaveTalkPage
186 * @param LinkTarget $target
187 * @return LinkTarget Talk page for $target
188 * @throws MWException if $target doesn't have talk pages, e.g. because it's in NS_SPECIAL,
189 * because it's a relative section-only link, or it's an an interwiki link.
191 public function getTalkPage( LinkTarget
$target ) : LinkTarget
{
192 if ( $target->getText() === '' ) {
193 throw new MWException( 'Can\'t determine talk page associated with relative section link' );
196 if ( $target->getInterwiki() !== '' ) {
197 throw new MWException( 'Can\'t determine talk page associated with interwiki link' );
200 if ( $this->isTalk( $target->getNamespace() ) ) {
204 // NOTE: getTalk throws on bad namespaces!
205 return new TitleValue( $this->getTalk( $target->getNamespace() ), $target->getDBkey() );
209 * Can the title have a corresponding talk page?
211 * False for relative section-only links (with getText() === ''),
212 * interwiki links (with getInterwiki() !== ''), and pages in NS_SPECIAL.
216 * @param LinkTarget $target
217 * @return bool True if this title either is a talk page or can have a talk page associated.
219 public function canHaveTalkPage( LinkTarget
$target ) {
220 if ( $target->getText() === '' ||
$target->getInterwiki() !== '' ) {
224 if ( $target->getNamespace() < NS_MAIN
) {
232 * Get the subject namespace index for a given namespace
233 * Special namespaces (NS_MEDIA, NS_SPECIAL) are always the subject.
235 * @param int $index Namespace index
238 public function getSubject( $index ) {
239 # Handle special namespaces
240 if ( $index < NS_MAIN
) {
244 return $this->isTalk( $index )
250 * @param LinkTarget $target
251 * @return LinkTarget Subject page for $target
253 public function getSubjectPage( LinkTarget
$target ) : LinkTarget
{
254 if ( $this->isSubject( $target->getNamespace() ) ) {
257 return new TitleValue( $this->getSubject( $target->getNamespace() ), $target->getDBkey() );
261 * Get the associated namespace.
262 * For talk namespaces, returns the subject (non-talk) namespace
263 * For subject (non-talk) namespaces, returns the talk namespace
265 * @param int $index Namespace index
267 * @throws MWException if called on a namespace that has no talk pages (e.g., NS_SPECIAL)
269 public function getAssociated( $index ) {
270 $this->isMethodValidFor( $index, __METHOD__
);
272 if ( $this->isSubject( $index ) ) {
273 return $this->getTalk( $index );
275 return $this->getSubject( $index );
279 * @param LinkTarget $target
280 * @return LinkTarget Talk page for $target if it's a subject page, subject page if it's a talk
282 * @throws MWException if $target's namespace doesn't have talk pages (e.g., NS_SPECIAL)
284 public function getAssociatedPage( LinkTarget
$target ) : LinkTarget
{
285 if ( $target->getText() === '' ) {
286 throw new MWException( 'Can\'t determine talk page associated with relative section link' );
289 if ( $target->getInterwiki() !== '' ) {
290 throw new MWException( 'Can\'t determine talk page associated with interwiki link' );
293 return new TitleValue(
294 $this->getAssociated( $target->getNamespace() ), $target->getDBkey() );
298 * Returns whether the specified namespace exists
304 public function exists( $index ) {
305 $nslist = $this->getCanonicalNamespaces();
306 return isset( $nslist[$index] );
310 * Returns whether the specified namespaces are the same namespace
312 * @note It's possible that in the future we may start using something
313 * other than just namespace indexes. Under that circumstance making use
314 * of this function rather than directly doing comparison will make
315 * sure that code will not potentially break.
317 * @param int $ns1 The first namespace index
318 * @param int $ns2 The second namespace index
322 public function equals( $ns1, $ns2 ) {
327 * Returns whether the specified namespaces share the same subject.
328 * eg: NS_USER and NS_USER wil return true, as well
329 * NS_USER and NS_USER_TALK will return true.
331 * @param int $ns1 The first namespace index
332 * @param int $ns2 The second namespace index
336 public function subjectEquals( $ns1, $ns2 ) {
337 return $this->getSubject( $ns1 ) == $this->getSubject( $ns2 );
341 * Returns array of all defined namespaces with their canonical
346 public function getCanonicalNamespaces() {
347 if ( $this->canonicalNamespaces
=== null ) {
348 $this->canonicalNamespaces
=
349 [ NS_MAIN
=> '' ] +
$this->options
->get( 'CanonicalNamespaceNames' );
350 $this->canonicalNamespaces +
=
351 ExtensionRegistry
::getInstance()->getAttribute( 'ExtensionNamespaces' );
352 if ( is_array( $this->options
->get( 'ExtraNamespaces' ) ) ) {
353 $this->canonicalNamespaces +
= $this->options
->get( 'ExtraNamespaces' );
355 Hooks
::run( 'CanonicalNamespaces', [ &$this->canonicalNamespaces
] );
357 return $this->canonicalNamespaces
;
361 * Returns the canonical (English) name for a given index
363 * @param int $index Namespace index
364 * @return string|bool If no canonical definition.
366 public function getCanonicalName( $index ) {
367 $nslist = $this->getCanonicalNamespaces();
368 return $nslist[$index] ??
false;
372 * Returns the index for a given canonical name, or NULL
373 * The input *must* be converted to lower case first
375 * @param string $name Namespace name
378 public function getCanonicalIndex( $name ) {
379 if ( $this->namespaceIndexes
=== false ) {
380 $this->namespaceIndexes
= [];
381 foreach ( $this->getCanonicalNamespaces() as $i => $text ) {
382 $this->namespaceIndexes
[strtolower( $text )] = $i;
385 if ( array_key_exists( $name, $this->namespaceIndexes
) ) {
386 return $this->namespaceIndexes
[$name];
393 * Returns an array of the namespaces (by integer id) that exist on the wiki. Used primarily by
394 * the API in help documentation. The array is sorted numerically and omits negative namespaces.
397 public function getValidNamespaces() {
398 if ( is_null( $this->validNamespaces
) ) {
399 foreach ( array_keys( $this->getCanonicalNamespaces() ) as $ns ) {
401 $this->validNamespaces
[] = $ns;
404 // T109137: sort numerically
405 sort( $this->validNamespaces
, SORT_NUMERIC
);
408 return $this->validNamespaces
;
414 * Does this namespace ever have a talk namespace?
416 * @param int $index Namespace ID
417 * @return bool True if this namespace either is or has a corresponding talk namespace.
419 public function hasTalkNamespace( $index ) {
420 return $index >= NS_MAIN
;
424 * Does this namespace contain content, for the purposes of calculating
427 * @param int $index Index to check
430 public function isContent( $index ) {
431 return $index == NS_MAIN ||
in_array( $index, $this->options
->get( 'ContentNamespaces' ) );
435 * Might pages in this namespace require the use of the Signature button on
438 * @param int $index Index to check
441 public function wantSignatures( $index ) {
442 return $this->isTalk( $index ) ||
443 in_array( $index, $this->options
->get( 'ExtraSignatureNamespaces' ) );
447 * Can pages in a namespace be watched?
452 public function isWatchable( $index ) {
453 return $index >= NS_MAIN
;
457 * Does the namespace allow subpages?
459 * @param int $index Index to check
462 public function hasSubpages( $index ) {
463 return !empty( $this->options
->get( 'NamespacesWithSubpages' )[$index] );
467 * Get a list of all namespace indices which are considered to contain content
468 * @return array Array of namespace indices
470 public function getContentNamespaces() {
471 $contentNamespaces = $this->options
->get( 'ContentNamespaces' );
472 if ( !is_array( $contentNamespaces ) ||
$contentNamespaces === [] ) {
474 } elseif ( !in_array( NS_MAIN
, $contentNamespaces ) ) {
475 // always force NS_MAIN to be part of array (to match the algorithm used by isContent)
476 return array_merge( [ NS_MAIN
], $contentNamespaces );
478 return $contentNamespaces;
483 * List all namespace indices which are considered subject, aka not a talk
484 * or special namespace. See also NamespaceInfo::isSubject
486 * @return array Array of namespace indices
488 public function getSubjectNamespaces() {
490 $this->getValidNamespaces(),
491 [ $this, 'isSubject' ]
496 * List all namespace indices which are considered talks, aka not a subject
497 * or special namespace. See also NamespaceInfo::isTalk
499 * @return array Array of namespace indices
501 public function getTalkNamespaces() {
503 $this->getValidNamespaces(),
509 * Is the namespace first-letter capitalized?
511 * @param int $index Index to check
514 public function isCapitalized( $index ) {
515 // Turn NS_MEDIA into NS_FILE
516 $index = $index === NS_MEDIA ? NS_FILE
: $index;
518 // Make sure to get the subject of our namespace
519 $index = $this->getSubject( $index );
521 // Some namespaces are special and should always be upper case
522 if ( in_array( $index, $this->alwaysCapitalizedNamespaces
) ) {
525 $overrides = $this->options
->get( 'CapitalLinkOverrides' );
526 if ( isset( $overrides[$index] ) ) {
527 // CapitalLinkOverrides is explicitly set
528 return $overrides[$index];
530 // Default to the global setting
531 return $this->options
->get( 'CapitalLinks' );
535 * Does the namespace (potentially) have different aliases for different
536 * genders. Not all languages make a distinction here.
538 * @param int $index Index to check
541 public function hasGenderDistinction( $index ) {
542 return $index == NS_USER ||
$index == NS_USER_TALK
;
546 * It is not possible to use pages from this namespace as template?
548 * @param int $index Index to check
551 public function isNonincludable( $index ) {
552 $namespaces = $this->options
->get( 'NonincludableNamespaces' );
553 return $namespaces && in_array( $index, $namespaces );
557 * Get the default content model for a namespace
558 * This does not mean that all pages in that namespace have the model
560 * @note To determine the default model for a new page's main slot, or any slot in general,
561 * use SlotRoleHandler::getDefaultModel() together with SlotRoleRegistry::getRoleHandler().
563 * @param int $index Index to check
564 * @return null|string Default model name for the given namespace, if set
566 public function getNamespaceContentModel( $index ) {
567 return $this->options
->get( 'NamespaceContentModels' )[$index] ??
null;
571 * Determine which restriction levels it makes sense to use in a namespace,
572 * optionally filtered by a user's rights.
574 * @deprecated since 1.34 User PermissionManager::getNamespaceRestrictionLevels instead.
575 * @param int $index Index to check
576 * @param User|null $user User to check
579 public function getRestrictionLevels( $index, User
$user = null ) {
580 // PermissionManager is not injected because adding an explicit dependency
581 // breaks MW installer by adding a dependency chain on the database before
582 // it was set up. Also, the method is deprecated and will be soon removed.
583 return MediaWikiServices
::getInstance()
584 ->getPermissionManager()
585 ->getNamespaceRestrictionLevels( $index, $user );
589 * Returns the link type to be used for categories.
591 * This determines which section of a category page titles
592 * in the namespace will appear within.
594 * @param int $index Namespace index
595 * @return string One of 'subcat', 'file', 'page'
597 public function getCategoryLinkType( $index ) {
598 $this->isMethodValidFor( $index, __METHOD__
);
600 if ( $index == NS_CATEGORY
) {
602 } elseif ( $index == NS_FILE
) {
610 * Retrieve the indexes for the namespaces defined by core.
616 public static function getCommonNamespaces() {
617 return array_keys( self
::$canonicalNames );