includes/MWNamespace.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 int $index
  49          * @param string $method
  50          *
  51          * @throws MWException
  52          * @return bool
  53          */
  54         private static function isMethodValidFor( $index, $method ) {
  55                 if ( $index < NS_MAIN ) {
  56                         throw new MWException( "$method does not make any sense for given namespace $index" );
  57                 }
  58                 return true;
  59         }
  60
  61         /**
  62          * Can pages in the given namespace be moved?
  63          *
  64          * @param int $index Namespace index
  65          * @return bool
  66          */
  67         public static function isMovable( $index ) {
  68                 global $wgAllowImageMoving;
  69
  70                 $result = !( $index < NS_MAIN || ( $index == NS_FILE && !$wgAllowImageMoving ) );
  71
  72                 /**
  73                  * @since 1.20
  74                  */
  75                 Hooks::run( 'NamespaceIsMovable', array( $index, &$result ) );
  76
  77                 return $result;
  78         }
  79
  80         /**
  81          * Is the given namespace is a subject (non-talk) namespace?
  82          *
  83          * @param int $index Namespace index
  84          * @return bool
  85          * @since 1.19
  86          */
  87         public static function isSubject( $index ) {
  88                 return !self::isTalk( $index );
  89         }
  90
  91         /**
  92          * Is the given namespace a talk namespace?
  93          *
  94          * @param int $index Namespace index
  95          * @return bool
  96          */
  97         public static function isTalk( $index ) {
  98                 return $index > NS_MAIN
  99                         && $index % 2;
 100         }
 101
 102         /**
 103          * Get the talk namespace index for a given namespace
 104          *
 105          * @param int $index Namespace index
 106          * @return int
 107          */
 108         public static function getTalk( $index ) {
 109                 self::isMethodValidFor( $index, __METHOD__ );
 110                 return self::isTalk( $index )
 111                         ? $index
 112                         : $index + 1;
 113         }
 114
 115         /**
 116          * Get the subject namespace index for a given namespace
 117          * Special namespaces (NS_MEDIA, NS_SPECIAL) are always the subject.
 118          *
 119          * @param int $index Namespace index
 120          * @return int
 121          */
 122         public static function getSubject( $index ) {
 123                 # Handle special namespaces
 124                 if ( $index < NS_MAIN ) {
 125                         return $index;
 126                 }
 127
 128                 return self::isTalk( $index )
 129                         ? $index - 1
 130                         : $index;
 131         }
 132
 133         /**
 134          * Get the associated namespace.
 135          * For talk namespaces, returns the subject (non-talk) namespace
 136          * For subject (non-talk) namespaces, returns the talk namespace
 137          *
 138          * @param int $index Namespace index
 139          * @return int|null If no associated namespace could be found
 140          */
 141         public static function getAssociated( $index ) {
 142                 self::isMethodValidFor( $index, __METHOD__ );
 143
 144                 if ( self::isSubject( $index ) ) {
 145                         return self::getTalk( $index );
 146                 } elseif ( self::isTalk( $index ) ) {
 147                         return self::getSubject( $index );
 148                 } else {
 149                         return null;
 150                 }
 151         }
 152
 153         /**
 154          * Returns whether the specified namespace exists
 155          *
 156          * @param int $index
 157          *
 158          * @return bool
 159          * @since 1.19
 160          */
 161         public static function exists( $index ) {
 162                 $nslist = self::getCanonicalNamespaces();
 163                 return isset( $nslist[$index] );
 164         }
 165
 166         /**
 167          * Returns whether the specified namespaces are the same namespace
 168          *
 169          * @note It's possible that in the future we may start using something
 170          * other than just namespace indexes. Under that circumstance making use
 171          * of this function rather than directly doing comparison will make
 172          * sure that code will not potentially break.
 173          *
 174          * @param int $ns1 The first namespace index
 175          * @param int $ns2 The second namespace index
 176          *
 177          * @return bool
 178          * @since 1.19
 179          */
 180         public static function equals( $ns1, $ns2 ) {
 181                 return $ns1 == $ns2;
 182         }
 183
 184         /**
 185          * Returns whether the specified namespaces share the same subject.
 186          * eg: NS_USER and NS_USER wil return true, as well
 187          *     NS_USER and NS_USER_TALK will return true.
 188          *
 189          * @param int $ns1 The first namespace index
 190          * @param int $ns2 The second namespace index
 191          *
 192          * @return bool
 193          * @since 1.19
 194          */
 195         public static function subjectEquals( $ns1, $ns2 ) {
 196                 return self::getSubject( $ns1 ) == self::getSubject( $ns2 );
 197         }
 198
 199         /**
 200          * Returns array of all defined namespaces with their canonical
 201          * (English) names.
 202          *
 203          * @param bool $rebuild Rebuild namespace list (default = false). Used for testing.
 204          *
 205          * @return array
 206          * @since 1.17
 207          */
 208         public static function getCanonicalNamespaces( $rebuild = false ) {
 209                 static $namespaces = null;
 210                 if ( $namespaces === null || $rebuild ) {
 211                         global $wgExtraNamespaces, $wgCanonicalNamespaceNames;
 212                         $namespaces = array( NS_MAIN => '' ) + $wgCanonicalNamespaceNames;
 213                         // Add extension namespaces
 214                         $namespaces += ExtensionRegistry::getInstance()->getAttribute( 'ExtensionNamespaces' );
 215                         if ( is_array( $wgExtraNamespaces ) ) {
 216                                 $namespaces += $wgExtraNamespaces;
 217                         }
 218                         Hooks::run( 'CanonicalNamespaces', array( &$namespaces ) );
 219                 }
 220                 return $namespaces;
 221         }
 222
 223         /**
 224          * Returns the canonical (English) name for a given index
 225          *
 226          * @param int $index Namespace index
 227          * @return string|bool If no canonical definition.
 228          */
 229         public static function getCanonicalName( $index ) {
 230                 $nslist = self::getCanonicalNamespaces();
 231                 if ( isset( $nslist[$index] ) ) {
 232                         return $nslist[$index];
 233                 } else {
 234                         return false;
 235                 }
 236         }
 237
 238         /**
 239          * Returns the index for a given canonical name, or NULL
 240          * The input *must* be converted to lower case first
 241          *
 242          * @param string $name Namespace name
 243          * @return int
 244          */
 245         public static function getCanonicalIndex( $name ) {
 246                 static $xNamespaces = false;
 247                 if ( $xNamespaces === false ) {
 248                         $xNamespaces = array();
 249                         foreach ( self::getCanonicalNamespaces() as $i => $text ) {
 250                                 $xNamespaces[strtolower( $text )] = $i;
 251                         }
 252                 }
 253                 if ( array_key_exists( $name, $xNamespaces ) ) {
 254                         return $xNamespaces[$name];
 255                 } else {
 256                         return null;
 257                 }
 258         }
 259
 260         /**
 261          * Returns an array of the namespaces (by integer id) that exist on the
 262          * wiki. Used primarily by the api in help documentation.
 263          * @return array
 264          */
 265         public static function getValidNamespaces() {
 266                 static $mValidNamespaces = null;
 267
 268                 if ( is_null( $mValidNamespaces ) ) {
 269                         foreach ( array_keys( self::getCanonicalNamespaces() ) as $ns ) {
 270                                 if ( $ns >= 0 ) {
 271                                         $mValidNamespaces[] = $ns;
 272                                 }
 273                         }
 274                         // T109137: sort numerically
 275                         sort( $mValidNamespaces, SORT_NUMERIC );
 276                 }
 277
 278                 return $mValidNamespaces;
 279         }
 280
 281         /**
 282          * Can this namespace ever have a talk namespace?
 283          *
 284          * @param int $index Namespace index
 285          * @return bool
 286          */
 287         public static function canTalk( $index ) {
 288                 return $index >= NS_MAIN;
 289         }
 290
 291         /**
 292          * Does this namespace contain content, for the purposes of calculating
 293          * statistics, etc?
 294          *
 295          * @param int $index Index to check
 296          * @return bool
 297          */
 298         public static function isContent( $index ) {
 299                 global $wgContentNamespaces;
 300                 return $index == NS_MAIN || in_array( $index, $wgContentNamespaces );
 301         }
 302
 303         /**
 304          * Might pages in this namespace require the use of the Signature button on
 305          * the edit toolbar?
 306          *
 307          * @param int $index Index to check
 308          * @return bool
 309          */
 310         public static function wantSignatures( $index ) {
 311                 global $wgExtraSignatureNamespaces;
 312                 return self::isTalk( $index ) || in_array( $index, $wgExtraSignatureNamespaces );
 313         }
 314
 315         /**
 316          * Can pages in a namespace be watched?
 317          *
 318          * @param int $index
 319          * @return bool
 320          */
 321         public static function isWatchable( $index ) {
 322                 return $index >= NS_MAIN;
 323         }
 324
 325         /**
 326          * Does the namespace allow subpages?
 327          *
 328          * @param int $index Index to check
 329          * @return bool
 330          */
 331         public static function hasSubpages( $index ) {
 332                 global $wgNamespacesWithSubpages;
 333                 return !empty( $wgNamespacesWithSubpages[$index] );
 334         }
 335
 336         /**
 337          * Get a list of all namespace indices which are considered to contain content
 338          * @return array Array of namespace indices
 339          */
 340         public static function getContentNamespaces() {
 341                 global $wgContentNamespaces;
 342                 if ( !is_array( $wgContentNamespaces ) || $wgContentNamespaces === array() ) {
 343                         return array( NS_MAIN );
 344                 } elseif ( !in_array( NS_MAIN, $wgContentNamespaces ) ) {
 345                         // always force NS_MAIN to be part of array (to match the algorithm used by isContent)
 346                         return array_merge( array( NS_MAIN ), $wgContentNamespaces );
 347                 } else {
 348                         return $wgContentNamespaces;
 349                 }
 350         }
 351
 352         /**
 353          * List all namespace indices which are considered subject, aka not a talk
 354          * or special namespace. See also MWNamespace::isSubject
 355          *
 356          * @return array Array of namespace indices
 357          */
 358         public static function getSubjectNamespaces() {
 359                 return array_filter(
 360                         MWNamespace::getValidNamespaces(),
 361                         'MWNamespace::isSubject'
 362                 );
 363         }
 364
 365         /**
 366          * List all namespace indices which are considered talks, aka not a subject
 367          * or special namespace. See also MWNamespace::isTalk
 368          *
 369          * @return array Array of namespace indices
 370          */
 371         public static function getTalkNamespaces() {
 372                 return array_filter(
 373                         MWNamespace::getValidNamespaces(),
 374                         'MWNamespace::isTalk'
 375                 );
 376         }
 377
 378         /**
 379          * Is the namespace first-letter capitalized?
 380          *
 381          * @param int $index Index to check
 382          * @return bool
 383          */
 384         public static function isCapitalized( $index ) {
 385                 global $wgCapitalLinks, $wgCapitalLinkOverrides;
 386                 // Turn NS_MEDIA into NS_FILE
 387                 $index = $index === NS_MEDIA ? NS_FILE : $index;
 388
 389                 // Make sure to get the subject of our namespace
 390                 $index = self::getSubject( $index );
 391
 392                 // Some namespaces are special and should always be upper case
 393                 if ( in_array( $index, self::$alwaysCapitalizedNamespaces ) ) {
 394                         return true;
 395                 }
 396                 if ( isset( $wgCapitalLinkOverrides[$index] ) ) {
 397                         // $wgCapitalLinkOverrides is explicitly set
 398                         return $wgCapitalLinkOverrides[$index];
 399                 }
 400                 // Default to the global setting
 401                 return $wgCapitalLinks;
 402         }
 403
 404         /**
 405          * Does the namespace (potentially) have different aliases for different
 406          * genders. Not all languages make a distinction here.
 407          *
 408          * @since 1.18
 409          * @param int $index Index to check
 410          * @return bool
 411          */
 412         public static function hasGenderDistinction( $index ) {
 413                 return $index == NS_USER || $index == NS_USER_TALK;
 414         }
 415
 416         /**
 417          * It is not possible to use pages from this namespace as template?
 418          *
 419          * @since 1.20
 420          * @param int $index Index to check
 421          * @return bool
 422          */
 423         public static function isNonincludable( $index ) {
 424                 global $wgNonincludableNamespaces;
 425                 return $wgNonincludableNamespaces && in_array( $index, $wgNonincludableNamespaces );
 426         }
 427
 428         /**
 429          * Get the default content model for a namespace
 430          * This does not mean that all pages in that namespace have the model
 431          *
 432          * @since 1.21
 433          * @param int $index Index to check
 434          * @return null|string Default model name for the given namespace, if set
 435          */
 436         public static function getNamespaceContentModel( $index ) {
 437                 global $wgNamespaceContentModels;
 438                 return isset( $wgNamespaceContentModels[$index] )
 439                         ? $wgNamespaceContentModels[$index]
 440                         : null;
 441         }
 442
 443         /**
 444          * Determine which restriction levels it makes sense to use in a namespace,
 445          * optionally filtered by a user's rights.
 446          *
 447          * @since 1.23
 448          * @param int $index Index to check
 449          * @param User $user User to check
 450          * @return array
 451          */
 452         public static function getRestrictionLevels( $index, User $user = null ) {
 453                 global $wgNamespaceProtection, $wgRestrictionLevels;
 454
 455                 if ( !isset( $wgNamespaceProtection[$index] ) ) {
 456                         // All levels are valid if there's no namespace restriction.
 457                         // But still filter by user, if necessary
 458                         $levels = $wgRestrictionLevels;
 459                         if ( $user ) {
 460                                 $levels = array_values( array_filter( $levels, function ( $level ) use ( $user ) {
 461                                         $right = $level;
 462                                         if ( $right == 'sysop' ) {
 463                                                 $right = 'editprotected'; // BC
 464                                         }
 465                                         if ( $right == 'autoconfirmed' ) {
 466                                                 $right = 'editsemiprotected'; // BC
 467                                         }
 468                                         return ( $right == '' || $user->isAllowed( $right ) );
 469                                 } ) );
 470                         }
 471                         return $levels;
 472                 }
 473
 474                 // First, get the list of groups that can edit this namespace.
 475                 $namespaceGroups = array();
 476                 $combine = 'array_merge';
 477                 foreach ( (array)$wgNamespaceProtection[$index] as $right ) {
 478                         if ( $right == 'sysop' ) {
 479                                 $right = 'editprotected'; // BC
 480                         }
 481                         if ( $right == 'autoconfirmed' ) {
 482                                 $right = 'editsemiprotected'; // BC
 483                         }
 484                         if ( $right != '' ) {
 485                                 $namespaceGroups = call_user_func( $combine, $namespaceGroups,
 486                                         User::getGroupsWithPermission( $right ) );
 487                                 $combine = 'array_intersect';
 488                         }
 489                 }
 490
 491                 // Now, keep only those restriction levels where there is at least one
 492                 // group that can edit the namespace but would be blocked by the
 493                 // restriction.
 494                 $usableLevels = array( '' );
 495                 foreach ( $wgRestrictionLevels as $level ) {
 496                         $right = $level;
 497                         if ( $right == 'sysop' ) {
 498                                 $right = 'editprotected'; // BC
 499                         }
 500                         if ( $right == 'autoconfirmed' ) {
 501                                 $right = 'editsemiprotected'; // BC
 502                         }
 503                         if ( $right != '' && ( !$user || $user->isAllowed( $right ) ) &&
 504                                 array_diff( $namespaceGroups, User::getGroupsWithPermission( $right ) )
 505                         ) {
 506                                 $usableLevels[] = $level;
 507                         }
 508                 }
 509
 510                 return $usableLevels;
 511         }
 512 }