includes/Namespace.php

   1 <?php
   2 /**
   3  * Provide things related to namespaces.
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License along
  16  * with this program; if not, write to the Free Software Foundation, Inc.,
  17  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  18  * http://www.gnu.org/copyleft/gpl.html
  19  *
  20  * @file
  21  */
  22
  23 /**
  24  * This is a utility class with only static functions
  25  * for dealing with namespaces that encodes all the
  26  * "magic" behaviors of them based on index.  The textual
  27  * names of the namespaces are handled by Language.php.
  28  *
  29  * These are synonyms for the names given in the language file
  30  * Users and translators should not change them
  31  *
  32  */
  33 class MWNamespace {
  34
  35         /**
  36          * These namespaces should always be first-letter capitalized, now and
  37          * forevermore. Historically, they could've probably been lowercased too,
  38          * but some things are just too ingrained now. :)
  39          */
  40         private static $alwaysCapitalizedNamespaces = array( NS_SPECIAL, NS_USER, NS_MEDIAWIKI );
  41
  42         /**
  43          * Throw an exception when trying to get the subject or talk page
  44          * for a given namespace where it does not make sense.
  45          * Special namespaces are defined in includes/Defines.php and have
  46          * a value below 0 (ex: NS_SPECIAL = -1 , NS_MEDIA = -2)
  47          *
  48          * @param $index
  49          * @param $method
  50          *
  51          * @return bool
  52          */
  53         private static function isMethodValidFor( $index, $method ) {
  54                 if ( $index < NS_MAIN ) {
  55                         throw new MWException( "$method does not make any sense for given namespace $index" );
  56                 }
  57                 return true;
  58         }
  59
  60         /**
  61          * Can pages in the given namespace be moved?
  62          *
  63          * @param $index Int: namespace index
  64          * @return bool
  65          */
  66         public static function isMovable( $index ) {
  67                 global $wgAllowImageMoving;
  68
  69                 $result = !( $index < NS_MAIN || ( $index == NS_FILE && !$wgAllowImageMoving )  || $index == NS_CATEGORY );
  70
  71                 /**
  72                  * @since 1.20
  73                  */
  74                 wfRunHooks( 'NamespaceIsMovable', array( $index, &$result ) );
  75
  76                 return $result;
  77         }
  78
  79         /**
  80          * Is the given namespace is a subject (non-talk) namespace?
  81          *
  82          * @param $index Int: namespace index
  83          * @return bool
  84          * @since 1.19
  85          */
  86         public static function isSubject( $index ) {
  87                 return !self::isTalk( $index );
  88         }
  89
  90         /**
  91          * @see self::isSubject
  92          * @deprecated Please use the more consistently named isSubject (since 1.19)
  93          * @return bool
  94          */
  95         public static function isMain( $index ) {
  96                 wfDeprecated( __METHOD__, '1.19' );
  97                 return self::isSubject( $index );
  98         }
  99
 100         /**
 101          * Is the given namespace a talk namespace?
 102          *
 103          * @param $index Int: namespace index
 104          * @return bool
 105          */
 106         public static function isTalk( $index ) {
 107                 return $index > NS_MAIN
 108                         && $index % 2;
 109         }
 110
 111         /**
 112          * Get the talk namespace index for a given namespace
 113          *
 114          * @param $index Int: namespace index
 115          * @return int
 116          */
 117         public static function getTalk( $index ) {
 118                 self::isMethodValidFor( $index, __METHOD__ );
 119                 return self::isTalk( $index )
 120                         ? $index
 121                         : $index + 1;
 122         }
 123
 124         /**
 125          * Get the subject namespace index for a given namespace
 126          * Special namespaces (NS_MEDIA, NS_SPECIAL) are always the subject.
 127          *
 128          * @param $index Int: Namespace index
 129          * @return int
 130          */
 131         public static function getSubject( $index ) {
 132                 # Handle special namespaces
 133                 if ( $index < NS_MAIN ) {
 134                         return $index;
 135                 }
 136
 137                 return self::isTalk( $index )
 138                         ? $index - 1
 139                         : $index;
 140         }
 141
 142         /**
 143          * Get the associated namespace.
 144          * For talk namespaces, returns the subject (non-talk) namespace
 145          * For subject (non-talk) namespaces, returns the talk namespace
 146          *
 147          * @param $index Int: namespace index
 148          * @return int or null if no associated namespace could be found
 149          */
 150         public static function getAssociated( $index ) {
 151                 self::isMethodValidFor( $index, __METHOD__ );
 152
 153                 if ( self::isSubject( $index ) ) {
 154                         return self::getTalk( $index );
 155                 } elseif ( self::isTalk( $index ) ) {
 156                         return self::getSubject( $index );
 157                 } else {
 158                         return null;
 159                 }
 160         }
 161
 162         /**
 163          * Returns whether the specified namespace exists
 164          *
 165          * @param $index
 166          *
 167          * @return bool
 168          * @since 1.19
 169          */
 170         public static function exists( $index ) {
 171                 $nslist = self::getCanonicalNamespaces();
 172                 return isset( $nslist[$index] );
 173         }
 174
 175         /**
 176          * Returns whether the specified namespaces are the same namespace
 177          *
 178          * @note It's possible that in the future we may start using something
 179          * other than just namespace indexes. Under that circumstance making use
 180          * of this function rather than directly doing comparison will make
 181          * sure that code will not potentially break.
 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 equals( $ns1, $ns2 ) {
 190                 return $ns1 == $ns2;
 191         }
 192
 193         /**
 194          * Returns whether the specified namespaces share the same subject.
 195          * eg: NS_USER and NS_USER wil return true, as well
 196          *     NS_USER and NS_USER_TALK will return true.
 197          *
 198          * @param $ns1 int The first namespace index
 199          * @param $ns2 int The second namespae index
 200          *
 201          * @return bool
 202          * @since 1.19
 203          */
 204         public static function subjectEquals( $ns1, $ns2 ) {
 205                 return self::getSubject( $ns1 ) == self::getSubject( $ns2 );
 206         }
 207
 208         /**
 209          * Returns array of all defined namespaces with their canonical
 210          * (English) names.
 211          *
 212          * @return array
 213          * @since 1.17
 214          */
 215         public static function getCanonicalNamespaces() {
 216                 static $namespaces = null;
 217                 if ( $namespaces === null ) {
 218                         global $wgExtraNamespaces, $wgCanonicalNamespaceNames;
 219                         $namespaces = array( NS_MAIN => '' ) + $wgCanonicalNamespaceNames;
 220                         if ( is_array( $wgExtraNamespaces ) ) {
 221                                 $namespaces += $wgExtraNamespaces;
 222                         }
 223                         wfRunHooks( 'CanonicalNamespaces', array( &$namespaces ) );
 224                 }
 225                 return $namespaces;
 226         }
 227
 228         /**
 229          * Returns the canonical (English) name for a given index
 230          *
 231          * @param $index Int: namespace index
 232          * @return string or false if no canonical definition.
 233          */
 234         public static function getCanonicalName( $index ) {
 235                 $nslist = self::getCanonicalNamespaces();
 236                 if ( isset( $nslist[$index] ) ) {
 237                         return $nslist[$index];
 238                 } else {
 239                         return false;
 240                 }
 241         }
 242
 243         /**
 244          * Returns the index for a given canonical name, or NULL
 245          * The input *must* be converted to lower case first
 246          *
 247          * @param $name String: namespace name
 248          * @return int
 249          */
 250         public static function getCanonicalIndex( $name ) {
 251                 static $xNamespaces = false;
 252                 if ( $xNamespaces === false ) {
 253                         $xNamespaces = array();
 254                         foreach ( self::getCanonicalNamespaces() as $i => $text ) {
 255                                 $xNamespaces[strtolower( $text )] = $i;
 256                         }
 257                 }
 258                 if ( array_key_exists( $name, $xNamespaces ) ) {
 259                         return $xNamespaces[$name];
 260                 } else {
 261                         return null;
 262                 }
 263         }
 264
 265         /**
 266          * Returns an array of the namespaces (by integer id) that exist on the
 267          * wiki. Used primarily by the api in help documentation.
 268          * @return array
 269          */
 270         public static function getValidNamespaces() {
 271                 static $mValidNamespaces = null;
 272
 273                 if ( is_null( $mValidNamespaces ) ) {
 274                         foreach ( array_keys( self::getCanonicalNamespaces() ) as $ns ) {
 275                                 if ( $ns >= 0 ) {
 276                                         $mValidNamespaces[] = $ns;
 277                                 }
 278                         }
 279                 }
 280
 281                 return $mValidNamespaces;
 282         }
 283
 284         /**
 285          * Can this namespace ever have a talk namespace?
 286          *
 287          * @param $index Int: namespace index
 288          * @return bool
 289          */
 290          public static function canTalk( $index ) {
 291                 return $index >= NS_MAIN;
 292          }
 293
 294         /**
 295          * Does this namespace contain content, for the purposes of calculating
 296          * statistics, etc?
 297          *
 298          * @param $index Int: index to check
 299          * @return bool
 300          */
 301         public static function isContent( $index ) {
 302                 global $wgContentNamespaces;
 303                 return $index == NS_MAIN || in_array( $index, $wgContentNamespaces );
 304         }
 305
 306         /**
 307          * Can pages in a namespace be watched?
 308          *
 309          * @param $index Int
 310          * @return bool
 311          */
 312         public static function isWatchable( $index ) {
 313                 return $index >= NS_MAIN;
 314         }
 315
 316         /**
 317          * Does the namespace allow subpages?
 318          *
 319          * @param $index int Index to check
 320          * @return bool
 321          */
 322         public static function hasSubpages( $index ) {
 323                 global $wgNamespacesWithSubpages;
 324                 return !empty( $wgNamespacesWithSubpages[$index] );
 325         }
 326
 327         /**
 328          * Get a list of all namespace indices which are considered to contain content
 329          * @return array of namespace indices
 330          */
 331         public static function getContentNamespaces() {
 332                 global $wgContentNamespaces;
 333                 if ( !is_array( $wgContentNamespaces ) || $wgContentNamespaces === array() ) {
 334                         return NS_MAIN;
 335                 } elseif ( !in_array( NS_MAIN, $wgContentNamespaces ) ) {
 336                         // always force NS_MAIN to be part of array (to match the algorithm used by isContent)
 337                         return array_merge( array( NS_MAIN ), $wgContentNamespaces );
 338                 } else {
 339                         return $wgContentNamespaces;
 340                 }
 341         }
 342         /**
 343          * Is the namespace first-letter capitalized?
 344          *
 345          * @param $index int Index to check
 346          * @return bool
 347          */
 348         public static function isCapitalized( $index ) {
 349                 global $wgCapitalLinks, $wgCapitalLinkOverrides;
 350                 // Turn NS_MEDIA into NS_FILE
 351                 $index = $index === NS_MEDIA ? NS_FILE : $index;
 352
 353                 // Make sure to get the subject of our namespace
 354                 $index = self::getSubject( $index );
 355
 356                 // Some namespaces are special and should always be upper case
 357                 if ( in_array( $index, self::$alwaysCapitalizedNamespaces ) ) {
 358                         return true;
 359                 }
 360                 if ( isset( $wgCapitalLinkOverrides[ $index ] ) ) {
 361                         // $wgCapitalLinkOverrides is explicitly set
 362                         return $wgCapitalLinkOverrides[ $index ];
 363                 }
 364                 // Default to the global setting
 365                 return $wgCapitalLinks;
 366         }
 367
 368         /**
 369          * Does the namespace (potentially) have different aliases for different
 370          * genders. Not all languages make a distinction here.
 371          *
 372          * @since 1.18
 373          * @param $index int Index to check
 374          * @return bool
 375          */
 376         public static function hasGenderDistinction( $index ) {
 377                 return $index == NS_USER || $index == NS_USER_TALK;
 378         }
 379
 380         /**
 381          * It is not possible to use pages from this namespace as template?
 382          *
 383          * @since 1.20
 384          * @param $index int Index to check
 385          * @return bool
 386          */
 387         public static function isNonincludable( $index ) {
 388                 global $wgNonincludableNamespaces;
 389                 return $wgNonincludableNamespaces && in_array( $index, $wgNonincludableNamespaces );
 390         }
 391
 392 }