includes/Namespace.php

   1 <?php
   2 /**
   3  * Provide things related to namespaces.
   4  *
   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.
   9  *
  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.
  14  *
  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
  19  *
  20  * @file
  21  */
  22
  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.
  28  *
  29  * These are synonyms for the names given in the language file
  30  * Users and translators should not change them
  31  *
  32  */
  33 class MWNamespace {
  34
  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. :)
  39          */
  40         private static $alwaysCapitalizedNamespaces = array( NS_SPECIAL, NS_USER, NS_MEDIAWIKI );
  41
  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)
  47          *
  48          * @param $index
  49          * @param $method
  50          *
  51          * @throws MWException
  52          * @return bool
  53          */
  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" );
  57                 }
  58                 return true;
  59         }
  60
  61         /**
  62          * Can pages in the given namespace be moved?
  63          *
  64          * @param int $index namespace index
  65          * @return bool
  66          */
  67         public static function isMovable( $index ) {
  68                 global $wgAllowImageMoving;
  69
  70                 $result = !( $index < NS_MAIN || ( $index == NS_FILE && !$wgAllowImageMoving ) || $index == NS_CATEGORY );
  71
  72                 /**
  73                  * @since 1.20
  74                  */
  75                 wfRunHooks( 'NamespaceIsMovable', array( $index, &$result ) );
  76
  77                 return $result;
  78         }
  79
  80         /**
  81          * Is the given namespace is a subject (non-talk) namespace?
  82          *
  83          * @param int $index namespace index
  84          * @return bool
  85          * @since 1.19
  86          */
  87         public static function isSubject( $index ) {
  88                 return !self::isTalk( $index );
  89         }
  90
  91         /**
  92          * @see self::isSubject
  93          * @deprecated Please use the more consistently named isSubject (since 1.19)
  94          * @return bool
  95          */
  96         public static function isMain( $index ) {
  97                 wfDeprecated( __METHOD__, '1.19' );
  98                 return self::isSubject( $index );
  99         }
 100
 101         /**
 102          * Is the given namespace a talk namespace?
 103          *
 104          * @param int $index namespace index
 105          * @return bool
 106          */
 107         public static function isTalk( $index ) {
 108                 return $index > NS_MAIN
 109                         && $index % 2;
 110         }
 111
 112         /**
 113          * Get the talk namespace index for a given namespace
 114          *
 115          * @param int $index namespace index
 116          * @return int
 117          */
 118         public static function getTalk( $index ) {
 119                 self::isMethodValidFor( $index, __METHOD__ );
 120                 return self::isTalk( $index )
 121                         ? $index
 122                         : $index + 1;
 123         }
 124
 125         /**
 126          * Get the subject namespace index for a given namespace
 127          * Special namespaces (NS_MEDIA, NS_SPECIAL) are always the subject.
 128          *
 129          * @param int $index Namespace index
 130          * @return int
 131          */
 132         public static function getSubject( $index ) {
 133                 # Handle special namespaces
 134                 if ( $index < NS_MAIN ) {
 135                         return $index;
 136                 }
 137
 138                 return self::isTalk( $index )
 139                         ? $index - 1
 140                         : $index;
 141         }
 142
 143         /**
 144          * Get the associated namespace.
 145          * For talk namespaces, returns the subject (non-talk) namespace
 146          * For subject (non-talk) namespaces, returns the talk namespace
 147          *
 148          * @param int $index namespace index
 149          * @return int or null if no associated namespace could be found
 150          */
 151         public static function getAssociated( $index ) {
 152                 self::isMethodValidFor( $index, __METHOD__ );
 153
 154                 if ( self::isSubject( $index ) ) {
 155                         return self::getTalk( $index );
 156                 } elseif ( self::isTalk( $index ) ) {
 157                         return self::getSubject( $index );
 158                 } else {
 159                         return null;
 160                 }
 161         }
 162
 163         /**
 164          * Returns whether the specified namespace exists
 165          *
 166          * @param $index
 167          *
 168          * @return bool
 169          * @since 1.19
 170          */
 171         public static function exists( $index ) {
 172                 $nslist = self::getCanonicalNamespaces();
 173                 return isset( $nslist[$index] );
 174         }
 175
 176         /**
 177          * Returns whether the specified namespaces are the same namespace
 178          *
 179          * @note It's possible that in the future we may start using something
 180          * other than just namespace indexes. Under that circumstance making use
 181          * of this function rather than directly doing comparison will make
 182          * sure that code will not potentially break.
 183          *
 184          * @param int $ns1 The first namespace index
 185          * @param int $ns2 The second namespace index
 186          *
 187          * @return bool
 188          * @since 1.19
 189          */
 190         public static function equals( $ns1, $ns2 ) {
 191                 return $ns1 == $ns2;
 192         }
 193
 194         /**
 195          * Returns whether the specified namespaces share the same subject.
 196          * eg: NS_USER and NS_USER wil return true, as well
 197          *     NS_USER and NS_USER_TALK will return true.
 198          *
 199          * @param int $ns1 The first namespace index
 200          * @param int $ns2 The second namespace index
 201          *
 202          * @return bool
 203          * @since 1.19
 204          */
 205         public static function subjectEquals( $ns1, $ns2 ) {
 206                 return self::getSubject( $ns1 ) == self::getSubject( $ns2 );
 207         }
 208
 209         /**
 210          * Returns array of all defined namespaces with their canonical
 211          * (English) names.
 212          *
 213          * @param bool $rebuild rebuild namespace list (default = false). Used for testing.
 214          *
 215          * @return array
 216          * @since 1.17
 217          */
 218         public static function getCanonicalNamespaces( $rebuild = false ) {
 219                 static $namespaces = null;
 220                 if ( $namespaces === null || $rebuild ) {
 221                         global $wgExtraNamespaces, $wgCanonicalNamespaceNames;
 222                         $namespaces = array( NS_MAIN => '' ) + $wgCanonicalNamespaceNames;
 223                         if ( is_array( $wgExtraNamespaces ) ) {
 224                                 $namespaces += $wgExtraNamespaces;
 225                         }
 226                         wfRunHooks( 'CanonicalNamespaces', array( &$namespaces ) );
 227                 }
 228                 return $namespaces;
 229         }
 230
 231         /**
 232          * Returns the canonical (English) name for a given index
 233          *
 234          * @param int $index namespace index
 235          * @return string or false if no canonical definition.
 236          */
 237         public static function getCanonicalName( $index ) {
 238                 $nslist = self::getCanonicalNamespaces();
 239                 if ( isset( $nslist[$index] ) ) {
 240                         return $nslist[$index];
 241                 } else {
 242                         return false;
 243                 }
 244         }
 245
 246         /**
 247          * Returns the index for a given canonical name, or NULL
 248          * The input *must* be converted to lower case first
 249          *
 250          * @param string $name namespace name
 251          * @return int
 252          */
 253         public static function getCanonicalIndex( $name ) {
 254                 static $xNamespaces = false;
 255                 if ( $xNamespaces === false ) {
 256                         $xNamespaces = array();
 257                         foreach ( self::getCanonicalNamespaces() as $i => $text ) {
 258                                 $xNamespaces[strtolower( $text )] = $i;
 259                         }
 260                 }
 261                 if ( array_key_exists( $name, $xNamespaces ) ) {
 262                         return $xNamespaces[$name];
 263                 } else {
 264                         return null;
 265                 }
 266         }
 267
 268         /**
 269          * Returns an array of the namespaces (by integer id) that exist on the
 270          * wiki. Used primarily by the api in help documentation.
 271          * @return array
 272          */
 273         public static function getValidNamespaces() {
 274                 static $mValidNamespaces = null;
 275
 276                 if ( is_null( $mValidNamespaces ) ) {
 277                         foreach ( array_keys( self::getCanonicalNamespaces() ) as $ns ) {
 278                                 if ( $ns >= 0 ) {
 279                                         $mValidNamespaces[] = $ns;
 280                                 }
 281                         }
 282                 }
 283
 284                 return $mValidNamespaces;
 285         }
 286
 287         /**
 288          * Can this namespace ever have a talk namespace?
 289          *
 290          * @param int $index namespace index
 291          * @return bool
 292          */
 293         public static function canTalk( $index ) {
 294                 return $index >= NS_MAIN;
 295         }
 296
 297         /**
 298          * Does this namespace contain content, for the purposes of calculating
 299          * statistics, etc?
 300          *
 301          * @param int $index index to check
 302          * @return bool
 303          */
 304         public static function isContent( $index ) {
 305                 global $wgContentNamespaces;
 306                 return $index == NS_MAIN || in_array( $index, $wgContentNamespaces );
 307         }
 308
 309         /**
 310          * Can pages in a namespace be watched?
 311          *
 312          * @param $index Int
 313          * @return bool
 314          */
 315         public static function isWatchable( $index ) {
 316                 return $index >= NS_MAIN;
 317         }
 318
 319         /**
 320          * Does the namespace allow subpages?
 321          *
 322          * @param int $index Index to check
 323          * @return bool
 324          */
 325         public static function hasSubpages( $index ) {
 326                 global $wgNamespacesWithSubpages;
 327                 return !empty( $wgNamespacesWithSubpages[$index] );
 328         }
 329
 330         /**
 331          * Get a list of all namespace indices which are considered to contain content
 332          * @return array of namespace indices
 333          */
 334         public static function getContentNamespaces() {
 335                 global $wgContentNamespaces;
 336                 if ( !is_array( $wgContentNamespaces ) || $wgContentNamespaces === array() ) {
 337                         return array( NS_MAIN );
 338                 } elseif ( !in_array( NS_MAIN, $wgContentNamespaces ) ) {
 339                         // always force NS_MAIN to be part of array (to match the algorithm used by isContent)
 340                         return array_merge( array( NS_MAIN ), $wgContentNamespaces );
 341                 } else {
 342                         return $wgContentNamespaces;
 343                 }
 344         }
 345
 346         /**
 347          * List all namespace indices which are considered subject, aka not a talk
 348          * or special namespace. See also MWNamespace::isSubject
 349          *
 350          * @return array of namespace indices
 351          */
 352         public static function getSubjectNamespaces() {
 353                 return array_filter(
 354                         MWNamespace::getValidNamespaces(),
 355                         'MWNamespace::isSubject'
 356                 );
 357         }
 358
 359         /**
 360          * List all namespace indices which are considered talks, aka not a subject
 361          * or special namespace. See also MWNamespace::isTalk
 362          *
 363          * @return array of namespace indices
 364          */
 365         public static function getTalkNamespaces() {
 366                 return array_filter(
 367                         MWNamespace::getValidNamespaces(),
 368                         'MWNamespace::isTalk'
 369                 );
 370         }
 371
 372         /**
 373          * Is the namespace first-letter capitalized?
 374          *
 375          * @param int $index Index to check
 376          * @return bool
 377          */
 378         public static function isCapitalized( $index ) {
 379                 global $wgCapitalLinks, $wgCapitalLinkOverrides;
 380                 // Turn NS_MEDIA into NS_FILE
 381                 $index = $index === NS_MEDIA ? NS_FILE : $index;
 382
 383                 // Make sure to get the subject of our namespace
 384                 $index = self::getSubject( $index );
 385
 386                 // Some namespaces are special and should always be upper case
 387                 if ( in_array( $index, self::$alwaysCapitalizedNamespaces ) ) {
 388                         return true;
 389                 }
 390                 if ( isset( $wgCapitalLinkOverrides[$index] ) ) {
 391                         // $wgCapitalLinkOverrides is explicitly set
 392                         return $wgCapitalLinkOverrides[$index];
 393                 }
 394                 // Default to the global setting
 395                 return $wgCapitalLinks;
 396         }
 397
 398         /**
 399          * Does the namespace (potentially) have different aliases for different
 400          * genders. Not all languages make a distinction here.
 401          *
 402          * @since 1.18
 403          * @param int $index Index to check
 404          * @return bool
 405          */
 406         public static function hasGenderDistinction( $index ) {
 407                 return $index == NS_USER || $index == NS_USER_TALK;
 408         }
 409
 410         /**
 411          * It is not possible to use pages from this namespace as template?
 412          *
 413          * @since 1.20
 414          * @param int $index Index to check
 415          * @return bool
 416          */
 417         public static function isNonincludable( $index ) {
 418                 global $wgNonincludableNamespaces;
 419                 return $wgNonincludableNamespaces && in_array( $index, $wgNonincludableNamespaces );
 420         }
 421
 422         /**
 423          * Get the default content model for a namespace
 424          * This does not mean that all pages in that namespace have the model
 425          *
 426          * @since 1.21
 427          * @param int $index Index to check
 428          * @return null|string default model name for the given namespace, if set
 429          */
 430         public static function getNamespaceContentModel( $index ) {
 431                 global $wgNamespaceContentModels;
 432                 return isset( $wgNamespaceContentModels[$index] )
 433                         ? $wgNamespaceContentModels[$index]
 434                         : null;
 435         }
 436 }