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