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