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
24 * This is a utility class with only static functions
25 * for dealing with namespaces that encodes all the
26 * "magic" behaviors of them based on index. The textual
27 * names of the namespaces are handled by Language.php.
29 * These are synonyms for the names given in the language file
30 * Users and translators should not change them
35 * These namespaces should always be first-letter capitalized, now and
36 * forevermore. Historically, they could've probably been lowercased too,
37 * but some things are just too ingrained now. :)
39 private static $alwaysCapitalizedNamespaces = [ NS_SPECIAL
, NS_USER
, NS_MEDIAWIKI
];
41 /** @var string[]|null Canonical namespaces cache */
42 private static $canonicalNamespaces = null;
44 /** @var array|false Canonical namespaces index cache */
45 private static $namespaceIndexes = false;
47 /** @var int[]|null Valid namespaces cache */
48 private static $validNamespaces = null;
51 * Throw an exception when trying to get the subject or talk page
52 * for a given namespace where it does not make sense.
53 * Special namespaces are defined in includes/Defines.php and have
54 * a value below 0 (ex: NS_SPECIAL = -1 , NS_MEDIA = -2)
57 * @param string $method
62 private static function isMethodValidFor( $index, $method ) {
63 if ( $index < NS_MAIN
) {
64 throw new MWException( "$method does not make any sense for given namespace $index" );
70 * Clear internal caches
72 * For use in unit testing when namespace configuration is changed.
76 public static function clearCaches() {
77 self
::$canonicalNamespaces = null;
78 self
::$namespaceIndexes = false;
79 self
::$validNamespaces = null;
83 * Can pages in the given namespace be moved?
85 * @param int $index Namespace index
88 public static function isMovable( $index ) {
89 global $wgAllowImageMoving;
91 $result = !( $index < NS_MAIN ||
( $index == NS_FILE
&& !$wgAllowImageMoving ) );
96 Hooks
::run( 'NamespaceIsMovable', [ $index, &$result ] );
102 * Is the given namespace is a subject (non-talk) namespace?
104 * @param int $index Namespace index
108 public static function isSubject( $index ) {
109 return !self
::isTalk( $index );
113 * Is the given namespace a talk namespace?
115 * @param int $index Namespace index
118 public static function isTalk( $index ) {
119 return $index > NS_MAIN
124 * Get the talk namespace index for a given namespace
126 * @param int $index Namespace index
129 public static function getTalk( $index ) {
130 self
::isMethodValidFor( $index, __METHOD__
);
131 return self
::isTalk( $index )
137 * Get the subject namespace index for a given namespace
138 * Special namespaces (NS_MEDIA, NS_SPECIAL) are always the subject.
140 * @param int $index Namespace index
143 public static function getSubject( $index ) {
144 # Handle special namespaces
145 if ( $index < NS_MAIN
) {
149 return self
::isTalk( $index )
155 * Get the associated namespace.
156 * For talk namespaces, returns the subject (non-talk) namespace
157 * For subject (non-talk) namespaces, returns the talk namespace
159 * @param int $index Namespace index
160 * @return int|null If no associated namespace could be found
162 public static function getAssociated( $index ) {
163 self
::isMethodValidFor( $index, __METHOD__
);
165 if ( self
::isSubject( $index ) ) {
166 return self
::getTalk( $index );
167 } elseif ( self
::isTalk( $index ) ) {
168 return self
::getSubject( $index );
175 * Returns whether the specified namespace exists
182 public static function exists( $index ) {
183 $nslist = self
::getCanonicalNamespaces();
184 return isset( $nslist[$index] );
188 * Returns whether the specified namespaces are the same namespace
190 * @note It's possible that in the future we may start using something
191 * other than just namespace indexes. Under that circumstance making use
192 * of this function rather than directly doing comparison will make
193 * sure that code will not potentially break.
195 * @param int $ns1 The first namespace index
196 * @param int $ns2 The second namespace index
201 public static function equals( $ns1, $ns2 ) {
206 * Returns whether the specified namespaces share the same subject.
207 * eg: NS_USER and NS_USER wil return true, as well
208 * NS_USER and NS_USER_TALK will return true.
210 * @param int $ns1 The first namespace index
211 * @param int $ns2 The second namespace index
216 public static function subjectEquals( $ns1, $ns2 ) {
217 return self
::getSubject( $ns1 ) == self
::getSubject( $ns2 );
221 * Returns array of all defined namespaces with their canonical
224 * @param bool $rebuild Rebuild namespace list (default = false). Used for testing.
225 * Deprecated since 1.31, use self::clearCaches() instead.
230 public static function getCanonicalNamespaces( $rebuild = false ) {
235 if ( self
::$canonicalNamespaces === null ) {
236 global $wgExtraNamespaces, $wgCanonicalNamespaceNames;
237 self
::$canonicalNamespaces = [ NS_MAIN
=> '' ] +
$wgCanonicalNamespaceNames;
238 // Add extension namespaces
239 self
::$canonicalNamespaces +
=
240 ExtensionRegistry
::getInstance()->getAttribute( 'ExtensionNamespaces' );
241 if ( is_array( $wgExtraNamespaces ) ) {
242 self
::$canonicalNamespaces +
= $wgExtraNamespaces;
244 Hooks
::run( 'CanonicalNamespaces', [ &self
::$canonicalNamespaces ] );
246 return self
::$canonicalNamespaces;
250 * Returns the canonical (English) name for a given index
252 * @param int $index Namespace index
253 * @return string|bool If no canonical definition.
255 public static function getCanonicalName( $index ) {
256 $nslist = self
::getCanonicalNamespaces();
257 if ( isset( $nslist[$index] ) ) {
258 return $nslist[$index];
265 * Returns the index for a given canonical name, or NULL
266 * The input *must* be converted to lower case first
268 * @param string $name Namespace name
271 public static function getCanonicalIndex( $name ) {
272 if ( self
::$namespaceIndexes === false ) {
273 self
::$namespaceIndexes = [];
274 foreach ( self
::getCanonicalNamespaces() as $i => $text ) {
275 self
::$namespaceIndexes[strtolower( $text )] = $i;
278 if ( array_key_exists( $name, self
::$namespaceIndexes ) ) {
279 return self
::$namespaceIndexes[$name];
286 * Returns an array of the namespaces (by integer id) that exist on the
287 * wiki. Used primarily by the api in help documentation.
290 public static function getValidNamespaces() {
291 if ( is_null( self
::$validNamespaces ) ) {
292 foreach ( array_keys( self
::getCanonicalNamespaces() ) as $ns ) {
294 self
::$validNamespaces[] = $ns;
297 // T109137: sort numerically
298 sort( self
::$validNamespaces, SORT_NUMERIC
);
301 return self
::$validNamespaces;
305 * Does this namespace ever have a talk namespace?
307 * @deprecated since 1.30, use hasTalkNamespace() instead.
309 * @param int $index Namespace index
310 * @return bool True if this namespace either is or has a corresponding talk namespace.
312 public static function canTalk( $index ) {
313 return self
::hasTalkNamespace( $index );
317 * Does this namespace ever have a talk namespace?
321 * @param int $index Namespace ID
322 * @return bool True if this namespace either is or has a corresponding talk namespace.
324 public static function hasTalkNamespace( $index ) {
325 return $index >= NS_MAIN
;
329 * Does this namespace contain content, for the purposes of calculating
332 * @param int $index Index to check
335 public static function isContent( $index ) {
336 global $wgContentNamespaces;
337 return $index == NS_MAIN ||
in_array( $index, $wgContentNamespaces );
341 * Might pages in this namespace require the use of the Signature button on
344 * @param int $index Index to check
347 public static function wantSignatures( $index ) {
348 global $wgExtraSignatureNamespaces;
349 return self
::isTalk( $index ) ||
in_array( $index, $wgExtraSignatureNamespaces );
353 * Can pages in a namespace be watched?
358 public static function isWatchable( $index ) {
359 return $index >= NS_MAIN
;
363 * Does the namespace allow subpages?
365 * @param int $index Index to check
368 public static function hasSubpages( $index ) {
369 global $wgNamespacesWithSubpages;
370 return !empty( $wgNamespacesWithSubpages[$index] );
374 * Get a list of all namespace indices which are considered to contain content
375 * @return array Array of namespace indices
377 public static function getContentNamespaces() {
378 global $wgContentNamespaces;
379 if ( !is_array( $wgContentNamespaces ) ||
$wgContentNamespaces === [] ) {
381 } elseif ( !in_array( NS_MAIN
, $wgContentNamespaces ) ) {
382 // always force NS_MAIN to be part of array (to match the algorithm used by isContent)
383 return array_merge( [ NS_MAIN
], $wgContentNamespaces );
385 return $wgContentNamespaces;
390 * List all namespace indices which are considered subject, aka not a talk
391 * or special namespace. See also MWNamespace::isSubject
393 * @return array Array of namespace indices
395 public static function getSubjectNamespaces() {
397 self
::getValidNamespaces(),
398 'MWNamespace::isSubject'
403 * List all namespace indices which are considered talks, aka not a subject
404 * or special namespace. See also MWNamespace::isTalk
406 * @return array Array of namespace indices
408 public static function getTalkNamespaces() {
410 self
::getValidNamespaces(),
411 'MWNamespace::isTalk'
416 * Is the namespace first-letter capitalized?
418 * @param int $index Index to check
421 public static function isCapitalized( $index ) {
422 global $wgCapitalLinks, $wgCapitalLinkOverrides;
423 // Turn NS_MEDIA into NS_FILE
424 $index = $index === NS_MEDIA ? NS_FILE
: $index;
426 // Make sure to get the subject of our namespace
427 $index = self
::getSubject( $index );
429 // Some namespaces are special and should always be upper case
430 if ( in_array( $index, self
::$alwaysCapitalizedNamespaces ) ) {
433 if ( isset( $wgCapitalLinkOverrides[$index] ) ) {
434 // $wgCapitalLinkOverrides is explicitly set
435 return $wgCapitalLinkOverrides[$index];
437 // Default to the global setting
438 return $wgCapitalLinks;
442 * Does the namespace (potentially) have different aliases for different
443 * genders. Not all languages make a distinction here.
446 * @param int $index Index to check
449 public static function hasGenderDistinction( $index ) {
450 return $index == NS_USER ||
$index == NS_USER_TALK
;
454 * It is not possible to use pages from this namespace as template?
457 * @param int $index Index to check
460 public static function isNonincludable( $index ) {
461 global $wgNonincludableNamespaces;
462 return $wgNonincludableNamespaces && in_array( $index, $wgNonincludableNamespaces );
466 * Get the default content model for a namespace
467 * This does not mean that all pages in that namespace have the model
470 * @param int $index Index to check
471 * @return null|string Default model name for the given namespace, if set
473 public static function getNamespaceContentModel( $index ) {
474 global $wgNamespaceContentModels;
475 return $wgNamespaceContentModels[$index] ??
null;
479 * Determine which restriction levels it makes sense to use in a namespace,
480 * optionally filtered by a user's rights.
483 * @param int $index Index to check
484 * @param User $user User to check
487 public static function getRestrictionLevels( $index, User
$user = null ) {
488 global $wgNamespaceProtection, $wgRestrictionLevels;
490 if ( !isset( $wgNamespaceProtection[$index] ) ) {
491 // All levels are valid if there's no namespace restriction.
492 // But still filter by user, if necessary
493 $levels = $wgRestrictionLevels;
495 $levels = array_values( array_filter( $levels, function ( $level ) use ( $user ) {
497 if ( $right == 'sysop' ) {
498 $right = 'editprotected'; // BC
500 if ( $right == 'autoconfirmed' ) {
501 $right = 'editsemiprotected'; // BC
503 return ( $right == '' ||
$user->isAllowed( $right ) );
509 // First, get the list of groups that can edit this namespace.
510 $namespaceGroups = [];
511 $combine = 'array_merge';
512 foreach ( (array)$wgNamespaceProtection[$index] as $right ) {
513 if ( $right == 'sysop' ) {
514 $right = 'editprotected'; // BC
516 if ( $right == 'autoconfirmed' ) {
517 $right = 'editsemiprotected'; // BC
519 if ( $right != '' ) {
520 $namespaceGroups = call_user_func( $combine, $namespaceGroups,
521 User
::getGroupsWithPermission( $right ) );
522 $combine = 'array_intersect';
526 // Now, keep only those restriction levels where there is at least one
527 // group that can edit the namespace but would be blocked by the
529 $usableLevels = [ '' ];
530 foreach ( $wgRestrictionLevels as $level ) {
532 if ( $right == 'sysop' ) {
533 $right = 'editprotected'; // BC
535 if ( $right == 'autoconfirmed' ) {
536 $right = 'editsemiprotected'; // BC
538 if ( $right != '' && ( !$user ||
$user->isAllowed( $right ) ) &&
539 array_diff( $namespaceGroups, User
::getGroupsWithPermission( $right ) )
541 $usableLevels[] = $level;
545 return $usableLevels;