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