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