includes/Namespace.php

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