Localisation updates from https://translatewiki.net.
[mediawiki.git] / includes / MWNamespace.php
blobbd6855145347acfab9cfd66695a29d643f374449
1 <?php
2 /**
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
20 * @file
23 /**
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
33 class MWNamespace {
35 /**
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 static $alwaysCapitalizedNamespaces = array( NS_SPECIAL, NS_USER, NS_MEDIAWIKI );
42 /**
43 * Throw an exception when trying to get the subject or talk page
44 * for a given namespace where it does not make sense.
45 * Special namespaces are defined in includes/Defines.php and have
46 * a value below 0 (ex: NS_SPECIAL = -1 , NS_MEDIA = -2)
48 * @param int $index
49 * @param string $method
51 * @throws MWException
52 * @return bool
54 private static function isMethodValidFor( $index, $method ) {
55 if ( $index < NS_MAIN ) {
56 throw new MWException( "$method does not make any sense for given namespace $index" );
58 return true;
61 /**
62 * Can pages in the given namespace be moved?
64 * @param int $index Namespace index
65 * @return bool
67 public static function isMovable( $index ) {
68 global $wgAllowImageMoving;
70 $result = !( $index < NS_MAIN || ( $index == NS_FILE && !$wgAllowImageMoving ) );
72 /**
73 * @since 1.20
75 Hooks::run( 'NamespaceIsMovable', array( $index, &$result ) );
77 return $result;
80 /**
81 * Is the given namespace is a subject (non-talk) namespace?
83 * @param int $index Namespace index
84 * @return bool
85 * @since 1.19
87 public static function isSubject( $index ) {
88 return !self::isTalk( $index );
91 /**
92 * Is the given namespace a talk namespace?
94 * @param int $index Namespace index
95 * @return bool
97 public static function isTalk( $index ) {
98 return $index > NS_MAIN
99 && $index % 2;
103 * Get the talk namespace index for a given namespace
105 * @param int $index Namespace index
106 * @return int
108 public static function getTalk( $index ) {
109 self::isMethodValidFor( $index, __METHOD__ );
110 return self::isTalk( $index )
111 ? $index
112 : $index + 1;
116 * Get the subject namespace index for a given namespace
117 * Special namespaces (NS_MEDIA, NS_SPECIAL) are always the subject.
119 * @param int $index Namespace index
120 * @return int
122 public static function getSubject( $index ) {
123 # Handle special namespaces
124 if ( $index < NS_MAIN ) {
125 return $index;
128 return self::isTalk( $index )
129 ? $index - 1
130 : $index;
134 * Get the associated namespace.
135 * For talk namespaces, returns the subject (non-talk) namespace
136 * For subject (non-talk) namespaces, returns the talk namespace
138 * @param int $index Namespace index
139 * @return int|null If no associated namespace could be found
141 public static function getAssociated( $index ) {
142 self::isMethodValidFor( $index, __METHOD__ );
144 if ( self::isSubject( $index ) ) {
145 return self::getTalk( $index );
146 } elseif ( self::isTalk( $index ) ) {
147 return self::getSubject( $index );
148 } else {
149 return null;
154 * Returns whether the specified namespace exists
156 * @param int $index
158 * @return bool
159 * @since 1.19
161 public static function exists( $index ) {
162 $nslist = self::getCanonicalNamespaces();
163 return isset( $nslist[$index] );
167 * Returns whether the specified namespaces are the same namespace
169 * @note It's possible that in the future we may start using something
170 * other than just namespace indexes. Under that circumstance making use
171 * of this function rather than directly doing comparison will make
172 * sure that code will not potentially break.
174 * @param int $ns1 The first namespace index
175 * @param int $ns2 The second namespace index
177 * @return bool
178 * @since 1.19
180 public static function equals( $ns1, $ns2 ) {
181 return $ns1 == $ns2;
185 * Returns whether the specified namespaces share the same subject.
186 * eg: NS_USER and NS_USER wil return true, as well
187 * NS_USER and NS_USER_TALK will return true.
189 * @param int $ns1 The first namespace index
190 * @param int $ns2 The second namespace index
192 * @return bool
193 * @since 1.19
195 public static function subjectEquals( $ns1, $ns2 ) {
196 return self::getSubject( $ns1 ) == self::getSubject( $ns2 );
200 * Returns array of all defined namespaces with their canonical
201 * (English) names.
203 * @param bool $rebuild Rebuild namespace list (default = false). Used for testing.
205 * @return array
206 * @since 1.17
208 public static function getCanonicalNamespaces( $rebuild = false ) {
209 static $namespaces = null;
210 if ( $namespaces === null || $rebuild ) {
211 global $wgExtraNamespaces, $wgCanonicalNamespaceNames;
212 $namespaces = array( NS_MAIN => '' ) + $wgCanonicalNamespaceNames;
213 if ( is_array( $wgExtraNamespaces ) ) {
214 $namespaces += $wgExtraNamespaces;
216 Hooks::run( 'CanonicalNamespaces', array( &$namespaces ) );
218 return $namespaces;
222 * Returns the canonical (English) name for a given index
224 * @param int $index Namespace index
225 * @return string|bool If no canonical definition.
227 public static function getCanonicalName( $index ) {
228 $nslist = self::getCanonicalNamespaces();
229 if ( isset( $nslist[$index] ) ) {
230 return $nslist[$index];
231 } else {
232 return false;
237 * Returns the index for a given canonical name, or NULL
238 * The input *must* be converted to lower case first
240 * @param string $name Namespace name
241 * @return int
243 public static function getCanonicalIndex( $name ) {
244 static $xNamespaces = false;
245 if ( $xNamespaces === false ) {
246 $xNamespaces = array();
247 foreach ( self::getCanonicalNamespaces() as $i => $text ) {
248 $xNamespaces[strtolower( $text )] = $i;
251 if ( array_key_exists( $name, $xNamespaces ) ) {
252 return $xNamespaces[$name];
253 } else {
254 return null;
259 * Returns an array of the namespaces (by integer id) that exist on the
260 * wiki. Used primarily by the api in help documentation.
261 * @return array
263 public static function getValidNamespaces() {
264 static $mValidNamespaces = null;
266 if ( is_null( $mValidNamespaces ) ) {
267 foreach ( array_keys( self::getCanonicalNamespaces() ) as $ns ) {
268 if ( $ns >= 0 ) {
269 $mValidNamespaces[] = $ns;
274 return $mValidNamespaces;
278 * Can this namespace ever have a talk namespace?
280 * @param int $index Namespace index
281 * @return bool
283 public static function canTalk( $index ) {
284 return $index >= NS_MAIN;
288 * Does this namespace contain content, for the purposes of calculating
289 * statistics, etc?
291 * @param int $index Index to check
292 * @return bool
294 public static function isContent( $index ) {
295 global $wgContentNamespaces;
296 return $index == NS_MAIN || in_array( $index, $wgContentNamespaces );
300 * Can pages in a namespace be watched?
302 * @param int $index
303 * @return bool
305 public static function isWatchable( $index ) {
306 return $index >= NS_MAIN;
310 * Does the namespace allow subpages?
312 * @param int $index Index to check
313 * @return bool
315 public static function hasSubpages( $index ) {
316 global $wgNamespacesWithSubpages;
317 return !empty( $wgNamespacesWithSubpages[$index] );
321 * Get a list of all namespace indices which are considered to contain content
322 * @return array Array of namespace indices
324 public static function getContentNamespaces() {
325 global $wgContentNamespaces;
326 if ( !is_array( $wgContentNamespaces ) || $wgContentNamespaces === array() ) {
327 return array( NS_MAIN );
328 } elseif ( !in_array( NS_MAIN, $wgContentNamespaces ) ) {
329 // always force NS_MAIN to be part of array (to match the algorithm used by isContent)
330 return array_merge( array( NS_MAIN ), $wgContentNamespaces );
331 } else {
332 return $wgContentNamespaces;
337 * List all namespace indices which are considered subject, aka not a talk
338 * or special namespace. See also MWNamespace::isSubject
340 * @return array Array of namespace indices
342 public static function getSubjectNamespaces() {
343 return array_filter(
344 MWNamespace::getValidNamespaces(),
345 'MWNamespace::isSubject'
350 * List all namespace indices which are considered talks, aka not a subject
351 * or special namespace. See also MWNamespace::isTalk
353 * @return array Array of namespace indices
355 public static function getTalkNamespaces() {
356 return array_filter(
357 MWNamespace::getValidNamespaces(),
358 'MWNamespace::isTalk'
363 * Is the namespace first-letter capitalized?
365 * @param int $index Index to check
366 * @return bool
368 public static function isCapitalized( $index ) {
369 global $wgCapitalLinks, $wgCapitalLinkOverrides;
370 // Turn NS_MEDIA into NS_FILE
371 $index = $index === NS_MEDIA ? NS_FILE : $index;
373 // Make sure to get the subject of our namespace
374 $index = self::getSubject( $index );
376 // Some namespaces are special and should always be upper case
377 if ( in_array( $index, self::$alwaysCapitalizedNamespaces ) ) {
378 return true;
380 if ( isset( $wgCapitalLinkOverrides[$index] ) ) {
381 // $wgCapitalLinkOverrides is explicitly set
382 return $wgCapitalLinkOverrides[$index];
384 // Default to the global setting
385 return $wgCapitalLinks;
389 * Does the namespace (potentially) have different aliases for different
390 * genders. Not all languages make a distinction here.
392 * @since 1.18
393 * @param int $index Index to check
394 * @return bool
396 public static function hasGenderDistinction( $index ) {
397 return $index == NS_USER || $index == NS_USER_TALK;
401 * It is not possible to use pages from this namespace as template?
403 * @since 1.20
404 * @param int $index Index to check
405 * @return bool
407 public static function isNonincludable( $index ) {
408 global $wgNonincludableNamespaces;
409 return $wgNonincludableNamespaces && in_array( $index, $wgNonincludableNamespaces );
413 * Get the default content model for a namespace
414 * This does not mean that all pages in that namespace have the model
416 * @since 1.21
417 * @param int $index Index to check
418 * @return null|string Default model name for the given namespace, if set
420 public static function getNamespaceContentModel( $index ) {
421 global $wgNamespaceContentModels;
422 return isset( $wgNamespaceContentModels[$index] )
423 ? $wgNamespaceContentModels[$index]
424 : null;
428 * Determine which restriction levels it makes sense to use in a namespace,
429 * optionally filtered by a user's rights.
431 * @since 1.23
432 * @param int $index Index to check
433 * @param User $user User to check
434 * @return array
436 public static function getRestrictionLevels( $index, User $user = null ) {
437 global $wgNamespaceProtection, $wgRestrictionLevels;
439 if ( !isset( $wgNamespaceProtection[$index] ) ) {
440 // All levels are valid if there's no namespace restriction.
441 // But still filter by user, if necessary
442 $levels = $wgRestrictionLevels;
443 if ( $user ) {
444 $levels = array_values( array_filter( $levels, function ( $level ) use ( $user ) {
445 $right = $level;
446 if ( $right == 'sysop' ) {
447 $right = 'editprotected'; // BC
449 if ( $right == 'autoconfirmed' ) {
450 $right = 'editsemiprotected'; // BC
452 return ( $right == '' || $user->isAllowed( $right ) );
453 } ) );
455 return $levels;
458 // First, get the list of groups that can edit this namespace.
459 $namespaceGroups = array();
460 $combine = 'array_merge';
461 foreach ( (array)$wgNamespaceProtection[$index] as $right ) {
462 if ( $right == 'sysop' ) {
463 $right = 'editprotected'; // BC
465 if ( $right == 'autoconfirmed' ) {
466 $right = 'editsemiprotected'; // BC
468 if ( $right != '' ) {
469 $namespaceGroups = call_user_func( $combine, $namespaceGroups,
470 User::getGroupsWithPermission( $right ) );
471 $combine = 'array_intersect';
475 // Now, keep only those restriction levels where there is at least one
476 // group that can edit the namespace but would be blocked by the
477 // restriction.
478 $usableLevels = array( '' );
479 foreach ( $wgRestrictionLevels as $level ) {
480 $right = $level;
481 if ( $right == 'sysop' ) {
482 $right = 'editprotected'; // BC
484 if ( $right == 'autoconfirmed' ) {
485 $right = 'editsemiprotected'; // BC
487 if ( $right != '' && ( !$user || $user->isAllowed( $right ) ) &&
488 array_diff( $namespaceGroups, User::getGroupsWithPermission( $right ) )
490 $usableLevels[] = $level;
494 return $usableLevels;