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