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  * @license GPL 2+
  22  * @author Daniel Kinzler
  23  */
  24
  25 /**
  26  * A codec for %MediaWiki page titles.
  27  *
  28  * @note Normalization and validation is applied while parsing, not when formatting.
  29  * It's possible to construct a TitleValue with an invalid title, and use MediaWikiTitleCodec
  30  * to generate an (invalid) title string from it. TitleValues should be constructed only
  31  * via parseTitle() or from a (semi)trusted source, such as the database.
  32  *
  33  * @see https://www.mediawiki.org/wiki/Requests_for_comment/TitleValue
  34  */
  35 class MediaWikiTitleCodec implements TitleFormatter, TitleParser {
  36         /**
  37          * @var Language
  38          */
  39         protected $language;
  40
  41         /**
  42          * @var GenderCache
  43          */
  44         protected $genderCache;
  45
  46         /**
  47          * @var string[]
  48          */
  49         protected $localInterwikis;
  50
  51         /**
  52          * @param Language $language the language object to use for localizing namespace names.
  53          * @param GenderCache $genderCache the gender cache for generating gendered namespace names
  54          * @param string[]|string $localInterwikis
  55          */
  56         public function __construct( Language $language, GenderCache $genderCache,
  57                 $localInterwikis = array()
  58         ) {
  59                 $this->language = $language;
  60                 $this->genderCache = $genderCache;
  61                 $this->localInterwikis = (array)$localInterwikis;
  62         }
  63
  64         /**
  65          * @see TitleFormatter::getNamespaceName()
  66          *
  67          * @param int $namespace
  68          * @param string $text
  69          *
  70          * @throws InvalidArgumentException if the namespace is invalid
  71          * @return string
  72          */
  73         public function getNamespaceName( $namespace, $text ) {
  74                 if ( $this->language->needsGenderDistinction() &&
  75                         MWNamespace::hasGenderDistinction( $namespace )
  76                 ) {
  77
  78                         //NOTE: we are assuming here that the title text is a user name!
  79                         $gender = $this->genderCache->getGenderOf( $text, __METHOD__ );
  80                         $name = $this->language->getGenderNsText( $namespace, $gender );
  81                 } else {
  82                         $name = $this->language->getNsText( $namespace );
  83                 }
  84
  85                 if ( $name === false ) {
  86                         throw new InvalidArgumentException( 'Unknown namespace ID: ' . $namespace );
  87                 }
  88
  89                 return $name;
  90         }
  91
  92         /**
  93          * @see TitleFormatter::formatTitle()
  94          *
  95          * @param int|bool $namespace The namespace ID (or false, if the namespace should be ignored)
  96          * @param string $text The page title. Should be valid. Only minimal normalization is applied.
  97          *        Underscores will be replaced.
  98          * @param string $fragment The fragment name (may be empty).
  99          *
 100          * @throws InvalidArgumentException if the namespace is invalid
 101          * @return string
 102          */
 103         public function formatTitle( $namespace, $text, $fragment = '' ) {
 104                 if ( $namespace !== false ) {
 105                         $namespace = $this->getNamespaceName( $namespace, $text );
 106
 107                         if ( $namespace !== '' ) {
 108                                 $text = $namespace . ':' . $text;
 109                         }
 110                 }
 111
 112                 if ( $fragment !== '' ) {
 113                         $text = $text . '#' . $fragment;
 114                 }
 115
 116                 $text = str_replace( '_', ' ', $text );
 117
 118                 return $text;
 119         }
 120
 121         /**
 122          * Parses the given text and constructs a TitleValue. Normalization
 123          * is applied according to the rules appropriate for the form specified by $form.
 124          *
 125          * @param string $text The text to parse
 126          * @param int $defaultNamespace Namespace to assume per default (usually NS_MAIN)
 127          *
 128          * @throws MalformedTitleException
 129          * @return TitleValue
 130          */
 131         public function parseTitle( $text, $defaultNamespace ) {
 132                 // NOTE: this is an ugly cludge that allows this class to share the
 133                 // code for parsing with the old Title class. The parser code should
 134                 // be refactored to avoid this.
 135                 $parts = $this->splitTitleString( $text, $defaultNamespace );
 136
 137                 // Interwiki links are not supported by TitleValue
 138                 if ( $parts['interwiki'] !== '' ) {
 139                         throw new MalformedTitleException( 'Title must not contain an interwiki prefix: ' . $text );
 140                 }
 141
 142                 // Relative fragment links are not supported by TitleValue
 143                 if ( $parts['dbkey'] === '' ) {
 144                         throw new MalformedTitleException( 'Title must not be empty: ' . $text );
 145                 }
 146
 147                 return new TitleValue( $parts['namespace'], $parts['dbkey'], $parts['fragment'] );
 148         }
 149
 150         /**
 151          * @see TitleFormatter::getText()
 152          *
 153          * @param TitleValue $title
 154          *
 155          * @return string $title->getText()
 156          */
 157         public function getText( TitleValue $title ) {
 158                 return $this->formatTitle( false, $title->getText(), '' );
 159         }
 160
 161         /**
 162          * @see TitleFormatter::getText()
 163          *
 164          * @param TitleValue $title
 165          *
 166          * @return string
 167          */
 168         public function getPrefixedText( TitleValue $title ) {
 169                 return $this->formatTitle( $title->getNamespace(), $title->getText(), '' );
 170         }
 171
 172         /**
 173          * @see TitleFormatter::getText()
 174          *
 175          * @param TitleValue $title
 176          *
 177          * @return string
 178          */
 179         public function getFullText( TitleValue $title ) {
 180                 return $this->formatTitle( $title->getNamespace(), $title->getText(), $title->getFragment() );
 181         }
 182
 183         /**
 184          * Normalizes and splits a title string.
 185          *
 186          * This function removes illegal characters, splits off the interwiki and
 187          * namespace prefixes, sets the other forms, and canonicalizes
 188          * everything.
 189          *
 190          * @todo this method is only exposed as a temporary measure to ease refactoring.
 191          * It was copied with minimal changes from Title::secureAndSplit().
 192          *
 193          * @todo This method should be split up and an appropriate interface
 194          * defined for use by the Title class.
 195          *
 196          * @param string $text
 197          * @param int $defaultNamespace
 198          *
 199          * @throws MalformedTitleException If $text is not a valid title string.
 200          * @return array A mapp with the fields 'interwiki', 'fragment', 'namespace',
 201          *         'user_case_dbkey', and 'dbkey'.
 202          */
 203         public function splitTitleString( $text, $defaultNamespace = NS_MAIN ) {
 204                 $dbkey = str_replace( ' ', '_', $text );
 205
 206                 # Initialisation
 207                 $parts = array(
 208                         'interwiki' => '',
 209                         'fragment' => '',
 210                         'namespace' => $defaultNamespace,
 211                         'dbkey' => $dbkey,
 212                         'user_case_dbkey' => $dbkey,
 213                 );
 214
 215                 # Strip Unicode bidi override characters.
 216                 # Sometimes they slip into cut-n-pasted page titles, where the
 217                 # override chars get included in list displays.
 218                 $dbkey = preg_replace( '/\xE2\x80[\x8E\x8F\xAA-\xAE]/S', '', $dbkey );
 219
 220                 # Clean up whitespace
 221                 # Note: use of the /u option on preg_replace here will cause
 222                 # input with invalid UTF-8 sequences to be nullified out in PHP 5.2.x,
 223                 # conveniently disabling them.
 224                 $dbkey = preg_replace(
 225                         '/[ _\xA0\x{1680}\x{180E}\x{2000}-\x{200A}\x{2028}\x{2029}\x{202F}\x{205F}\x{3000}]+/u',
 226                         '_',
 227                         $dbkey
 228                 );
 229                 $dbkey = trim( $dbkey, '_' );
 230
 231                 if ( strpos( $dbkey, UTF8_REPLACEMENT ) !== false ) {
 232                         # Contained illegal UTF-8 sequences or forbidden Unicode chars.
 233                         throw new MalformedTitleException( 'Bad UTF-8 sequences found in title: ' . $text );
 234                 }
 235
 236                 $parts['dbkey'] = $dbkey;
 237
 238                 # Initial colon indicates main namespace rather than specified default
 239                 # but should not create invalid {ns,title} pairs such as {0,Project:Foo}
 240                 if ( $dbkey !== '' && ':' == $dbkey[0] ) {
 241                         $parts['namespace'] = NS_MAIN;
 242                         $dbkey = substr( $dbkey, 1 ); # remove the colon but continue processing
 243                         $dbkey = trim( $dbkey, '_' ); # remove any subsequent whitespace
 244                 }
 245
 246                 if ( $dbkey == '' ) {
 247                         throw new MalformedTitleException( 'Empty title: ' . $text );
 248                 }
 249
 250                 # Namespace or interwiki prefix
 251                 $prefixRegexp = "/^(.+?)_*:_*(.*)$/S";
 252                 do {
 253                         $m = array();
 254                         if ( preg_match( $prefixRegexp, $dbkey, $m ) ) {
 255                                 $p = $m[1];
 256                                 if ( ( $ns = $this->language->getNsIndex( $p ) ) !== false ) {
 257                                         # Ordinary namespace
 258                                         $dbkey = $m[2];
 259                                         $parts['namespace'] = $ns;
 260                                         # For Talk:X pages, check if X has a "namespace" prefix
 261                                         if ( $ns == NS_TALK && preg_match( $prefixRegexp, $dbkey, $x ) ) {
 262                                                 if ( $this->language->getNsIndex( $x[1] ) ) {
 263                                                         # Disallow Talk:File:x type titles...
 264                                                         throw new MalformedTitleException( 'Bad namespace prefix: ' . $text );
 265                                                 } elseif ( Interwiki::isValidInterwiki( $x[1] ) ) {
 266                                                         //TODO: get rid of global state!
 267                                                         # Disallow Talk:Interwiki:x type titles...
 268                                                         throw new MalformedTitleException( 'Interwiki prefix found in title: ' . $text );
 269                                                 }
 270                                         }
 271                                 } elseif ( Interwiki::isValidInterwiki( $p ) ) {
 272                                         # Interwiki link
 273                                         $dbkey = $m[2];
 274                                         $parts['interwiki'] = $this->language->lc( $p );
 275
 276                                         # Redundant interwiki prefix to the local wiki
 277                                         foreach ( $this->localInterwikis as $localIW ) {
 278                                                 if ( 0 == strcasecmp( $parts['interwiki'], $localIW ) ) {
 279                                                         if ( $dbkey == '' ) {
 280                                                                 # Empty self-links should point to the Main Page, to ensure
 281                                                                 # compatibility with cross-wiki transclusions and the like.
 282                                                                 $mainPage = Title::newMainPage();
 283                                                                 return array(
 284                                                                         'interwiki' => $mainPage->getInterwiki(),
 285                                                                         'fragment' => $mainPage->getFragment(),
 286                                                                         'namespace' => $mainPage->getNamespace(),
 287                                                                         'dbkey' => $mainPage->getDBkey(),
 288                                                                         'user_case_dbkey' => $mainPage->getUserCaseDBKey()
 289                                                                 );
 290                                                         }
 291                                                         $parts['interwiki'] = '';
 292
 293                                                         # Do another namespace split...
 294                                                         continue 2;
 295                                                 }
 296                                         }
 297
 298                                         # If there's an initial colon after the interwiki, that also
 299                                         # resets the default namespace
 300                                         if ( $dbkey !== '' && $dbkey[0] == ':' ) {
 301                                                 $parts['namespace'] = NS_MAIN;
 302                                                 $dbkey = substr( $dbkey, 1 );
 303                                         }
 304                                 }
 305                                 # If there's no recognized interwiki or namespace,
 306                                 # then let the colon expression be part of the title.
 307                         }
 308                         break;
 309                 } while ( true );
 310
 311                 $fragment = strstr( $dbkey, '#' );
 312                 if ( false !== $fragment ) {
 313                         $parts['fragment'] = str_replace( '_', ' ', substr( $fragment, 1 ) );
 314                         $dbkey = substr( $dbkey, 0, strlen( $dbkey ) - strlen( $fragment ) );
 315                         # remove whitespace again: prevents "Foo_bar_#"
 316                         # becoming "Foo_bar_"
 317                         $dbkey = preg_replace( '/_*$/', '', $dbkey );
 318                 }
 319
 320                 # Reject illegal characters.
 321                 $rxTc = Title::getTitleInvalidRegex();
 322                 if ( preg_match( $rxTc, $dbkey ) ) {
 323                         throw new MalformedTitleException( 'Illegal characters found in title: ' . $text );
 324                 }
 325
 326                 # Pages with "/./" or "/../" appearing in the URLs will often be un-
 327                 # reachable due to the way web browsers deal with 'relative' URLs.
 328                 # Also, they conflict with subpage syntax.  Forbid them explicitly.
 329                 if (
 330                         strpos( $dbkey, '.' ) !== false &&
 331                         (
 332                                 $dbkey === '.' || $dbkey === '..' ||
 333                                 strpos( $dbkey, './' ) === 0 ||
 334                                 strpos( $dbkey, '../' ) === 0 ||
 335                                 strpos( $dbkey, '/./' ) !== false ||
 336                                 strpos( $dbkey, '/../' ) !== false ||
 337                                 substr( $dbkey, -2 ) == '/.' ||
 338                                 substr( $dbkey, -3 ) == '/..'
 339                         )
 340                 ) {
 341                         throw new MalformedTitleException( 'Bad title: ' . $text );
 342                 }
 343
 344                 # Magic tilde sequences? Nu-uh!
 345                 if ( strpos( $dbkey, '~~~' ) !== false ) {
 346                         throw new MalformedTitleException( 'Bad title: ' . $text );
 347                 }
 348
 349                 # Limit the size of titles to 255 bytes. This is typically the size of the
 350                 # underlying database field. We make an exception for special pages, which
 351                 # don't need to be stored in the database, and may edge over 255 bytes due
 352                 # to subpage syntax for long titles, e.g. [[Special:Block/Long name]]
 353                 if (
 354                         ( $parts['namespace'] != NS_SPECIAL && strlen( $dbkey ) > 255 )
 355                         || strlen( $dbkey ) > 512
 356                 ) {
 357                         throw new MalformedTitleException( 'Title too long: ' . substr( $dbkey, 0, 255 ) . '...' );
 358                 }
 359
 360                 # Normally, all wiki links are forced to have an initial capital letter so [[foo]]
 361                 # and [[Foo]] point to the same place.  Don't force it for interwikis, since the
 362                 # other site might be case-sensitive.
 363                 $parts['user_case_dbkey'] = $dbkey;
 364                 if ( $parts['interwiki'] === '' ) {
 365                         $dbkey = Title::capitalize( $dbkey, $parts['namespace'] );
 366                 }
 367
 368                 # Can't make a link to a namespace alone... "empty" local links can only be
 369                 # self-links with a fragment identifier.
 370                 if ( $dbkey == '' && $parts['interwiki'] === '' ) {
 371                         if ( $parts['namespace'] != NS_MAIN ) {
 372                                 throw new MalformedTitleException( 'Empty title: ' . $text );
 373                         }
 374                 }
 375
 376                 // Allow IPv6 usernames to start with '::' by canonicalizing IPv6 titles.
 377                 // IP names are not allowed for accounts, and can only be referring to
 378                 // edits from the IP. Given '::' abbreviations and caps/lowercaps,
 379                 // there are numerous ways to present the same IP. Having sp:contribs scan
 380                 // them all is silly and having some show the edits and others not is
 381                 // inconsistent. Same for talk/userpages. Keep them normalized instead.
 382                 if ( $parts['namespace'] == NS_USER || $parts['namespace'] == NS_USER_TALK ) {
 383                         $dbkey = IP::sanitizeIP( $dbkey );
 384                 }
 385
 386                 // Any remaining initial :s are illegal.
 387                 if ( $dbkey !== '' && ':' == $dbkey[0] ) {
 388                         throw new MalformedTitleException( 'Title must not start with a colon: ' . $text );
 389                 }
 390
 391                 # Fill fields
 392                 $parts['dbkey'] = $dbkey;
 393
 394                 return $parts;
 395         }
 396 }