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/define.php and have
  31          * a value below 0 (ex: NS_SPECIAL = -1 , NS_MEDIA = -2)
  32          *
  33          * @param $ns Int: namespace index
  34          */
  35         private static function isMethodValidFor( $index, $method ) {
  36                 if( $index < NS_MAIN ) {
  37                         throw new MWException( "$method does not make any sense for given namespace $index" );
  38                 }
  39                 return true;
  40         }
  41
  42         /**
  43          * Can pages in the given namespace be moved?
  44          *
  45          * @param $index Int: namespace index
  46          * @return bool
  47          */
  48         public static function isMovable( $index ) {
  49                 global $wgAllowImageMoving;
  50                 return !( $index < NS_MAIN || ($index == NS_FILE && !$wgAllowImageMoving)  || $index == NS_CATEGORY );
  51         }
  52
  53         /**
  54          * Is the given namespace is a subject (non-talk) namespace?
  55          *
  56          * @param $index Int: namespace index
  57          * @return bool
  58          */
  59         public static function isMain( $index ) {
  60                 return !self::isTalk( $index );
  61         }
  62
  63         /**
  64          * Is the given namespace a talk namespace?
  65          *
  66          * @param $index Int: namespace index
  67          * @return bool
  68          */
  69         public static function isTalk( $index ) {
  70                 return $index > NS_MAIN
  71                         && $index % 2;
  72         }
  73
  74         /**
  75          * Get the talk namespace index for a given namespace
  76          *
  77          * @param $index Int: namespace index
  78          * @return int
  79          */
  80         public static function getTalk( $index ) {
  81                 self::isMethodValidFor( $index, __METHOD__ );
  82                 return self::isTalk( $index )
  83                         ? $index
  84                         : $index + 1;
  85         }
  86
  87         /**
  88          * Get the subject namespace index for a given namespace
  89          * Special namespaces (NS_MEDIA, NS_SPECIAL) are always the subject.
  90          *
  91          * @param $index Int: Namespace index
  92          * @return int
  93          */
  94         public static function getSubject( $index ) {
  95                 # Handle special namespaces
  96                 if( $index < NS_MAIN ) {
  97                         return $index;
  98                 }
  99
 100                 return self::isTalk( $index )
 101                         ? $index - 1
 102                         : $index;
 103         }
 104
 105         /**
 106          * Get the associated namespace.
 107          * For talk namespaces, returns the subject (non-talk) namespace
 108          * For subject (non-talk) namespaces, returns the talk namespace
 109          *
 110          * @param $index Int: namespace index
 111          * @return int or null if no associated namespace could be found
 112          */
 113         public static function getAssociated( $index ) {
 114                 self::isMethodValidFor( $index, __METHOD__ );
 115
 116                 if( self::isMain( $index ) ) {
 117                         return self::getTalk( $index );
 118                 } elseif( self::isTalk( $index ) ) {
 119                         return self::getSubject( $index );
 120                 } else {
 121                         return null;
 122                 }
 123         }
 124
 125         /**
 126          * Returns whether the specified namespace exists
 127          */
 128         public static function exists( $index ) {
 129                 $nslist = self::getCanonicalNamespaces();
 130                 return isset( $nslist[$index] );
 131         }
 132
 133         /**
 134          * Returns array of all defined namespaces with their canonical
 135          * (English) names.
 136          *
 137          * @return \array
 138          * @since 1.17
 139          */
 140         public static function getCanonicalNamespaces() {
 141                 static $namespaces = null;
 142                 if ( $namespaces === null ) {
 143                         global $wgExtraNamespaces, $wgCanonicalNamespaceNames;
 144                         $namespaces = array( NS_MAIN => '' ) + $wgCanonicalNamespaceNames;
 145                         if ( is_array( $wgExtraNamespaces ) ) {
 146                                 $namespaces += $wgExtraNamespaces;
 147                         }
 148                         wfRunHooks( 'CanonicalNamespaces', array( &$namespaces ) );
 149                 }
 150                 return $namespaces;
 151         }
 152
 153         /**
 154          * Returns the canonical (English) name for a given index
 155          *
 156          * @param $index Int: namespace index
 157          * @return string or false if no canonical definition.
 158          */
 159         public static function getCanonicalName( $index ) {
 160                 $nslist = self::getCanonicalNamespaces();
 161                 if( isset( $nslist[$index] ) ) {
 162                         return $nslist[$index];
 163                 } else {
 164                         return false;
 165                 }
 166         }
 167
 168         /**
 169          * Returns the index for a given canonical name, or NULL
 170          * The input *must* be converted to lower case first
 171          *
 172          * @param $name String: namespace name
 173          * @return int
 174          */
 175         public static function getCanonicalIndex( $name ) {
 176                 static $xNamespaces = false;
 177                 if ( $xNamespaces === false ) {
 178                         $xNamespaces = array();
 179                         foreach ( self::getCanonicalNamespaces() as $i => $text ) {
 180                                 $xNamespaces[strtolower($text)] = $i;
 181                         }
 182                 }
 183                 if ( array_key_exists( $name, $xNamespaces ) ) {
 184                         return $xNamespaces[$name];
 185                 } else {
 186                         return null;
 187                 }
 188         }
 189
 190         /**
 191          * Returns an array of the namespaces (by integer id) that exist on the
 192          * wiki. Used primarily by the api in help documentation.
 193          * @return array
 194          */
 195         public static function getValidNamespaces() {
 196                 static $mValidNamespaces = null;
 197
 198                 if ( is_null( $mValidNamespaces ) ) {
 199                         foreach ( array_keys( self::getCanonicalNamespaces() ) as $ns ) {
 200                                 if ( $ns >= 0 ) {
 201                                         $mValidNamespaces[] = $ns;
 202                                 }
 203                         }
 204                 }
 205
 206                 return $mValidNamespaces;
 207         }
 208
 209         /**
 210          * Can this namespace ever have a talk namespace?
 211          *
 212          * @param $index Int: namespace index
 213          * @return bool
 214          */
 215          public static function canTalk( $index ) {
 216                 return $index >= NS_MAIN;
 217          }
 218
 219         /**
 220          * Does this namespace contain content, for the purposes of calculating
 221          * statistics, etc?
 222          *
 223          * @param $index Int: index to check
 224          * @return bool
 225          */
 226         public static function isContent( $index ) {
 227                 global $wgContentNamespaces;
 228                 return $index == NS_MAIN || in_array( $index, $wgContentNamespaces );
 229         }
 230
 231         /**
 232          * Can pages in a namespace be watched?
 233          *
 234          * @param $index Int
 235          * @return bool
 236          */
 237         public static function isWatchable( $index ) {
 238                 return $index >= NS_MAIN;
 239         }
 240
 241         /**
 242          * Does the namespace allow subpages?
 243          *
 244          * @param $index int Index to check
 245          * @return bool
 246          */
 247         public static function hasSubpages( $index ) {
 248                 global $wgNamespacesWithSubpages;
 249                 return !empty( $wgNamespacesWithSubpages[$index] );
 250         }
 251
 252         /**
 253          * Get a list of all namespace indices which are considered to contain content
 254          * @return array of namespace indices
 255          */
 256         public static function getContentNamespaces() {
 257                 global $wgContentNamespaces;
 258                 if( !is_array( $wgContentNamespaces ) || $wgContentNamespaces === array() ) {
 259                         return NS_MAIN;
 260                 } elseif ( !in_array( NS_MAIN, $wgContentNamespaces ) ) {
 261                         // always force NS_MAIN to be part of array (to match the algorithm used by isContent)
 262                         return array_merge( array( NS_MAIN ), $wgContentNamespaces );
 263                 } else {
 264                         return $wgContentNamespaces;
 265                 }
 266         }
 267         /**
 268          * Is the namespace first-letter capitalized?
 269          *
 270          * @param $index int Index to check
 271          * @return bool
 272          */
 273         public static function isCapitalized( $index ) {
 274                 global $wgCapitalLinks, $wgCapitalLinkOverrides;
 275                 // Turn NS_MEDIA into NS_FILE
 276                 $index = $index === NS_MEDIA ? NS_FILE : $index;
 277
 278                 // Make sure to get the subject of our namespace
 279                 $index = self::getSubject( $index );
 280
 281                 // Some namespaces are special and should always be upper case
 282                 if ( in_array( $index, self::$alwaysCapitalizedNamespaces ) ) {
 283                         return true;
 284                 }
 285                 if ( isset( $wgCapitalLinkOverrides[ $index ] ) ) {
 286                         // $wgCapitalLinkOverrides is explicitly set
 287                         return $wgCapitalLinkOverrides[ $index ];
 288                 }
 289                 // Default to the global setting
 290                 return $wgCapitalLinks;
 291         }
 292
 293         /**
 294          * Does the namespace (potentially) have different aliases for different
 295          * genders. Not all languages make a distinction here.
 296          *
 297          * @since 1.18
 298          * @param $index int Index to check
 299          * @return bool
 300          */
 301         public static function hasGenderDistinction( $index ) {
 302                 return $index == NS_USER || $index == NS_USER_TALK;
 303         }
 304
 305 }