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 true
  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          */
  71         public static function isMain( $index ) {
  72                 return self::isSubject( $index );
  73         }
  74
  75         /**
  76          * Is the given namespace a talk namespace?
  77          *
  78          * @param $index Int: namespace index
  79          * @return bool
  80          */
  81         public static function isTalk( $index ) {
  82                 return $index > NS_MAIN
  83                         && $index % 2;
  84         }
  85
  86         /**
  87          * Get the talk namespace index for a given namespace
  88          *
  89          * @param $index Int: namespace index
  90          * @return int
  91          */
  92         public static function getTalk( $index ) {
  93                 self::isMethodValidFor( $index, __METHOD__ );
  94                 return self::isTalk( $index )
  95                         ? $index
  96                         : $index + 1;
  97         }
  98
  99         /**
 100          * Get the subject namespace index for a given namespace
 101          * Special namespaces (NS_MEDIA, NS_SPECIAL) are always the subject.
 102          *
 103          * @param $index Int: Namespace index
 104          * @return int
 105          */
 106         public static function getSubject( $index ) {
 107                 # Handle special namespaces
 108                 if( $index < NS_MAIN ) {
 109                         return $index;
 110                 }
 111
 112                 return self::isTalk( $index )
 113                         ? $index - 1
 114                         : $index;
 115         }
 116
 117         /**
 118          * Get the associated namespace.
 119          * For talk namespaces, returns the subject (non-talk) namespace
 120          * For subject (non-talk) namespaces, returns the talk namespace
 121          *
 122          * @param $index Int: namespace index
 123          * @return int or null if no associated namespace could be found
 124          */
 125         public static function getAssociated( $index ) {
 126                 self::isMethodValidFor( $index, __METHOD__ );
 127
 128                 if( self::isMain( $index ) ) {
 129                         return self::getTalk( $index );
 130                 } elseif( self::isTalk( $index ) ) {
 131                         return self::getSubject( $index );
 132                 } else {
 133                         return null;
 134                 }
 135         }
 136
 137         /**
 138          * Returns whether the specified namespace exists
 139          *
 140          * @param $index
 141          *
 142          * @return bool
 143          * @since 1.19
 144          */
 145         public static function exists( $index ) {
 146                 $nslist = self::getCanonicalNamespaces();
 147                 return isset( $nslist[$index] );
 148         }
 149
 150         /**
 151          * Returns whether the specified namespaces are the same namespace
 152          *
 153          * @note It's possible that in the future we may start using something
 154          * other than just namespace indexes. Under that circumstance making use
 155          * of this function rather than directly doing comparison will make
 156          * sure that code will not potentially break.
 157          *
 158          * @param $ns1 int The first namespace index
 159          * @param $ns2 int The second namespae index
 160          *
 161          * @return bool
 162          * @since 1.19
 163          */
 164         public static function equals( $ns1, $ns2 ) {
 165                 return $ns1 == $ns2;
 166         }
 167
 168         /**
 169          * Returns whether the specified namespaces share the same subject.
 170          * eg: NS_USER and NS_USER wil return true, as well
 171          *     NS_USER and NS_USER_TALK will return true.
 172          *
 173          * @param $ns1 int The first namespace index
 174          * @param $ns2 int The second namespae index
 175          *
 176          * @return bool
 177          * @since 1.19
 178          */
 179         public static function subjectEquals( $ns1, $ns2 ) {
 180                 return self::getSubject( $ns1 ) == self::getSubject( $ns2 );
 181         }
 182
 183         /**
 184          * Returns array of all defined namespaces with their canonical
 185          * (English) names.
 186          *
 187          * @return \array
 188          * @since 1.17
 189          */
 190         public static function getCanonicalNamespaces() {
 191                 static $namespaces = null;
 192                 if ( $namespaces === null ) {
 193                         global $wgExtraNamespaces, $wgCanonicalNamespaceNames;
 194                         $namespaces = array( NS_MAIN => '' ) + $wgCanonicalNamespaceNames;
 195                         if ( is_array( $wgExtraNamespaces ) ) {
 196                                 $namespaces += $wgExtraNamespaces;
 197                         }
 198                         wfRunHooks( 'CanonicalNamespaces', array( &$namespaces ) );
 199                 }
 200                 return $namespaces;
 201         }
 202
 203         /**
 204          * Returns the canonical (English) name for a given index
 205          *
 206          * @param $index Int: namespace index
 207          * @return string or false if no canonical definition.
 208          */
 209         public static function getCanonicalName( $index ) {
 210                 $nslist = self::getCanonicalNamespaces();
 211                 if( isset( $nslist[$index] ) ) {
 212                         return $nslist[$index];
 213                 } else {
 214                         return false;
 215                 }
 216         }
 217
 218         /**
 219          * Returns the index for a given canonical name, or NULL
 220          * The input *must* be converted to lower case first
 221          *
 222          * @param $name String: namespace name
 223          * @return int
 224          */
 225         public static function getCanonicalIndex( $name ) {
 226                 static $xNamespaces = false;
 227                 if ( $xNamespaces === false ) {
 228                         $xNamespaces = array();
 229                         foreach ( self::getCanonicalNamespaces() as $i => $text ) {
 230                                 $xNamespaces[strtolower($text)] = $i;
 231                         }
 232                 }
 233                 if ( array_key_exists( $name, $xNamespaces ) ) {
 234                         return $xNamespaces[$name];
 235                 } else {
 236                         return null;
 237                 }
 238         }
 239
 240         /**
 241          * Returns an array of the namespaces (by integer id) that exist on the
 242          * wiki. Used primarily by the api in help documentation.
 243          * @return array
 244          */
 245         public static function getValidNamespaces() {
 246                 static $mValidNamespaces = null;
 247
 248                 if ( is_null( $mValidNamespaces ) ) {
 249                         foreach ( array_keys( self::getCanonicalNamespaces() ) as $ns ) {
 250                                 if ( $ns >= 0 ) {
 251                                         $mValidNamespaces[] = $ns;
 252                                 }
 253                         }
 254                 }
 255
 256                 return $mValidNamespaces;
 257         }
 258
 259         /**
 260          * Can this namespace ever have a talk namespace?
 261          *
 262          * @param $index Int: namespace index
 263          * @return bool
 264          */
 265          public static function canTalk( $index ) {
 266                 return $index >= NS_MAIN;
 267          }
 268
 269         /**
 270          * Does this namespace contain content, for the purposes of calculating
 271          * statistics, etc?
 272          *
 273          * @param $index Int: index to check
 274          * @return bool
 275          */
 276         public static function isContent( $index ) {
 277                 global $wgContentNamespaces;
 278                 return $index == NS_MAIN || in_array( $index, $wgContentNamespaces );
 279         }
 280
 281         /**
 282          * Can pages in a namespace be watched?
 283          *
 284          * @param $index Int
 285          * @return bool
 286          */
 287         public static function isWatchable( $index ) {
 288                 return $index >= NS_MAIN;
 289         }
 290
 291         /**
 292          * Does the namespace allow subpages?
 293          *
 294          * @param $index int Index to check
 295          * @return bool
 296          */
 297         public static function hasSubpages( $index ) {
 298                 global $wgNamespacesWithSubpages;
 299                 return !empty( $wgNamespacesWithSubpages[$index] );
 300         }
 301
 302         /**
 303          * Get a list of all namespace indices which are considered to contain content
 304          * @return array of namespace indices
 305          */
 306         public static function getContentNamespaces() {
 307                 global $wgContentNamespaces;
 308                 if( !is_array( $wgContentNamespaces ) || $wgContentNamespaces === array() ) {
 309                         return NS_MAIN;
 310                 } elseif ( !in_array( NS_MAIN, $wgContentNamespaces ) ) {
 311                         // always force NS_MAIN to be part of array (to match the algorithm used by isContent)
 312                         return array_merge( array( NS_MAIN ), $wgContentNamespaces );
 313                 } else {
 314                         return $wgContentNamespaces;
 315                 }
 316         }
 317         /**
 318          * Is the namespace first-letter capitalized?
 319          *
 320          * @param $index int Index to check
 321          * @return bool
 322          */
 323         public static function isCapitalized( $index ) {
 324                 global $wgCapitalLinks, $wgCapitalLinkOverrides;
 325                 // Turn NS_MEDIA into NS_FILE
 326                 $index = $index === NS_MEDIA ? NS_FILE : $index;
 327
 328                 // Make sure to get the subject of our namespace
 329                 $index = self::getSubject( $index );
 330
 331                 // Some namespaces are special and should always be upper case
 332                 if ( in_array( $index, self::$alwaysCapitalizedNamespaces ) ) {
 333                         return true;
 334                 }
 335                 if ( isset( $wgCapitalLinkOverrides[ $index ] ) ) {
 336                         // $wgCapitalLinkOverrides is explicitly set
 337                         return $wgCapitalLinkOverrides[ $index ];
 338                 }
 339                 // Default to the global setting
 340                 return $wgCapitalLinks;
 341         }
 342
 343         /**
 344          * Does the namespace (potentially) have different aliases for different
 345          * genders. Not all languages make a distinction here.
 346          *
 347          * @since 1.18
 348          * @param $index int Index to check
 349          * @return bool
 350          */
 351         public static function hasGenderDistinction( $index ) {
 352                 return $index == NS_USER || $index == NS_USER_TALK;
 353         }
 354
 355 }