[Summary view] [Print] [Text view]

   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              'local_interwiki' => false,
 210              'fragment' => '',
 211              'namespace' => $defaultNamespace,
 212              'dbkey' => $dbkey,
 213              'user_case_dbkey' => $dbkey,
 214          );
 215  
 216          # Strip Unicode bidi override characters.
 217          # Sometimes they slip into cut-n-pasted page titles, where the
 218          # override chars get included in list displays.
 219          $dbkey = preg_replace( '/\xE2\x80[\x8E\x8F\xAA-\xAE]/S', '', $dbkey );
 220  
 221          # Clean up whitespace
 222          # Note: use of the /u option on preg_replace here will cause
 223          # input with invalid UTF-8 sequences to be nullified out in PHP 5.2.x,
 224          # conveniently disabling them.
 225          $dbkey = preg_replace(
 226              '/[ _\xA0\x{1680}\x{180E}\x{2000}-\x{200A}\x{2028}\x{2029}\x{202F}\x{205F}\x{3000}]+/u',
 227              '_',
 228              $dbkey
 229          );
 230          $dbkey = trim( $dbkey, '_' );
 231  
 232          if ( strpos( $dbkey, UTF8_REPLACEMENT ) !== false ) {
 233              # Contained illegal UTF-8 sequences or forbidden Unicode chars.
 234              throw new MalformedTitleException( 'Bad UTF-8 sequences found in title: ' . $text );
 235          }
 236  
 237          $parts['dbkey'] = $dbkey;
 238  
 239          # Initial colon indicates main namespace rather than specified default
 240          # but should not create invalid {ns,title} pairs such as {0,Project:Foo}
 241          if ( $dbkey !== '' && ':' == $dbkey[0] ) {
 242              $parts['namespace'] = NS_MAIN;
 243              $dbkey = substr( $dbkey, 1 ); # remove the colon but continue processing
 244              $dbkey = trim( $dbkey, '_' ); # remove any subsequent whitespace
 245          }
 246  
 247          if ( $dbkey == '' ) {
 248              throw new MalformedTitleException( 'Empty title: ' . $text );
 249          }
 250  
 251          # Namespace or interwiki prefix
 252          $prefixRegexp = "/^(.+?)_*:_*(.*)$/S";
 253          do {
 254              $m = array();
 255              if ( preg_match( $prefixRegexp, $dbkey, $m ) ) {
 256                  $p = $m[1];
 257                  if ( ( $ns = $this->language->getNsIndex( $p ) ) !== false ) {
 258                      # Ordinary namespace
 259                      $dbkey = $m[2];
 260                      $parts['namespace'] = $ns;
 261                      # For Talk:X pages, check if X has a "namespace" prefix
 262                      if ( $ns == NS_TALK && preg_match( $prefixRegexp, $dbkey, $x ) ) {
 263                          if ( $this->language->getNsIndex( $x[1] ) ) {
 264                              # Disallow Talk:File:x type titles...
 265                              throw new MalformedTitleException( 'Bad namespace prefix: ' . $text );
 266                          } elseif ( Interwiki::isValidInterwiki( $x[1] ) ) {
 267                              //TODO: get rid of global state!
 268                              # Disallow Talk:Interwiki:x type titles...
 269                              throw new MalformedTitleException( 'Interwiki prefix found in title: ' . $text );
 270                          }
 271                      }
 272                  } elseif ( Interwiki::isValidInterwiki( $p ) ) {
 273                      # Interwiki link
 274                      $dbkey = $m[2];
 275                      $parts['interwiki'] = $this->language->lc( $p );
 276  
 277                      # Redundant interwiki prefix to the local wiki
 278                      foreach ( $this->localInterwikis as $localIW ) {
 279                          if ( 0 == strcasecmp( $parts['interwiki'], $localIW ) ) {
 280                              if ( $dbkey == '' ) {
 281                                  # Empty self-links should point to the Main Page, to ensure
 282                                  # compatibility with cross-wiki transclusions and the like.
 283                                  $mainPage = Title::newMainPage();
 284                                  return array(
 285                                      'interwiki' => $mainPage->getInterwiki(),
 286                                      'local_interwiki' => true,
 287                                      'fragment' => $mainPage->getFragment(),
 288                                      'namespace' => $mainPage->getNamespace(),
 289                                      'dbkey' => $mainPage->getDBkey(),
 290                                      'user_case_dbkey' => $mainPage->getUserCaseDBKey()
 291                                  );
 292                              }
 293                              $parts['interwiki'] = '';
 294                              # local interwikis should behave like initial-colon links
 295                              $parts['local_interwiki'] = true;
 296  
 297                              # Do another namespace split...
 298                              continue 2;
 299                          }
 300                      }
 301  
 302                      # If there's an initial colon after the interwiki, that also
 303                      # resets the default namespace
 304                      if ( $dbkey !== '' && $dbkey[0] == ':' ) {
 305                          $parts['namespace'] = NS_MAIN;
 306                          $dbkey = substr( $dbkey, 1 );
 307                      }
 308                  }
 309                  # If there's no recognized interwiki or namespace,
 310                  # then let the colon expression be part of the title.
 311              }
 312              break;
 313          } while ( true );
 314  
 315          $fragment = strstr( $dbkey, '#' );
 316          if ( false !== $fragment ) {
 317              $parts['fragment'] = str_replace( '_', ' ', substr( $fragment, 1 ) );
 318              $dbkey = substr( $dbkey, 0, strlen( $dbkey ) - strlen( $fragment ) );
 319              # remove whitespace again: prevents "Foo_bar_#"
 320              # becoming "Foo_bar_"
 321              $dbkey = preg_replace( '/_*$/', '', $dbkey );
 322          }
 323  
 324          # Reject illegal characters.
 325          $rxTc = Title::getTitleInvalidRegex();
 326          if ( preg_match( $rxTc, $dbkey ) ) {
 327              throw new MalformedTitleException( 'Illegal characters found in title: ' . $text );
 328          }
 329  
 330          # Pages with "/./" or "/../" appearing in the URLs will often be un-
 331          # reachable due to the way web browsers deal with 'relative' URLs.
 332          # Also, they conflict with subpage syntax.  Forbid them explicitly.
 333          if (
 334              strpos( $dbkey, '.' ) !== false &&
 335              (
 336                  $dbkey === '.' || $dbkey === '..' ||
 337                  strpos( $dbkey, './' ) === 0 ||
 338                  strpos( $dbkey, '../' ) === 0 ||
 339                  strpos( $dbkey, '/./' ) !== false ||
 340                  strpos( $dbkey, '/../' ) !== false ||
 341                  substr( $dbkey, -2 ) == '/.' ||
 342                  substr( $dbkey, -3 ) == '/..'
 343              )
 344          ) {
 345              throw new MalformedTitleException( 'Bad title: ' . $text );
 346          }
 347  
 348          # Magic tilde sequences? Nu-uh!
 349          if ( strpos( $dbkey, '~~~' ) !== false ) {
 350              throw new MalformedTitleException( 'Bad title: ' . $text );
 351          }
 352  
 353          # Limit the size of titles to 255 bytes. This is typically the size of the
 354          # underlying database field. We make an exception for special pages, which
 355          # don't need to be stored in the database, and may edge over 255 bytes due
 356          # to subpage syntax for long titles, e.g. [[Special:Block/Long name]]
 357          if (
 358              ( $parts['namespace'] != NS_SPECIAL && strlen( $dbkey ) > 255 )
 359              || strlen( $dbkey ) > 512
 360          ) {
 361              throw new MalformedTitleException( 'Title too long: ' . substr( $dbkey, 0, 255 ) . '...' );
 362          }
 363  
 364          # Normally, all wiki links are forced to have an initial capital letter so [[foo]]
 365          # and [[Foo]] point to the same place.  Don't force it for interwikis, since the
 366          # other site might be case-sensitive.
 367          $parts['user_case_dbkey'] = $dbkey;
 368          if ( $parts['interwiki'] === '' ) {
 369              $dbkey = Title::capitalize( $dbkey, $parts['namespace'] );
 370          }
 371  
 372          # Can't make a link to a namespace alone... "empty" local links can only be
 373          # self-links with a fragment identifier.
 374          if ( $dbkey == '' && $parts['interwiki'] === '' ) {
 375              if ( $parts['namespace'] != NS_MAIN ) {
 376                  throw new MalformedTitleException( 'Empty title: ' . $text );
 377              }
 378          }
 379  
 380          // Allow IPv6 usernames to start with '::' by canonicalizing IPv6 titles.
 381          // IP names are not allowed for accounts, and can only be referring to
 382          // edits from the IP. Given '::' abbreviations and caps/lowercaps,
 383          // there are numerous ways to present the same IP. Having sp:contribs scan
 384          // them all is silly and having some show the edits and others not is
 385          // inconsistent. Same for talk/userpages. Keep them normalized instead.
 386          if ( $parts['namespace'] == NS_USER || $parts['namespace'] == NS_USER_TALK ) {
 387              $dbkey = IP::sanitizeIP( $dbkey );
 388          }
 389  
 390          // Any remaining initial :s are illegal.
 391          if ( $dbkey !== '' && ':' == $dbkey[0] ) {
 392              throw new MalformedTitleException( 'Title must not start with a colon: ' . $text );
 393          }
 394  
 395          # Fill fields
 396          $parts['dbkey'] = $dbkey;
 397  
 398          return $parts;
 399      }
 400  }