includes/title/MediaWikiTitleCodec.php

   1 <?php
   2 /**
   3  * A codec for MediaWiki page titles.
   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  * @author Daniel Kinzler
  22  */
  23 use MediaWiki\Interwiki\InterwikiLookup;
  24 use MediaWiki\MediaWikiServices;
  25 use MediaWiki\Linker\LinkTarget;
  26
  27 /**
  28  * A codec for MediaWiki page titles.
  29  *
  30  * @note Normalization and validation is applied while parsing, not when formatting.
  31  * It's possible to construct a TitleValue with an invalid title, and use MediaWikiTitleCodec
  32  * to generate an (invalid) title string from it. TitleValues should be constructed only
  33  * via parseTitle() or from a (semi)trusted source, such as the database.
  34  *
  35  * @see https://www.mediawiki.org/wiki/Requests_for_comment/TitleValue
  36  * @since 1.23
  37  */
  38 class MediaWikiTitleCodec implements TitleFormatter, TitleParser {
  39         /**
  40          * @var Language
  41          */
  42         protected $language;
  43
  44         /**
  45          * @var GenderCache
  46          */
  47         protected $genderCache;
  48
  49         /**
  50          * @var string[]
  51          */
  52         protected $localInterwikis;
  53
  54         /**
  55          * @var InterwikiLookup
  56          */
  57         protected $interwikiLookup;
  58
  59         /**
  60          * @var NamespaceInfo
  61          */
  62         protected $nsInfo;
  63
  64         /**
  65          * @param Language $language The language object to use for localizing namespace names,
  66          *   capitalization, etc.
  67          * @param GenderCache $genderCache The gender cache for generating gendered namespace names
  68          * @param string[]|string $localInterwikis
  69          * @param InterwikiLookup|null $interwikiLookup
  70          * @param NamespaceInfo|null $nsInfo
  71          */
  72         public function __construct( Language $language, GenderCache $genderCache,
  73                 $localInterwikis = [], InterwikiLookup $interwikiLookup = null,
  74                 NamespaceInfo $nsInfo = null
  75         ) {
  76                 if ( !$interwikiLookup ) {
  77                         wfDeprecated( __METHOD__ . ' with no InterwikiLookup argument', '1.34' );
  78                         $interwikiLookup = MediaWikiServices::getInstance()->getInterwikiLookup();
  79                 }
  80                 if ( !$nsInfo ) {
  81                         wfDeprecated( __METHOD__ . ' with no NamespaceInfo argument', '1.34' );
  82                         $nsInfo = MediaWikiServices::getInstance()->getNamespaceInfo();
  83                 }
  84                 $this->language = $language;
  85                 $this->genderCache = $genderCache;
  86                 $this->localInterwikis = (array)$localInterwikis;
  87                 $this->interwikiLookup = $interwikiLookup;
  88                 $this->nsInfo = $nsInfo;
  89         }
  90
  91         /**
  92          * @see TitleFormatter::getNamespaceName()
  93          *
  94          * @param int $namespace
  95          * @param string $text
  96          *
  97          * @throws InvalidArgumentException If the namespace is invalid
  98          * @return string Namespace name with underscores (not spaces)
  99          */
 100         public function getNamespaceName( $namespace, $text ) {
 101                 if ( $this->language->needsGenderDistinction() &&
 102                         $this->nsInfo->hasGenderDistinction( $namespace )
 103                 ) {
 104                         // NOTE: we are assuming here that the title text is a user name!
 105                         $gender = $this->genderCache->getGenderOf( $text, __METHOD__ );
 106                         $name = $this->language->getGenderNsText( $namespace, $gender );
 107                 } else {
 108                         $name = $this->language->getNsText( $namespace );
 109                 }
 110
 111                 if ( $name === false ) {
 112                         throw new InvalidArgumentException( 'Unknown namespace ID: ' . $namespace );
 113                 }
 114
 115                 return $name;
 116         }
 117
 118         /**
 119          * @see TitleFormatter::formatTitle()
 120          *
 121          * @param int|bool $namespace The namespace ID (or false, if the namespace should be ignored)
 122          * @param string $text The page title. Should be valid. Only minimal normalization is applied.
 123          *        Underscores will be replaced.
 124          * @param string $fragment The fragment name (may be empty).
 125          * @param string $interwiki The interwiki name (may be empty).
 126          *
 127          * @throws InvalidArgumentException If the namespace is invalid
 128          * @return string
 129          */
 130         public function formatTitle( $namespace, $text, $fragment = '', $interwiki = '' ) {
 131                 $out = '';
 132                 if ( $interwiki !== '' ) {
 133                         $out = $interwiki . ':';
 134                 }
 135
 136                 if ( $namespace != 0 ) {
 137                         try {
 138                                 $nsName = $this->getNamespaceName( $namespace, $text );
 139                         } catch ( InvalidArgumentException $e ) {
 140                                 // See T165149. Awkward, but better than erroneously linking to the main namespace.
 141                                 $nsName = $this->language->getNsText( NS_SPECIAL ) . ":Badtitle/NS{$namespace}";
 142                         }
 143
 144                         $out .= $nsName . ':';
 145                 }
 146                 $out .= $text;
 147
 148                 if ( $fragment !== '' ) {
 149                         $out .= '#' . $fragment;
 150                 }
 151
 152                 $out = str_replace( '_', ' ', $out );
 153
 154                 return $out;
 155         }
 156
 157         /**
 158          * Parses the given text and constructs a TitleValue.
 159          *
 160          * @param string $text The text to parse
 161          * @param int $defaultNamespace Namespace to assume per default (usually NS_MAIN)
 162          *
 163          * @throws MalformedTitleException
 164          * @return TitleValue
 165          */
 166         public function parseTitle( $text, $defaultNamespace = NS_MAIN ) {
 167                 // Convert things like &eacute; &#257; or &#x3017; into normalized (T16952) text
 168                 $filteredText = Sanitizer::decodeCharReferencesAndNormalize( $text );
 169
 170                 // NOTE: this is an ugly cludge that allows this class to share the
 171                 // code for parsing with the old Title class. The parser code should
 172                 // be refactored to avoid this.
 173                 $parts = $this->splitTitleString( $filteredText, $defaultNamespace );
 174
 175                 // Fragment-only is okay, but only with no namespace
 176                 if ( $parts['dbkey'] === '' &&
 177                 ( $parts['fragment'] === '' || $parts['namespace'] !== NS_MAIN ) ) {
 178                         throw new MalformedTitleException( 'title-invalid-empty', $text );
 179                 }
 180
 181                 return new TitleValue(
 182                         $parts['namespace'],
 183                         $parts['dbkey'],
 184                         $parts['fragment'],
 185                         $parts['interwiki']
 186                 );
 187         }
 188
 189         /**
 190          * Given a namespace and title, return a TitleValue if valid, or null if invalid.
 191          *
 192          * @param int $namespace
 193          * @param string $text
 194          * @param string $fragment
 195          * @param string $interwiki
 196          *
 197          * @return TitleValue|null
 198          */
 199         public function makeTitleValueSafe( $namespace, $text, $fragment = '', $interwiki = '' ) {
 200                 if ( !$this->nsInfo->exists( $namespace ) ) {
 201                         return null;
 202                 }
 203
 204                 $canonicalNs = $this->nsInfo->getCanonicalName( $namespace );
 205                 $fullText = $canonicalNs == '' ? $text : "$canonicalNs:$text";
 206                 if ( strval( $interwiki ) != '' ) {
 207                         $fullText = "$interwiki:$fullText";
 208                 }
 209                 if ( strval( $fragment ) != '' ) {
 210                         $fullText .= '#' . $fragment;
 211                 }
 212
 213                 try {
 214                         $parts = $this->splitTitleString( $fullText );
 215                 } catch ( MalformedTitleException $e ) {
 216                         return null;
 217                 }
 218
 219                 return new TitleValue(
 220                         $parts['namespace'], $parts['dbkey'], $parts['fragment'], $parts['interwiki'] );
 221         }
 222
 223         /**
 224          * @see TitleFormatter::getText()
 225          *
 226          * @param LinkTarget $title
 227          *
 228          * @return string $title->getText()
 229          */
 230         public function getText( LinkTarget $title ) {
 231                 return $title->getText();
 232         }
 233
 234         /**
 235          * @see TitleFormatter::getText()
 236          *
 237          * @param LinkTarget $title
 238          *
 239          * @return string
 240          * @suppress PhanUndeclaredProperty
 241          */
 242         public function getPrefixedText( LinkTarget $title ) {
 243                 if ( !isset( $title->prefixedText ) ) {
 244                         $title->prefixedText = $this->formatTitle(
 245                                 $title->getNamespace(),
 246                                 $title->getText(),
 247                                 '',
 248                                 $title->getInterwiki()
 249                         );
 250                 }
 251
 252                 return $title->prefixedText;
 253         }
 254
 255         /**
 256          * @since 1.27
 257          * @see TitleFormatter::getPrefixedDBkey()
 258          * @param LinkTarget $target
 259          * @return string
 260          */
 261         public function getPrefixedDBkey( LinkTarget $target ) {
 262                 return strtr( $this->formatTitle(
 263                         $target->getNamespace(),
 264                         $target->getDBkey(),
 265                         '',
 266                         $target->getInterwiki()
 267                 ), ' ', '_' );
 268         }
 269
 270         /**
 271          * @see TitleFormatter::getText()
 272          *
 273          * @param LinkTarget $title
 274          *
 275          * @return string
 276          */
 277         public function getFullText( LinkTarget $title ) {
 278                 return $this->formatTitle(
 279                         $title->getNamespace(),
 280                         $title->getText(),
 281                         $title->getFragment(),
 282                         $title->getInterwiki()
 283                 );
 284         }
 285
 286         /**
 287          * Normalizes and splits a title string.
 288          *
 289          * This function removes illegal characters, splits off the interwiki and
 290          * namespace prefixes, sets the other forms, and canonicalizes
 291          * everything.
 292          *
 293          * @todo this method is only exposed as a temporary measure to ease refactoring.
 294          * It was copied with minimal changes from Title::secureAndSplit().
 295          *
 296          * @todo This method should be split up and an appropriate interface
 297          * defined for use by the Title class.
 298          *
 299          * @param string $text
 300          * @param int $defaultNamespace
 301          *
 302          * @throws MalformedTitleException If $text is not a valid title string.
 303          * @return array A map with the fields 'interwiki', 'fragment', 'namespace',
 304          *         'user_case_dbkey', and 'dbkey'.
 305          */
 306         public function splitTitleString( $text, $defaultNamespace = NS_MAIN ) {
 307                 $dbkey = str_replace( ' ', '_', $text );
 308
 309                 # Initialisation
 310                 $parts = [
 311                         'interwiki' => '',
 312                         'local_interwiki' => false,
 313                         'fragment' => '',
 314                         'namespace' => $defaultNamespace,
 315                         'dbkey' => $dbkey,
 316                         'user_case_dbkey' => $dbkey,
 317                 ];
 318
 319                 # Strip Unicode bidi override characters.
 320                 # Sometimes they slip into cut-n-pasted page titles, where the
 321                 # override chars get included in list displays.
 322                 $dbkey = preg_replace( '/[\x{200E}\x{200F}\x{202A}-\x{202E}]+/u', '', $dbkey );
 323
 324                 # Clean up whitespace
 325                 # Note: use of the /u option on preg_replace here will cause
 326                 # input with invalid UTF-8 sequences to be nullified out in PHP 5.2.x,
 327                 # conveniently disabling them.
 328                 $dbkey = preg_replace(
 329                         '/[ _\xA0\x{1680}\x{180E}\x{2000}-\x{200A}\x{2028}\x{2029}\x{202F}\x{205F}\x{3000}]+/u',
 330                         '_',
 331                         $dbkey
 332                 );
 333                 $dbkey = trim( $dbkey, '_' );
 334
 335                 if ( strpos( $dbkey, UtfNormal\Constants::UTF8_REPLACEMENT ) !== false ) {
 336                         # Contained illegal UTF-8 sequences or forbidden Unicode chars.
 337                         throw new MalformedTitleException( 'title-invalid-utf8', $text );
 338                 }
 339
 340                 $parts['dbkey'] = $dbkey;
 341
 342                 # Initial colon indicates main namespace rather than specified default
 343                 # but should not create invalid {ns,title} pairs such as {0,Project:Foo}
 344                 if ( $dbkey !== '' && $dbkey[0] == ':' ) {
 345                         $parts['namespace'] = NS_MAIN;
 346                         $dbkey = substr( $dbkey, 1 ); # remove the colon but continue processing
 347                         $dbkey = trim( $dbkey, '_' ); # remove any subsequent whitespace
 348                 }
 349
 350                 if ( $dbkey == '' ) {
 351                         throw new MalformedTitleException( 'title-invalid-empty', $text );
 352                 }
 353
 354                 # Namespace or interwiki prefix
 355                 $prefixRegexp = "/^(.+?)_*:_*(.*)$/S";
 356                 do {
 357                         $m = [];
 358                         if ( preg_match( $prefixRegexp, $dbkey, $m ) ) {
 359                                 $p = $m[1];
 360                                 $ns = $this->language->getNsIndex( $p );
 361                                 if ( $ns !== false ) {
 362                                         # Ordinary namespace
 363                                         $dbkey = $m[2];
 364                                         $parts['namespace'] = $ns;
 365                                         # For Talk:X pages, check if X has a "namespace" prefix
 366                                         if ( $ns == NS_TALK && preg_match( $prefixRegexp, $dbkey, $x ) ) {
 367                                                 if ( $this->language->getNsIndex( $x[1] ) ) {
 368                                                         # Disallow Talk:File:x type titles...
 369                                                         throw new MalformedTitleException( 'title-invalid-talk-namespace', $text );
 370                                                 } elseif ( $this->interwikiLookup->isValidInterwiki( $x[1] ) ) {
 371                                                         # Disallow Talk:Interwiki:x type titles...
 372                                                         throw new MalformedTitleException( 'title-invalid-talk-namespace', $text );
 373                                                 }
 374                                         }
 375                                 } elseif ( $this->interwikiLookup->isValidInterwiki( $p ) ) {
 376                                         # Interwiki link
 377                                         $dbkey = $m[2];
 378                                         $parts['interwiki'] = $this->language->lc( $p );
 379
 380                                         # Redundant interwiki prefix to the local wiki
 381                                         foreach ( $this->localInterwikis as $localIW ) {
 382                                                 if ( strcasecmp( $parts['interwiki'], $localIW ) == 0 ) {
 383                                                         if ( $dbkey == '' ) {
 384                                                                 # Empty self-links should point to the Main Page, to ensure
 385                                                                 # compatibility with cross-wiki transclusions and the like.
 386                                                                 $mainPage = Title::newMainPage();
 387                                                                 return [
 388                                                                         'interwiki' => $mainPage->getInterwiki(),
 389                                                                         'local_interwiki' => true,
 390                                                                         'fragment' => $mainPage->getFragment(),
 391                                                                         'namespace' => $mainPage->getNamespace(),
 392                                                                         'dbkey' => $mainPage->getDBkey(),
 393                                                                         'user_case_dbkey' => $mainPage->getUserCaseDBKey()
 394                                                                 ];
 395                                                         }
 396                                                         $parts['interwiki'] = '';
 397                                                         # local interwikis should behave like initial-colon links
 398                                                         $parts['local_interwiki'] = true;
 399
 400                                                         # Do another namespace split...
 401                                                         continue 2;
 402                                                 }
 403                                         }
 404
 405                                         # If there's an initial colon after the interwiki, that also
 406                                         # resets the default namespace
 407                                         if ( $dbkey !== '' && $dbkey[0] == ':' ) {
 408                                                 $parts['namespace'] = NS_MAIN;
 409                                                 $dbkey = substr( $dbkey, 1 );
 410                                                 $dbkey = trim( $dbkey, '_' );
 411                                         }
 412                                 }
 413                                 # If there's no recognized interwiki or namespace,
 414                                 # then let the colon expression be part of the title.
 415                         }
 416                         break;
 417                 } while ( true );
 418
 419                 $fragment = strstr( $dbkey, '#' );
 420                 if ( $fragment !== false ) {
 421                         $parts['fragment'] = str_replace( '_', ' ', substr( $fragment, 1 ) );
 422                         $dbkey = substr( $dbkey, 0, strlen( $dbkey ) - strlen( $fragment ) );
 423                         # remove whitespace again: prevents "Foo_bar_#"
 424                         # becoming "Foo_bar_"
 425                         $dbkey = preg_replace( '/_*$/', '', $dbkey );
 426                 }
 427
 428                 # Reject illegal characters.
 429                 $rxTc = self::getTitleInvalidRegex();
 430                 $matches = [];
 431                 if ( preg_match( $rxTc, $dbkey, $matches ) ) {
 432                         throw new MalformedTitleException( 'title-invalid-characters', $text, [ $matches[0] ] );
 433                 }
 434
 435                 # Pages with "/./" or "/../" appearing in the URLs will often be un-
 436                 # reachable due to the way web browsers deal with 'relative' URLs.
 437                 # Also, they conflict with subpage syntax.  Forbid them explicitly.
 438                 if (
 439                         strpos( $dbkey, '.' ) !== false &&
 440                         (
 441                                 $dbkey === '.' || $dbkey === '..' ||
 442                                 strpos( $dbkey, './' ) === 0 ||
 443                                 strpos( $dbkey, '../' ) === 0 ||
 444                                 strpos( $dbkey, '/./' ) !== false ||
 445                                 strpos( $dbkey, '/../' ) !== false ||
 446                                 substr( $dbkey, -2 ) == '/.' ||
 447                                 substr( $dbkey, -3 ) == '/..'
 448                         )
 449                 ) {
 450                         throw new MalformedTitleException( 'title-invalid-relative', $text );
 451                 }
 452
 453                 # Magic tilde sequences? Nu-uh!
 454                 if ( strpos( $dbkey, '~~~' ) !== false ) {
 455                         throw new MalformedTitleException( 'title-invalid-magic-tilde', $text );
 456                 }
 457
 458                 # Limit the size of titles to 255 bytes. This is typically the size of the
 459                 # underlying database field. We make an exception for special pages, which
 460                 # don't need to be stored in the database, and may edge over 255 bytes due
 461                 # to subpage syntax for long titles, e.g. [[Special:Block/Long name]]
 462                 $maxLength = ( $parts['namespace'] != NS_SPECIAL ) ? 255 : 512;
 463                 if ( strlen( $dbkey ) > $maxLength ) {
 464                         throw new MalformedTitleException( 'title-invalid-too-long', $text,
 465                                 [ Message::numParam( $maxLength ) ] );
 466                 }
 467
 468                 # Normally, all wiki links are forced to have an initial capital letter so [[foo]]
 469                 # and [[Foo]] point to the same place.  Don't force it for interwikis, since the
 470                 # other site might be case-sensitive.
 471                 $parts['user_case_dbkey'] = $dbkey;
 472                 if ( $parts['interwiki'] === '' && $this->nsInfo->isCapitalized( $parts['namespace'] ) ) {
 473                         $dbkey = $this->language->ucfirst( $dbkey );
 474                 }
 475
 476                 # Can't make a link to a namespace alone... "empty" local links can only be
 477                 # self-links with a fragment identifier.
 478                 if ( $dbkey == '' && $parts['interwiki'] === '' && $parts['namespace'] != NS_MAIN ) {
 479                         throw new MalformedTitleException( 'title-invalid-empty', $text );
 480                 }
 481
 482                 // Allow IPv6 usernames to start with '::' by canonicalizing IPv6 titles.
 483                 // IP names are not allowed for accounts, and can only be referring to
 484                 // edits from the IP. Given '::' abbreviations and caps/lowercaps,
 485                 // there are numerous ways to present the same IP. Having sp:contribs scan
 486                 // them all is silly and having some show the edits and others not is
 487                 // inconsistent. Same for talk/userpages. Keep them normalized instead.
 488                 if ( $parts['namespace'] == NS_USER || $parts['namespace'] == NS_USER_TALK ) {
 489                         $dbkey = IP::sanitizeIP( $dbkey );
 490                 }
 491
 492                 // Any remaining initial :s are illegal.
 493                 if ( $dbkey !== '' && $dbkey[0] == ':' ) {
 494                         throw new MalformedTitleException( 'title-invalid-leading-colon', $text );
 495                 }
 496
 497                 # Fill fields
 498                 $parts['dbkey'] = $dbkey;
 499
 500                 return $parts;
 501         }
 502
 503         /**
 504          * Returns a simple regex that will match on characters and sequences invalid in titles.
 505          * Note that this doesn't pick up many things that could be wrong with titles, but that
 506          * replacing this regex with something valid will make many titles valid.
 507          * Previously Title::getTitleInvalidRegex()
 508          *
 509          * @return string Regex string
 510          * @since 1.25
 511          */
 512         public static function getTitleInvalidRegex() {
 513                 static $rxTc = false;
 514                 if ( !$rxTc ) {
 515                         # Matching titles will be held as illegal.
 516                         $rxTc = '/' .
 517                                 # Any character not allowed is forbidden...
 518                                 '[^' . Title::legalChars() . ']' .
 519                                 # URL percent encoding sequences interfere with the ability
 520                                 # to round-trip titles -- you can't link to them consistently.
 521                                 '|%[0-9A-Fa-f]{2}' .
 522                                 # XML/HTML character references produce similar issues.
 523                                 '|&[A-Za-z0-9\x80-\xff]+;' .
 524                                 '|&#[0-9]+;' .
 525                                 '|&#x[0-9A-Fa-f]+;' .
 526                                 '/S';
 527                 }
 528
 529                 return $rxTc;
 530         }
 531 }