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          * @param bool $rebuild rebuild namespace list (default = false). Used for testing.
 213          *
 214          * @return array
 215          * @since 1.17
 216          */
 217         public static function getCanonicalNamespaces( $rebuild = false ) {
 218                 static $namespaces = null;
 219                 if ( $namespaces === null || $rebuild ) {
 220                         global $wgExtraNamespaces, $wgCanonicalNamespaceNames;
 221                         $namespaces = array( NS_MAIN => '' ) + $wgCanonicalNamespaceNames;
 222                         if ( is_array( $wgExtraNamespaces ) ) {
 223                                 $namespaces += $wgExtraNamespaces;
 224                         }
 225                         wfRunHooks( 'CanonicalNamespaces', array( &$namespaces ) );
 226                 }
 227                 return $namespaces;
 228         }
 229
 230         /**
 231          * Returns the canonical (English) name for a given index
 232          *
 233          * @param $index Int: namespace index
 234          * @return string or false if no canonical definition.
 235          */
 236         public static function getCanonicalName( $index ) {
 237                 $nslist = self::getCanonicalNamespaces();
 238                 if ( isset( $nslist[$index] ) ) {
 239                         return $nslist[$index];
 240                 } else {
 241                         return false;
 242                 }
 243         }
 244
 245         /**
 246          * Returns the index for a given canonical name, or NULL
 247          * The input *must* be converted to lower case first
 248          *
 249          * @param $name String: namespace name
 250          * @return int
 251          */
 252         public static function getCanonicalIndex( $name ) {
 253                 static $xNamespaces = false;
 254                 if ( $xNamespaces === false ) {
 255                         $xNamespaces = array();
 256                         foreach ( self::getCanonicalNamespaces() as $i => $text ) {
 257                                 $xNamespaces[strtolower( $text )] = $i;
 258                         }
 259                 }
 260                 if ( array_key_exists( $name, $xNamespaces ) ) {
 261                         return $xNamespaces[$name];
 262                 } else {
 263                         return null;
 264                 }
 265         }
 266
 267         /**
 268          * Returns an array of the namespaces (by integer id) that exist on the
 269          * wiki. Used primarily by the api in help documentation.
 270          * @return array
 271          */
 272         public static function getValidNamespaces() {
 273                 static $mValidNamespaces = null;
 274
 275                 if ( is_null( $mValidNamespaces ) ) {
 276                         foreach ( array_keys( self::getCanonicalNamespaces() ) as $ns ) {
 277                                 if ( $ns >= 0 ) {
 278                                         $mValidNamespaces[] = $ns;
 279                                 }
 280                         }
 281                 }
 282
 283                 return $mValidNamespaces;
 284         }
 285
 286         /**
 287          * Can this namespace ever have a talk namespace?
 288          *
 289          * @param $index Int: namespace index
 290          * @return bool
 291          */
 292          public static function canTalk( $index ) {
 293                 return $index >= NS_MAIN;
 294          }
 295
 296         /**
 297          * Does this namespace contain content, for the purposes of calculating
 298          * statistics, etc?
 299          *
 300          * @param $index Int: index to check
 301          * @return bool
 302          */
 303         public static function isContent( $index ) {
 304                 global $wgContentNamespaces;
 305                 return $index == NS_MAIN || in_array( $index, $wgContentNamespaces );
 306         }
 307
 308         /**
 309          * Can pages in a namespace be watched?
 310          *
 311          * @param $index Int
 312          * @return bool
 313          */
 314         public static function isWatchable( $index ) {
 315                 return $index >= NS_MAIN;
 316         }
 317
 318         /**
 319          * Does the namespace allow subpages?
 320          *
 321          * @param $index int Index to check
 322          * @return bool
 323          */
 324         public static function hasSubpages( $index ) {
 325                 global $wgNamespacesWithSubpages;
 326                 return !empty( $wgNamespacesWithSubpages[$index] );
 327         }
 328
 329         /**
 330          * Get a list of all namespace indices which are considered to contain content
 331          * @return array of namespace indices
 332          */
 333         public static function getContentNamespaces() {
 334                 global $wgContentNamespaces;
 335                 if ( !is_array( $wgContentNamespaces ) || $wgContentNamespaces === array() ) {
 336                         return NS_MAIN;
 337                 } elseif ( !in_array( NS_MAIN, $wgContentNamespaces ) ) {
 338                         // always force NS_MAIN to be part of array (to match the algorithm used by isContent)
 339                         return array_merge( array( NS_MAIN ), $wgContentNamespaces );
 340                 } else {
 341                         return $wgContentNamespaces;
 342                 }
 343         }
 344         /**
 345          * Is the namespace first-letter capitalized?
 346          *
 347          * @param $index int Index to check
 348          * @return bool
 349          */
 350         public static function isCapitalized( $index ) {
 351                 global $wgCapitalLinks, $wgCapitalLinkOverrides;
 352                 // Turn NS_MEDIA into NS_FILE
 353                 $index = $index === NS_MEDIA ? NS_FILE : $index;
 354
 355                 // Make sure to get the subject of our namespace
 356                 $index = self::getSubject( $index );
 357
 358                 // Some namespaces are special and should always be upper case
 359                 if ( in_array( $index, self::$alwaysCapitalizedNamespaces ) ) {
 360                         return true;
 361                 }
 362                 if ( isset( $wgCapitalLinkOverrides[ $index ] ) ) {
 363                         // $wgCapitalLinkOverrides is explicitly set
 364                         return $wgCapitalLinkOverrides[ $index ];
 365                 }
 366                 // Default to the global setting
 367                 return $wgCapitalLinks;
 368         }
 369
 370         /**
 371          * Does the namespace (potentially) have different aliases for different
 372          * genders. Not all languages make a distinction here.
 373          *
 374          * @since 1.18
 375          * @param $index int Index to check
 376          * @return bool
 377          */
 378         public static function hasGenderDistinction( $index ) {
 379                 return $index == NS_USER || $index == NS_USER_TALK;
 380         }
 381
 382         /**
 383          * It is not possible to use pages from this namespace as template?
 384          *
 385          * @since 1.20
 386          * @param $index int Index to check
 387          * @return bool
 388          */
 389         public static function isNonincludable( $index ) {
 390                 global $wgNonincludableNamespaces;
 391                 return $wgNonincludableNamespaces && in_array( $index, $wgNonincludableNamespaces );
 392         }
 393
 394 }