includes/Namespace.php

   1 <?php
   2 /**
   3  * Provide things related to namespaces
   4  * @file
   5  */
   6
   7 /**
   8  * This is a utility class with only static functions
   9  * for dealing with namespaces that encodes all the
  10  * "magic" behaviors of them based on index.  The textual
  11  * names of the namespaces are handled by Language.php.
  12  *
  13  * These are synonyms for the names given in the language file
  14  * Users and translators should not change them
  15  *
  16  */
  17
  18 class MWNamespace {
  19
  20         /**
  21          * These namespaces should always be first-letter capitalized, now and
  22          * forevermore. Historically, they could've probably been lowercased too,
  23          * but some things are just too ingrained now. :)
  24          */
  25         private static $alwaysCapitalizedNamespaces = array( NS_SPECIAL, NS_USER, NS_MEDIAWIKI );
  26
  27         /**
  28          * Throw an exception when trying to get the subject or talk page
  29          * for a given namespace where it does not make sense.
  30          * Special namespaces are defined in includes/Defines.php and have
  31          * a value below 0 (ex: NS_SPECIAL = -1 , NS_MEDIA = -2)
  32          *
  33          * @param $index
  34          * @param $method
  35          *
  36          * @return bool
  37          */
  38         private static function isMethodValidFor( $index, $method ) {
  39                 if ( $index < NS_MAIN ) {
  40                         throw new MWException( "$method does not make any sense for given namespace $index" );
  41                 }
  42                 return true;
  43         }
  44
  45         /**
  46          * Can pages in the given namespace be moved?
  47          *
  48          * @param $index Int: namespace index
  49          * @return bool
  50          */
  51         public static function isMovable( $index ) {
  52                 global $wgAllowImageMoving;
  53                 return !( $index < NS_MAIN || ( $index == NS_FILE && !$wgAllowImageMoving )  || $index == NS_CATEGORY );
  54         }
  55
  56         /**
  57          * Is the given namespace is a subject (non-talk) namespace?
  58          *
  59          * @param $index Int: namespace index
  60          * @return bool
  61          * @since 1.19
  62          */
  63         public static function isSubject( $index ) {
  64                 return !self::isTalk( $index );
  65         }
  66
  67         /**
  68          * @see self::isSubject
  69          * @deprecated Please use the more consistently named isSubject (since 1.19)
  70          * @return bool
  71          */
  72         public static function isMain( $index ) {
  73                 wfDeprecated( __METHOD__, '1.19' );
  74                 return self::isSubject( $index );
  75         }
  76
  77         /**
  78          * Is the given namespace a talk namespace?
  79          *
  80          * @param $index Int: namespace index
  81          * @return bool
  82          */
  83         public static function isTalk( $index ) {
  84                 return $index > NS_MAIN
  85                         && $index % 2;
  86         }
  87
  88         /**
  89          * Get the talk namespace index for a given namespace
  90          *
  91          * @param $index Int: namespace index
  92          * @return int
  93          */
  94         public static function getTalk( $index ) {
  95                 self::isMethodValidFor( $index, __METHOD__ );
  96                 return self::isTalk( $index )
  97                         ? $index
  98                         : $index + 1;
  99         }
 100
 101         /**
 102          * Get the subject namespace index for a given namespace
 103          * Special namespaces (NS_MEDIA, NS_SPECIAL) are always the subject.
 104          *
 105          * @param $index Int: Namespace index
 106          * @return int
 107          */
 108         public static function getSubject( $index ) {
 109                 # Handle special namespaces
 110                 if ( $index < NS_MAIN ) {
 111                         return $index;
 112                 }
 113
 114                 return self::isTalk( $index )
 115                         ? $index - 1
 116                         : $index;
 117         }
 118
 119         /**
 120          * Get the associated namespace.
 121          * For talk namespaces, returns the subject (non-talk) namespace
 122          * For subject (non-talk) namespaces, returns the talk namespace
 123          *
 124          * @param $index Int: namespace index
 125          * @return int or null if no associated namespace could be found
 126          */
 127         public static function getAssociated( $index ) {
 128                 self::isMethodValidFor( $index, __METHOD__ );
 129
 130                 if ( self::isSubject( $index ) ) {
 131                         return self::getTalk( $index );
 132                 } elseif ( self::isTalk( $index ) ) {
 133                         return self::getSubject( $index );
 134                 } else {
 135                         return null;
 136                 }
 137         }
 138
 139         /**
 140          * Returns whether the specified namespace exists
 141          *
 142          * @param $index
 143          *
 144          * @return bool
 145          * @since 1.19
 146          */
 147         public static function exists( $index ) {
 148                 $nslist = self::getCanonicalNamespaces();
 149                 return isset( $nslist[$index] );
 150         }
 151
 152         /**
 153          * Returns whether the specified namespaces are the same namespace
 154          *
 155          * @note It's possible that in the future we may start using something
 156          * other than just namespace indexes. Under that circumstance making use
 157          * of this function rather than directly doing comparison will make
 158          * sure that code will not potentially break.
 159          *
 160          * @param $ns1 int The first namespace index
 161          * @param $ns2 int The second namespae index
 162          *
 163          * @return bool
 164          * @since 1.19
 165          */
 166         public static function equals( $ns1, $ns2 ) {
 167                 return $ns1 == $ns2;
 168         }
 169
 170         /**
 171          * Returns whether the specified namespaces share the same subject.
 172          * eg: NS_USER and NS_USER wil return true, as well
 173          *     NS_USER and NS_USER_TALK will return true.
 174          *
 175          * @param $ns1 int The first namespace index
 176          * @param $ns2 int The second namespae index
 177          *
 178          * @return bool
 179          * @since 1.19
 180          */
 181         public static function subjectEquals( $ns1, $ns2 ) {
 182                 return self::getSubject( $ns1 ) == self::getSubject( $ns2 );
 183         }
 184
 185         /**
 186          * Returns array of all defined namespaces with their canonical
 187          * (English) names.
 188          *
 189          * @param bool $rebuild rebuild namespace list (default = false). Used for testing.
 190          *
 191          * @return array
 192          * @since 1.17
 193          */
 194         public static function getCanonicalNamespaces( $rebuild = false ) {
 195                 static $namespaces = null;
 196                 if ( $namespaces === null || $rebuild ) {
 197                         global $wgExtraNamespaces, $wgCanonicalNamespaceNames;
 198                         $namespaces = array( NS_MAIN => '' ) + $wgCanonicalNamespaceNames;
 199                         if ( is_array( $wgExtraNamespaces ) ) {
 200                                 $namespaces += $wgExtraNamespaces;
 201                         }
 202                         wfRunHooks( 'CanonicalNamespaces', array( &$namespaces ) );
 203                 }
 204                 return $namespaces;
 205         }
 206
 207         /**
 208          * Returns the canonical (English) name for a given index
 209          *
 210          * @param $index Int: namespace index
 211          * @return string or false if no canonical definition.
 212          */
 213         public static function getCanonicalName( $index ) {
 214                 $nslist = self::getCanonicalNamespaces();
 215                 if ( isset( $nslist[$index] ) ) {
 216                         return $nslist[$index];
 217                 } else {
 218                         return false;
 219                 }
 220         }
 221
 222         /**
 223          * Returns the index for a given canonical name, or NULL
 224          * The input *must* be converted to lower case first
 225          *
 226          * @param $name String: namespace name
 227          * @return int
 228          */
 229         public static function getCanonicalIndex( $name ) {
 230                 static $xNamespaces = false;
 231                 if ( $xNamespaces === false ) {
 232                         $xNamespaces = array();
 233                         foreach ( self::getCanonicalNamespaces() as $i => $text ) {
 234                                 $xNamespaces[strtolower( $text )] = $i;
 235                         }
 236                 }
 237                 if ( array_key_exists( $name, $xNamespaces ) ) {
 238                         return $xNamespaces[$name];
 239                 } else {
 240                         return null;
 241                 }
 242         }
 243
 244         /**
 245          * Returns an array of the namespaces (by integer id) that exist on the
 246          * wiki. Used primarily by the api in help documentation.
 247          * @return array
 248          */
 249         public static function getValidNamespaces() {
 250                 static $mValidNamespaces = null;
 251
 252                 if ( is_null( $mValidNamespaces ) ) {
 253                         foreach ( array_keys( self::getCanonicalNamespaces() ) as $ns ) {
 254                                 if ( $ns >= 0 ) {
 255                                         $mValidNamespaces[] = $ns;
 256                                 }
 257                         }
 258                 }
 259
 260                 return $mValidNamespaces;
 261         }
 262
 263         /**
 264          * Can this namespace ever have a talk namespace?
 265          *
 266          * @param $index Int: namespace index
 267          * @return bool
 268          */
 269          public static function canTalk( $index ) {
 270                 return $index >= NS_MAIN;
 271          }
 272
 273         /**
 274          * Does this namespace contain content, for the purposes of calculating
 275          * statistics, etc?
 276          *
 277          * @param $index Int: index to check
 278          * @return bool
 279          */
 280         public static function isContent( $index ) {
 281                 global $wgContentNamespaces;
 282                 return $index == NS_MAIN || in_array( $index, $wgContentNamespaces );
 283         }
 284
 285         /**
 286          * Can pages in a namespace be watched?
 287          *
 288          * @param $index Int
 289          * @return bool
 290          */
 291         public static function isWatchable( $index ) {
 292                 return $index >= NS_MAIN;
 293         }
 294
 295         /**
 296          * Does the namespace allow subpages?
 297          *
 298          * @param $index int Index to check
 299          * @return bool
 300          */
 301         public static function hasSubpages( $index ) {
 302                 global $wgNamespacesWithSubpages;
 303                 return !empty( $wgNamespacesWithSubpages[$index] );
 304         }
 305
 306         /**
 307          * Get a list of all namespace indices which are considered to contain content
 308          * @return array of namespace indices
 309          */
 310         public static function getContentNamespaces() {
 311                 global $wgContentNamespaces;
 312                 if ( !is_array( $wgContentNamespaces ) || $wgContentNamespaces === array() ) {
 313                         return NS_MAIN;
 314                 } elseif ( !in_array( NS_MAIN, $wgContentNamespaces ) ) {
 315                         // always force NS_MAIN to be part of array (to match the algorithm used by isContent)
 316                         return array_merge( array( NS_MAIN ), $wgContentNamespaces );
 317                 } else {
 318                         return $wgContentNamespaces;
 319                 }
 320         }
 321         /**
 322          * Is the namespace first-letter capitalized?
 323          *
 324          * @param $index int Index to check
 325          * @return bool
 326          */
 327         public static function isCapitalized( $index ) {
 328                 global $wgCapitalLinks, $wgCapitalLinkOverrides;
 329                 // Turn NS_MEDIA into NS_FILE
 330                 $index = $index === NS_MEDIA ? NS_FILE : $index;
 331
 332                 // Make sure to get the subject of our namespace
 333                 $index = self::getSubject( $index );
 334
 335                 // Some namespaces are special and should always be upper case
 336                 if ( in_array( $index, self::$alwaysCapitalizedNamespaces ) ) {
 337                         return true;
 338                 }
 339                 if ( isset( $wgCapitalLinkOverrides[ $index ] ) ) {
 340                         // $wgCapitalLinkOverrides is explicitly set
 341                         return $wgCapitalLinkOverrides[ $index ];
 342                 }
 343                 // Default to the global setting
 344                 return $wgCapitalLinks;
 345         }
 346
 347         /**
 348          * Does the namespace (potentially) have different aliases for different
 349          * genders. Not all languages make a distinction here.
 350          *
 351          * @since 1.18
 352          * @param $index int Index to check
 353          * @return bool
 354          */
 355         public static function hasGenderDistinction( $index ) {
 356                 return $index == NS_USER || $index == NS_USER_TALK;
 357         }
 358
 359 }