3 * A codec for %MediaWiki page titles.
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.
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.
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
22 * @author Daniel Kinzler
24 use MediaWiki\Linker\LinkTarget
;
27 * A codec for %MediaWiki page titles.
29 * @note Normalization and validation is applied while parsing, not when formatting.
30 * It's possible to construct a TitleValue with an invalid title, and use MediaWikiTitleCodec
31 * to generate an (invalid) title string from it. TitleValues should be constructed only
32 * via parseTitle() or from a (semi)trusted source, such as the database.
34 * @see https://www.mediawiki.org/wiki/Requests_for_comment/TitleValue
37 class MediaWikiTitleCodec
implements TitleFormatter
, TitleParser
{
46 protected $genderCache;
51 protected $localInterwikis;
54 * @param Language $language The language object to use for localizing namespace names.
55 * @param GenderCache $genderCache The gender cache for generating gendered namespace names
56 * @param string[]|string $localInterwikis
58 public function __construct( Language
$language, GenderCache
$genderCache,
61 $this->language
= $language;
62 $this->genderCache
= $genderCache;
63 $this->localInterwikis
= (array)$localInterwikis;
67 * @see TitleFormatter::getNamespaceName()
69 * @param int $namespace
72 * @throws InvalidArgumentException If the namespace is invalid
75 public function getNamespaceName( $namespace, $text ) {
76 if ( $this->language
->needsGenderDistinction() &&
77 MWNamespace
::hasGenderDistinction( $namespace )
80 // NOTE: we are assuming here that the title text is a user name!
81 $gender = $this->genderCache
->getGenderOf( $text, __METHOD__
);
82 $name = $this->language
->getGenderNsText( $namespace, $gender );
84 $name = $this->language
->getNsText( $namespace );
87 if ( $name === false ) {
88 throw new InvalidArgumentException( 'Unknown namespace ID: ' . $namespace );
95 * @see TitleFormatter::formatTitle()
97 * @param int|bool $namespace The namespace ID (or false, if the namespace should be ignored)
98 * @param string $text The page title. Should be valid. Only minimal normalization is applied.
99 * Underscores will be replaced.
100 * @param string $fragment The fragment name (may be empty).
101 * @param string $interwiki The interwiki name (may be empty).
103 * @throws InvalidArgumentException If the namespace is invalid
106 public function formatTitle( $namespace, $text, $fragment = '', $interwiki = '' ) {
107 if ( $namespace !== false ) {
108 $namespace = $this->getNamespaceName( $namespace, $text );
110 if ( $namespace !== '' ) {
111 $text = $namespace . ':' . $text;
115 if ( $fragment !== '' ) {
116 $text = $text . '#' . $fragment;
119 if ( $interwiki !== '' ) {
120 $text = $interwiki . ':' . $text;
123 $text = str_replace( '_', ' ', $text );
129 * Parses the given text and constructs a TitleValue. Normalization
130 * is applied according to the rules appropriate for the form specified by $form.
132 * @param string $text The text to parse
133 * @param int $defaultNamespace Namespace to assume per default (usually NS_MAIN)
135 * @throws MalformedTitleException
138 public function parseTitle( $text, $defaultNamespace ) {
139 // NOTE: this is an ugly cludge that allows this class to share the
140 // code for parsing with the old Title class. The parser code should
141 // be refactored to avoid this.
142 $parts = $this->splitTitleString( $text, $defaultNamespace );
144 // Relative fragment links are not supported by TitleValue
145 if ( $parts['dbkey'] === '' ) {
146 throw new MalformedTitleException( 'title-invalid-empty', $text );
149 return new TitleValue(
158 * @see TitleFormatter::getText()
160 * @param LinkTarget $title
162 * @return string $title->getText()
164 public function getText( LinkTarget
$title ) {
165 return $this->formatTitle( false, $title->getText(), '' );
169 * @see TitleFormatter::getText()
171 * @param LinkTarget $title
175 public function getPrefixedText( LinkTarget
$title ) {
176 return $this->formatTitle(
177 $title->getNamespace(),
180 $title->getInterwiki()
186 * @see TitleFormatter::getPrefixedDBkey()
187 * @param LinkTarget $target
190 public function getPrefixedDBkey( LinkTarget
$target ) {
192 if ( $target->isExternal() ) {
193 $key .= $target->getInterwiki() . ':';
195 // Try to get a namespace name, but fallback
196 // to empty string if it doesn't exist
198 $nsName = $this->getNamespaceName(
199 $target->getNamespace(),
202 } catch ( InvalidArgumentException
$e ) {
206 if ( $target->getNamespace() !== 0 ) {
207 $key .= $nsName . ':';
210 $key .= $target->getText();
212 return strtr( $key, ' ', '_' );
216 * @see TitleFormatter::getText()
218 * @param LinkTarget $title
222 public function getFullText( LinkTarget
$title ) {
223 return $this->formatTitle(
224 $title->getNamespace(),
226 $title->getFragment(),
227 $title->getInterwiki()
232 * Normalizes and splits a title string.
234 * This function removes illegal characters, splits off the interwiki and
235 * namespace prefixes, sets the other forms, and canonicalizes
238 * @todo this method is only exposed as a temporary measure to ease refactoring.
239 * It was copied with minimal changes from Title::secureAndSplit().
241 * @todo This method should be split up and an appropriate interface
242 * defined for use by the Title class.
244 * @param string $text
245 * @param int $defaultNamespace
247 * @throws MalformedTitleException If $text is not a valid title string.
248 * @return array A map with the fields 'interwiki', 'fragment', 'namespace',
249 * 'user_case_dbkey', and 'dbkey'.
251 public function splitTitleString( $text, $defaultNamespace = NS_MAIN
) {
252 $dbkey = str_replace( ' ', '_', $text );
257 'local_interwiki' => false,
259 'namespace' => $defaultNamespace,
261 'user_case_dbkey' => $dbkey,
264 # Strip Unicode bidi override characters.
265 # Sometimes they slip into cut-n-pasted page titles, where the
266 # override chars get included in list displays.
267 $dbkey = preg_replace( '/\xE2\x80[\x8E\x8F\xAA-\xAE]/S', '', $dbkey );
269 # Clean up whitespace
270 # Note: use of the /u option on preg_replace here will cause
271 # input with invalid UTF-8 sequences to be nullified out in PHP 5.2.x,
272 # conveniently disabling them.
273 $dbkey = preg_replace(
274 '/[ _\xA0\x{1680}\x{180E}\x{2000}-\x{200A}\x{2028}\x{2029}\x{202F}\x{205F}\x{3000}]+/u',
278 $dbkey = trim( $dbkey, '_' );
280 if ( strpos( $dbkey, UtfNormal\Constants
::UTF8_REPLACEMENT
) !== false ) {
281 # Contained illegal UTF-8 sequences or forbidden Unicode chars.
282 throw new MalformedTitleException( 'title-invalid-utf8', $text );
285 $parts['dbkey'] = $dbkey;
287 # Initial colon indicates main namespace rather than specified default
288 # but should not create invalid {ns,title} pairs such as {0,Project:Foo}
289 if ( $dbkey !== '' && ':' == $dbkey[0] ) {
290 $parts['namespace'] = NS_MAIN
;
291 $dbkey = substr( $dbkey, 1 ); # remove the colon but continue processing
292 $dbkey = trim( $dbkey, '_' ); # remove any subsequent whitespace
295 if ( $dbkey == '' ) {
296 throw new MalformedTitleException( 'title-invalid-empty', $text );
299 # Namespace or interwiki prefix
300 $prefixRegexp = "/^(.+?)_*:_*(.*)$/S";
303 if ( preg_match( $prefixRegexp, $dbkey, $m ) ) {
305 $ns = $this->language
->getNsIndex( $p );
306 if ( $ns !== false ) {
309 $parts['namespace'] = $ns;
310 # For Talk:X pages, check if X has a "namespace" prefix
311 if ( $ns == NS_TALK
&& preg_match( $prefixRegexp, $dbkey, $x ) ) {
312 if ( $this->language
->getNsIndex( $x[1] ) ) {
313 # Disallow Talk:File:x type titles...
314 throw new MalformedTitleException( 'title-invalid-talk-namespace', $text );
315 } elseif ( Interwiki
::isValidInterwiki( $x[1] ) ) {
316 // TODO: get rid of global state!
317 # Disallow Talk:Interwiki:x type titles...
318 throw new MalformedTitleException( 'title-invalid-talk-namespace', $text );
321 } elseif ( Interwiki
::isValidInterwiki( $p ) ) {
324 $parts['interwiki'] = $this->language
->lc( $p );
326 # Redundant interwiki prefix to the local wiki
327 foreach ( $this->localInterwikis
as $localIW ) {
328 if ( 0 == strcasecmp( $parts['interwiki'], $localIW ) ) {
329 if ( $dbkey == '' ) {
330 # Empty self-links should point to the Main Page, to ensure
331 # compatibility with cross-wiki transclusions and the like.
332 $mainPage = Title
::newMainPage();
334 'interwiki' => $mainPage->getInterwiki(),
335 'local_interwiki' => true,
336 'fragment' => $mainPage->getFragment(),
337 'namespace' => $mainPage->getNamespace(),
338 'dbkey' => $mainPage->getDBkey(),
339 'user_case_dbkey' => $mainPage->getUserCaseDBKey()
342 $parts['interwiki'] = '';
343 # local interwikis should behave like initial-colon links
344 $parts['local_interwiki'] = true;
346 # Do another namespace split...
351 # If there's an initial colon after the interwiki, that also
352 # resets the default namespace
353 if ( $dbkey !== '' && $dbkey[0] == ':' ) {
354 $parts['namespace'] = NS_MAIN
;
355 $dbkey = substr( $dbkey, 1 );
358 # If there's no recognized interwiki or namespace,
359 # then let the colon expression be part of the title.
364 $fragment = strstr( $dbkey, '#' );
365 if ( false !== $fragment ) {
366 $parts['fragment'] = str_replace( '_', ' ', substr( $fragment, 1 ) );
367 $dbkey = substr( $dbkey, 0, strlen( $dbkey ) - strlen( $fragment ) );
368 # remove whitespace again: prevents "Foo_bar_#"
369 # becoming "Foo_bar_"
370 $dbkey = preg_replace( '/_*$/', '', $dbkey );
373 # Reject illegal characters.
374 $rxTc = self
::getTitleInvalidRegex();
376 if ( preg_match( $rxTc, $dbkey, $matches ) ) {
377 throw new MalformedTitleException( 'title-invalid-characters', $text, [ $matches[0] ] );
380 # Pages with "/./" or "/../" appearing in the URLs will often be un-
381 # reachable due to the way web browsers deal with 'relative' URLs.
382 # Also, they conflict with subpage syntax. Forbid them explicitly.
384 strpos( $dbkey, '.' ) !== false &&
386 $dbkey === '.' ||
$dbkey === '..' ||
387 strpos( $dbkey, './' ) === 0 ||
388 strpos( $dbkey, '../' ) === 0 ||
389 strpos( $dbkey, '/./' ) !== false ||
390 strpos( $dbkey, '/../' ) !== false ||
391 substr( $dbkey, -2 ) == '/.' ||
392 substr( $dbkey, -3 ) == '/..'
395 throw new MalformedTitleException( 'title-invalid-relative', $text );
398 # Magic tilde sequences? Nu-uh!
399 if ( strpos( $dbkey, '~~~' ) !== false ) {
400 throw new MalformedTitleException( 'title-invalid-magic-tilde', $text );
403 # Limit the size of titles to 255 bytes. This is typically the size of the
404 # underlying database field. We make an exception for special pages, which
405 # don't need to be stored in the database, and may edge over 255 bytes due
406 # to subpage syntax for long titles, e.g. [[Special:Block/Long name]]
407 $maxLength = ( $parts['namespace'] != NS_SPECIAL
) ?
255 : 512;
408 if ( strlen( $dbkey ) > $maxLength ) {
409 throw new MalformedTitleException( 'title-invalid-too-long', $text,
410 [ Message
::numParam( $maxLength ) ] );
413 # Normally, all wiki links are forced to have an initial capital letter so [[foo]]
414 # and [[Foo]] point to the same place. Don't force it for interwikis, since the
415 # other site might be case-sensitive.
416 $parts['user_case_dbkey'] = $dbkey;
417 if ( $parts['interwiki'] === '' ) {
418 $dbkey = Title
::capitalize( $dbkey, $parts['namespace'] );
421 # Can't make a link to a namespace alone... "empty" local links can only be
422 # self-links with a fragment identifier.
423 if ( $dbkey == '' && $parts['interwiki'] === '' ) {
424 if ( $parts['namespace'] != NS_MAIN
) {
425 throw new MalformedTitleException( 'title-invalid-empty', $text );
429 // Allow IPv6 usernames to start with '::' by canonicalizing IPv6 titles.
430 // IP names are not allowed for accounts, and can only be referring to
431 // edits from the IP. Given '::' abbreviations and caps/lowercaps,
432 // there are numerous ways to present the same IP. Having sp:contribs scan
433 // them all is silly and having some show the edits and others not is
434 // inconsistent. Same for talk/userpages. Keep them normalized instead.
435 if ( $parts['namespace'] == NS_USER ||
$parts['namespace'] == NS_USER_TALK
) {
436 $dbkey = IP
::sanitizeIP( $dbkey );
439 // Any remaining initial :s are illegal.
440 if ( $dbkey !== '' && ':' == $dbkey[0] ) {
441 throw new MalformedTitleException( 'title-invalid-leading-colon', $text );
445 $parts['dbkey'] = $dbkey;
451 * Returns a simple regex that will match on characters and sequences invalid in titles.
452 * Note that this doesn't pick up many things that could be wrong with titles, but that
453 * replacing this regex with something valid will make many titles valid.
454 * Previously Title::getTitleInvalidRegex()
456 * @return string Regex string
459 public static function getTitleInvalidRegex() {
460 static $rxTc = false;
462 # Matching titles will be held as illegal.
464 # Any character not allowed is forbidden...
465 '[^' . Title
::legalChars() . ']' .
466 # URL percent encoding sequences interfere with the ability
467 # to round-trip titles -- you can't link to them consistently.
469 # XML/HTML character references produce similar issues.
470 '|&[A-Za-z0-9\x80-\xff]+;' .
472 '|&#x[0-9A-Fa-f]+;' .