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