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          * @return array
 190          * @since 1.17
 191          */
 192         public static function getCanonicalNamespaces() {
 193                 static $namespaces = null;
 194                 if ( $namespaces === null ) {
 195                         global $wgExtraNamespaces, $wgCanonicalNamespaceNames;
 196                         $namespaces = array( NS_MAIN => '' ) + $wgCanonicalNamespaceNames;
 197                         if ( is_array( $wgExtraNamespaces ) ) {
 198                                 $namespaces += $wgExtraNamespaces;
 199                         }
 200                         wfRunHooks( 'CanonicalNamespaces', array( &$namespaces ) );
 201                 }
 202                 return $namespaces;
 203         }
 204
 205         /**
 206          * Returns the canonical (English) name for a given index
 207          *
 208          * @param $index Int: namespace index
 209          * @return string or false if no canonical definition.
 210          */
 211         public static function getCanonicalName( $index ) {
 212                 $nslist = self::getCanonicalNamespaces();
 213                 if ( isset( $nslist[$index] ) ) {
 214                         return $nslist[$index];
 215                 } else {
 216                         return false;
 217                 }
 218         }
 219
 220         /**
 221          * Returns the index for a given canonical name, or NULL
 222          * The input *must* be converted to lower case first
 223          *
 224          * @param $name String: namespace name
 225          * @return int
 226          */
 227         public static function getCanonicalIndex( $name ) {
 228                 static $xNamespaces = false;
 229                 if ( $xNamespaces === false ) {
 230                         $xNamespaces = array();
 231                         foreach ( self::getCanonicalNamespaces() as $i => $text ) {
 232                                 $xNamespaces[strtolower( $text )] = $i;
 233                         }
 234                 }
 235                 if ( array_key_exists( $name, $xNamespaces ) ) {
 236                         return $xNamespaces[$name];
 237                 } else {
 238                         return null;
 239                 }
 240         }
 241
 242         /**
 243          * Returns an array of the namespaces (by integer id) that exist on the
 244          * wiki. Used primarily by the api in help documentation.
 245          * @return array
 246          */
 247         public static function getValidNamespaces() {
 248                 static $mValidNamespaces = null;
 249
 250                 if ( is_null( $mValidNamespaces ) ) {
 251                         foreach ( array_keys( self::getCanonicalNamespaces() ) as $ns ) {
 252                                 if ( $ns >= 0 ) {
 253                                         $mValidNamespaces[] = $ns;
 254                                 }
 255                         }
 256                 }
 257
 258                 return $mValidNamespaces;
 259         }
 260
 261         /**
 262          * Can this namespace ever have a talk namespace?
 263          *
 264          * @param $index Int: namespace index
 265          * @return bool
 266          */
 267          public static function canTalk( $index ) {
 268                 return $index >= NS_MAIN;
 269          }
 270
 271         /**
 272          * Does this namespace contain content, for the purposes of calculating
 273          * statistics, etc?
 274          *
 275          * @param $index Int: index to check
 276          * @return bool
 277          */
 278         public static function isContent( $index ) {
 279                 global $wgContentNamespaces;
 280                 return $index == NS_MAIN || in_array( $index, $wgContentNamespaces );
 281         }
 282
 283         /**
 284          * Can pages in a namespace be watched?
 285          *
 286          * @param $index Int
 287          * @return bool
 288          */
 289         public static function isWatchable( $index ) {
 290                 return $index >= NS_MAIN;
 291         }
 292
 293         /**
 294          * Does the namespace allow subpages?
 295          *
 296          * @param $index int Index to check
 297          * @return bool
 298          */
 299         public static function hasSubpages( $index ) {
 300                 global $wgNamespacesWithSubpages;
 301                 return !empty( $wgNamespacesWithSubpages[$index] );
 302         }
 303
 304         /**
 305          * Get a list of all namespace indices which are considered to contain content
 306          * @return array of namespace indices
 307          */
 308         public static function getContentNamespaces() {
 309                 global $wgContentNamespaces;
 310                 if ( !is_array( $wgContentNamespaces ) || $wgContentNamespaces === array() ) {
 311                         return NS_MAIN;
 312                 } elseif ( !in_array( NS_MAIN, $wgContentNamespaces ) ) {
 313                         // always force NS_MAIN to be part of array (to match the algorithm used by isContent)
 314                         return array_merge( array( NS_MAIN ), $wgContentNamespaces );
 315                 } else {
 316                         return $wgContentNamespaces;
 317                 }
 318         }
 319         /**
 320          * Is the namespace first-letter capitalized?
 321          *
 322          * @param $index int Index to check
 323          * @return bool
 324          */
 325         public static function isCapitalized( $index ) {
 326                 global $wgCapitalLinks, $wgCapitalLinkOverrides;
 327                 // Turn NS_MEDIA into NS_FILE
 328                 $index = $index === NS_MEDIA ? NS_FILE : $index;
 329
 330                 // Make sure to get the subject of our namespace
 331                 $index = self::getSubject( $index );
 332
 333                 // Some namespaces are special and should always be upper case
 334                 if ( in_array( $index, self::$alwaysCapitalizedNamespaces ) ) {
 335                         return true;
 336                 }
 337                 if ( isset( $wgCapitalLinkOverrides[ $index ] ) ) {
 338                         // $wgCapitalLinkOverrides is explicitly set
 339                         return $wgCapitalLinkOverrides[ $index ];
 340                 }
 341                 // Default to the global setting
 342                 return $wgCapitalLinks;
 343         }
 344
 345         /**
 346          * Does the namespace (potentially) have different aliases for different
 347          * genders. Not all languages make a distinction here.
 348          *
 349          * @since 1.18
 350          * @param $index int Index to check
 351          * @return bool
 352          */
 353         public static function hasGenderDistinction( $index ) {
 354                 return $index == NS_USER || $index == NS_USER_TALK;
 355         }
 356
 357 }