diff options
Diffstat (limited to 'includes/title')
-rw-r--r-- | includes/title/MalformedTitleException.php | 32 | ||||
-rw-r--r-- | includes/title/MediaWikiPageLinkRenderer.php | 131 | ||||
-rw-r--r-- | includes/title/MediaWikiTitleCodec.php | 400 | ||||
-rw-r--r-- | includes/title/PageLinkRenderer.php | 67 | ||||
-rw-r--r-- | includes/title/TitleFormatter.php | 90 | ||||
-rw-r--r-- | includes/title/TitleParser.php | 47 | ||||
-rw-r--r-- | includes/title/TitleValue.php | 161 |
7 files changed, 928 insertions, 0 deletions
diff --git a/includes/title/MalformedTitleException.php b/includes/title/MalformedTitleException.php new file mode 100644 index 00000000..a8a5d754 --- /dev/null +++ b/includes/title/MalformedTitleException.php @@ -0,0 +1,32 @@ +<?php +/** + * Representation of a page title within %MediaWiki. + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License along + * with this program; if not, write to the Free Software Foundation, Inc., + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + * http://www.gnu.org/copyleft/gpl.html + * + * @file + * @license GPL 2+ + * @author Daniel Kinzler + */ + +/** + * MalformedTitleException is thrown when a TitleParser is unable to parse a title string. + * + * @license GPL 2+ + * @author Daniel Kinzler + */ +class MalformedTitleException extends Exception { +} diff --git a/includes/title/MediaWikiPageLinkRenderer.php b/includes/title/MediaWikiPageLinkRenderer.php new file mode 100644 index 00000000..f46cb5e3 --- /dev/null +++ b/includes/title/MediaWikiPageLinkRenderer.php @@ -0,0 +1,131 @@ +<?php +/** + * A service for generating links from page titles + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License along + * with this program; if not, write to the Free Software Foundation, Inc., + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + * http://www.gnu.org/copyleft/gpl.html + * + * @file + * @license GPL 2+ + * @author Daniel Kinzler + */ + +/** + * A service for generating links from page titles. + * + * @see https://www.mediawiki.org/wiki/Requests_for_comment/TitleValue + */ +class MediaWikiPageLinkRenderer implements PageLinkRenderer { + /** + * @var TitleFormatter + */ + protected $formatter; + + /** + * @var string + */ + protected $baseUrl; + + /** + * @note $formatter and $baseUrl are currently not used for generating links, + * since we still rely on the Linker class to generate the actual HTML. + * Once this is reversed so that Linker becomes a legacy interface to + * HtmlPageLinkRenderer, we will be using them, so it seems prudent to + * already declare the dependency and inject them. + * + * @param TitleFormatter $formatter Formatter for generating the target title string + * @param string $baseUrl (currently unused, pending refactoring of Linker). + * Defaults to $wgArticlePath. + */ + public function __construct( TitleFormatter $formatter, $baseUrl = null ) { + if ( $baseUrl === null ) { + $baseUrl = $GLOBALS['wgArticlePath']; + } + + $this->formatter = $formatter; + $this->baseUrl = $baseUrl; + } + + /** + * Returns the (partial) URL for the given page (including any section identifier). + * + * @param TitleValue $page The link's target + * @param array $params Any additional URL parameters. + * + * @return string + */ + public function getPageUrl( TitleValue $page, $params = array() ) { + //TODO: move the code from Linker::linkUrl here! + //The below is just a rough estimation! + + $name = $this->formatter->getPrefixedText( $page ); + $name = str_replace( ' ', '_', $name ); + $name = wfUrlencode( $name ); + + $url = $this->baseUrl . $name; + + if ( $params ) { + $separator = ( strpos( $url, '?' ) ) ? '&' : '?'; + $url .= $separator . wfArrayToCgi( $params ); + } + + $fragment = $page->getFragment(); + if ( $fragment !== '' ) { + $url = $url . '#' . wfUrlencode( $fragment ); + } + + return $url; + } + + /** + * Returns an HTML link to the given page, using the given surface text. + * + * @param TitleValue $page The link's target + * @param string $text The link's surface text (will be derived from $page if not given). + * + * @return string + */ + public function renderHtmlLink( TitleValue $page, $text = null ) { + if ( $text === null ) { + $text = $this->formatter->getFullText( $page ); + } + + // TODO: move the logic implemented by Linker here, + // using $this->formatter and $this->baseUrl, and + // re-implement Linker to use a HtmlPageLinkRenderer. + $title = Title::newFromTitleValue( $page ); + $link = Linker::link( $title, htmlspecialchars( $text ) ); + + return $link; + } + + /** + * Returns a wikitext link to the given page, using the given surface text. + * + * @param TitleValue $page The link's target + * @param string $text The link's surface text (will be derived from $page if not given). + * + * @return string + */ + public function renderWikitextLink( TitleValue $page, $text = null ) { + if ( $text === null ) { + $text = $this->formatter->getFullText( $page ); + } + + $name = $this->formatter->getFullText( $page ); + + return '[[:' . $name . '|' . wfEscapeWikiText( $text ) . ']]'; + } +} diff --git a/includes/title/MediaWikiTitleCodec.php b/includes/title/MediaWikiTitleCodec.php new file mode 100644 index 00000000..6ca0799c --- /dev/null +++ b/includes/title/MediaWikiTitleCodec.php @@ -0,0 +1,400 @@ +<?php +/** + * A codec for %MediaWiki page titles. + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License along + * with this program; if not, write to the Free Software Foundation, Inc., + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + * http://www.gnu.org/copyleft/gpl.html + * + * @file + * @license GPL 2+ + * @author Daniel Kinzler + */ + +/** + * A codec for %MediaWiki page titles. + * + * @note Normalization and validation is applied while parsing, not when formatting. + * It's possible to construct a TitleValue with an invalid title, and use MediaWikiTitleCodec + * to generate an (invalid) title string from it. TitleValues should be constructed only + * via parseTitle() or from a (semi)trusted source, such as the database. + * + * @see https://www.mediawiki.org/wiki/Requests_for_comment/TitleValue + */ +class MediaWikiTitleCodec implements TitleFormatter, TitleParser { + /** + * @var Language + */ + protected $language; + + /** + * @var GenderCache + */ + protected $genderCache; + + /** + * @var string[] + */ + protected $localInterwikis; + + /** + * @param Language $language The language object to use for localizing namespace names. + * @param GenderCache $genderCache The gender cache for generating gendered namespace names + * @param string[]|string $localInterwikis + */ + public function __construct( Language $language, GenderCache $genderCache, + $localInterwikis = array() + ) { + $this->language = $language; + $this->genderCache = $genderCache; + $this->localInterwikis = (array)$localInterwikis; + } + + /** + * @see TitleFormatter::getNamespaceName() + * + * @param int $namespace + * @param string $text + * + * @throws InvalidArgumentException If the namespace is invalid + * @return string + */ + public function getNamespaceName( $namespace, $text ) { + if ( $this->language->needsGenderDistinction() && + MWNamespace::hasGenderDistinction( $namespace ) + ) { + + //NOTE: we are assuming here that the title text is a user name! + $gender = $this->genderCache->getGenderOf( $text, __METHOD__ ); + $name = $this->language->getGenderNsText( $namespace, $gender ); + } else { + $name = $this->language->getNsText( $namespace ); + } + + if ( $name === false ) { + throw new InvalidArgumentException( 'Unknown namespace ID: ' . $namespace ); + } + + return $name; + } + + /** + * @see TitleFormatter::formatTitle() + * + * @param int|bool $namespace The namespace ID (or false, if the namespace should be ignored) + * @param string $text The page title. Should be valid. Only minimal normalization is applied. + * Underscores will be replaced. + * @param string $fragment The fragment name (may be empty). + * + * @throws InvalidArgumentException If the namespace is invalid + * @return string + */ + public function formatTitle( $namespace, $text, $fragment = '' ) { + if ( $namespace !== false ) { + $namespace = $this->getNamespaceName( $namespace, $text ); + + if ( $namespace !== '' ) { + $text = $namespace . ':' . $text; + } + } + + if ( $fragment !== '' ) { + $text = $text . '#' . $fragment; + } + + $text = str_replace( '_', ' ', $text ); + + return $text; + } + + /** + * Parses the given text and constructs a TitleValue. Normalization + * is applied according to the rules appropriate for the form specified by $form. + * + * @param string $text The text to parse + * @param int $defaultNamespace Namespace to assume per default (usually NS_MAIN) + * + * @throws MalformedTitleException + * @return TitleValue + */ + public function parseTitle( $text, $defaultNamespace ) { + // NOTE: this is an ugly cludge that allows this class to share the + // code for parsing with the old Title class. The parser code should + // be refactored to avoid this. + $parts = $this->splitTitleString( $text, $defaultNamespace ); + + // Interwiki links are not supported by TitleValue + if ( $parts['interwiki'] !== '' ) { + throw new MalformedTitleException( 'Title must not contain an interwiki prefix: ' . $text ); + } + + // Relative fragment links are not supported by TitleValue + if ( $parts['dbkey'] === '' ) { + throw new MalformedTitleException( 'Title must not be empty: ' . $text ); + } + + return new TitleValue( $parts['namespace'], $parts['dbkey'], $parts['fragment'] ); + } + + /** + * @see TitleFormatter::getText() + * + * @param TitleValue $title + * + * @return string $title->getText() + */ + public function getText( TitleValue $title ) { + return $this->formatTitle( false, $title->getText(), '' ); + } + + /** + * @see TitleFormatter::getText() + * + * @param TitleValue $title + * + * @return string + */ + public function getPrefixedText( TitleValue $title ) { + return $this->formatTitle( $title->getNamespace(), $title->getText(), '' ); + } + + /** + * @see TitleFormatter::getText() + * + * @param TitleValue $title + * + * @return string + */ + public function getFullText( TitleValue $title ) { + return $this->formatTitle( $title->getNamespace(), $title->getText(), $title->getFragment() ); + } + + /** + * Normalizes and splits a title string. + * + * This function removes illegal characters, splits off the interwiki and + * namespace prefixes, sets the other forms, and canonicalizes + * everything. + * + * @todo this method is only exposed as a temporary measure to ease refactoring. + * It was copied with minimal changes from Title::secureAndSplit(). + * + * @todo This method should be split up and an appropriate interface + * defined for use by the Title class. + * + * @param string $text + * @param int $defaultNamespace + * + * @throws MalformedTitleException If $text is not a valid title string. + * @return array A mapp with the fields 'interwiki', 'fragment', 'namespace', + * 'user_case_dbkey', and 'dbkey'. + */ + public function splitTitleString( $text, $defaultNamespace = NS_MAIN ) { + $dbkey = str_replace( ' ', '_', $text ); + + # Initialisation + $parts = array( + 'interwiki' => '', + 'local_interwiki' => false, + 'fragment' => '', + 'namespace' => $defaultNamespace, + 'dbkey' => $dbkey, + 'user_case_dbkey' => $dbkey, + ); + + # Strip Unicode bidi override characters. + # Sometimes they slip into cut-n-pasted page titles, where the + # override chars get included in list displays. + $dbkey = preg_replace( '/\xE2\x80[\x8E\x8F\xAA-\xAE]/S', '', $dbkey ); + + # Clean up whitespace + # Note: use of the /u option on preg_replace here will cause + # input with invalid UTF-8 sequences to be nullified out in PHP 5.2.x, + # conveniently disabling them. + $dbkey = preg_replace( + '/[ _\xA0\x{1680}\x{180E}\x{2000}-\x{200A}\x{2028}\x{2029}\x{202F}\x{205F}\x{3000}]+/u', + '_', + $dbkey + ); + $dbkey = trim( $dbkey, '_' ); + + if ( strpos( $dbkey, UTF8_REPLACEMENT ) !== false ) { + # Contained illegal UTF-8 sequences or forbidden Unicode chars. + throw new MalformedTitleException( 'Bad UTF-8 sequences found in title: ' . $text ); + } + + $parts['dbkey'] = $dbkey; + + # Initial colon indicates main namespace rather than specified default + # but should not create invalid {ns,title} pairs such as {0,Project:Foo} + if ( $dbkey !== '' && ':' == $dbkey[0] ) { + $parts['namespace'] = NS_MAIN; + $dbkey = substr( $dbkey, 1 ); # remove the colon but continue processing + $dbkey = trim( $dbkey, '_' ); # remove any subsequent whitespace + } + + if ( $dbkey == '' ) { + throw new MalformedTitleException( 'Empty title: ' . $text ); + } + + # Namespace or interwiki prefix + $prefixRegexp = "/^(.+?)_*:_*(.*)$/S"; + do { + $m = array(); + if ( preg_match( $prefixRegexp, $dbkey, $m ) ) { + $p = $m[1]; + if ( ( $ns = $this->language->getNsIndex( $p ) ) !== false ) { + # Ordinary namespace + $dbkey = $m[2]; + $parts['namespace'] = $ns; + # For Talk:X pages, check if X has a "namespace" prefix + if ( $ns == NS_TALK && preg_match( $prefixRegexp, $dbkey, $x ) ) { + if ( $this->language->getNsIndex( $x[1] ) ) { + # Disallow Talk:File:x type titles... + throw new MalformedTitleException( 'Bad namespace prefix: ' . $text ); + } elseif ( Interwiki::isValidInterwiki( $x[1] ) ) { + //TODO: get rid of global state! + # Disallow Talk:Interwiki:x type titles... + throw new MalformedTitleException( 'Interwiki prefix found in title: ' . $text ); + } + } + } elseif ( Interwiki::isValidInterwiki( $p ) ) { + # Interwiki link + $dbkey = $m[2]; + $parts['interwiki'] = $this->language->lc( $p ); + + # Redundant interwiki prefix to the local wiki + foreach ( $this->localInterwikis as $localIW ) { + if ( 0 == strcasecmp( $parts['interwiki'], $localIW ) ) { + if ( $dbkey == '' ) { + # Empty self-links should point to the Main Page, to ensure + # compatibility with cross-wiki transclusions and the like. + $mainPage = Title::newMainPage(); + return array( + 'interwiki' => $mainPage->getInterwiki(), + 'local_interwiki' => true, + 'fragment' => $mainPage->getFragment(), + 'namespace' => $mainPage->getNamespace(), + 'dbkey' => $mainPage->getDBkey(), + 'user_case_dbkey' => $mainPage->getUserCaseDBKey() + ); + } + $parts['interwiki'] = ''; + # local interwikis should behave like initial-colon links + $parts['local_interwiki'] = true; + + # Do another namespace split... + continue 2; + } + } + + # If there's an initial colon after the interwiki, that also + # resets the default namespace + if ( $dbkey !== '' && $dbkey[0] == ':' ) { + $parts['namespace'] = NS_MAIN; + $dbkey = substr( $dbkey, 1 ); + } + } + # If there's no recognized interwiki or namespace, + # then let the colon expression be part of the title. + } + break; + } while ( true ); + + $fragment = strstr( $dbkey, '#' ); + if ( false !== $fragment ) { + $parts['fragment'] = str_replace( '_', ' ', substr( $fragment, 1 ) ); + $dbkey = substr( $dbkey, 0, strlen( $dbkey ) - strlen( $fragment ) ); + # remove whitespace again: prevents "Foo_bar_#" + # becoming "Foo_bar_" + $dbkey = preg_replace( '/_*$/', '', $dbkey ); + } + + # Reject illegal characters. + $rxTc = Title::getTitleInvalidRegex(); + if ( preg_match( $rxTc, $dbkey ) ) { + throw new MalformedTitleException( 'Illegal characters found in title: ' . $text ); + } + + # Pages with "/./" or "/../" appearing in the URLs will often be un- + # reachable due to the way web browsers deal with 'relative' URLs. + # Also, they conflict with subpage syntax. Forbid them explicitly. + if ( + strpos( $dbkey, '.' ) !== false && + ( + $dbkey === '.' || $dbkey === '..' || + strpos( $dbkey, './' ) === 0 || + strpos( $dbkey, '../' ) === 0 || + strpos( $dbkey, '/./' ) !== false || + strpos( $dbkey, '/../' ) !== false || + substr( $dbkey, -2 ) == '/.' || + substr( $dbkey, -3 ) == '/..' + ) + ) { + throw new MalformedTitleException( 'Bad title: ' . $text ); + } + + # Magic tilde sequences? Nu-uh! + if ( strpos( $dbkey, '~~~' ) !== false ) { + throw new MalformedTitleException( 'Bad title: ' . $text ); + } + + # Limit the size of titles to 255 bytes. This is typically the size of the + # underlying database field. We make an exception for special pages, which + # don't need to be stored in the database, and may edge over 255 bytes due + # to subpage syntax for long titles, e.g. [[Special:Block/Long name]] + if ( + ( $parts['namespace'] != NS_SPECIAL && strlen( $dbkey ) > 255 ) + || strlen( $dbkey ) > 512 + ) { + throw new MalformedTitleException( 'Title too long: ' . substr( $dbkey, 0, 255 ) . '...' ); + } + + # Normally, all wiki links are forced to have an initial capital letter so [[foo]] + # and [[Foo]] point to the same place. Don't force it for interwikis, since the + # other site might be case-sensitive. + $parts['user_case_dbkey'] = $dbkey; + if ( $parts['interwiki'] === '' ) { + $dbkey = Title::capitalize( $dbkey, $parts['namespace'] ); + } + + # Can't make a link to a namespace alone... "empty" local links can only be + # self-links with a fragment identifier. + if ( $dbkey == '' && $parts['interwiki'] === '' ) { + if ( $parts['namespace'] != NS_MAIN ) { + throw new MalformedTitleException( 'Empty title: ' . $text ); + } + } + + // Allow IPv6 usernames to start with '::' by canonicalizing IPv6 titles. + // IP names are not allowed for accounts, and can only be referring to + // edits from the IP. Given '::' abbreviations and caps/lowercaps, + // there are numerous ways to present the same IP. Having sp:contribs scan + // them all is silly and having some show the edits and others not is + // inconsistent. Same for talk/userpages. Keep them normalized instead. + if ( $parts['namespace'] == NS_USER || $parts['namespace'] == NS_USER_TALK ) { + $dbkey = IP::sanitizeIP( $dbkey ); + } + + // Any remaining initial :s are illegal. + if ( $dbkey !== '' && ':' == $dbkey[0] ) { + throw new MalformedTitleException( 'Title must not start with a colon: ' . $text ); + } + + # Fill fields + $parts['dbkey'] = $dbkey; + + return $parts; + } +} diff --git a/includes/title/PageLinkRenderer.php b/includes/title/PageLinkRenderer.php new file mode 100644 index 00000000..fb1096e0 --- /dev/null +++ b/includes/title/PageLinkRenderer.php @@ -0,0 +1,67 @@ +<?php +/** + * Represents a link rendering service for %MediaWiki. + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License along + * with this program; if not, write to the Free Software Foundation, Inc., + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + * http://www.gnu.org/copyleft/gpl.html + * + * @file + * @license GPL 2+ + * @author Daniel Kinzler + */ + +/** + * Represents a link rendering service for %MediaWiki. + * + * This is designed to encapsulate the knowledge about how page titles map to + * URLs, and how links are encoded in a given output format. + * + * @see https://www.mediawiki.org/wiki/Requests_for_comment/TitleValue + */ +interface PageLinkRenderer { + /** + * Returns the URL for the given page. + * + * @todo expand this to cover the functionality of Linker::linkUrl + * + * @param TitleValue $page The link's target + * @param array $params Any additional URL parameters. + * + * @return string + */ + public function getPageUrl( TitleValue $page, $params = array() ); + + /** + * Returns an HTML link to the given page, using the given surface text. + * + * @todo expand this to cover the functionality of Linker::link + * + * @param TitleValue $page The link's target + * @param string $text The link's surface text (will be derived from $page if not given). + * + * @return string + */ + public function renderHtmlLink( TitleValue $page, $text = null ); + + /** + * Returns a wikitext link to the given page, using the given surface text. + * + * @param TitleValue $page The link's target + * @param string $text The link's surface text (will be derived from $page if not given). + * + * @return string + */ + public function renderWikitextLink( TitleValue $page, $text = null ); +} diff --git a/includes/title/TitleFormatter.php b/includes/title/TitleFormatter.php new file mode 100644 index 00000000..7c71ef5e --- /dev/null +++ b/includes/title/TitleFormatter.php @@ -0,0 +1,90 @@ +<?php +/** + * A title formatter service for %MediaWiki. + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License along + * with this program; if not, write to the Free Software Foundation, Inc., + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + * http://www.gnu.org/copyleft/gpl.html + * + * @file + * @license GPL 2+ + * @author Daniel Kinzler + */ + +/** + * A title formatter service for MediaWiki. + * + * This is designed to encapsulate knowledge about conventions for the title + * forms to be used in the database, in urls, in wikitext, etc. + * + * @see https://www.mediawiki.org/wiki/Requests_for_comment/TitleValue + */ +interface TitleFormatter { + /** + * Returns the title formatted for display. + * Per default, this includes the namespace but not the fragment. + * + * @note Normalization is applied if $title is not in TitleValue::TITLE_FORM. + * + * @param int|bool $namespace The namespace ID (or false, if the namespace should be ignored) + * @param string $text The page title + * @param string $fragment The fragment name (may be empty). + * + * @return string + */ + public function formatTitle( $namespace, $text, $fragment = '' ); + + /** + * Returns the title text formatted for display, without namespace of fragment. + * + * @note Only minimal normalization is applied. Consider using TitleValue::getText() directly. + * + * @param TitleValue $title The title to format + * + * @return string + */ + public function getText( TitleValue $title ); + + /** + * Returns the title formatted for display, including the namespace name. + * + * @param TitleValue $title The title to format + * + * @return string + */ + public function getPrefixedText( TitleValue $title ); + + /** + * Returns the title formatted for display, with namespace and fragment. + * + * @param TitleValue $title The title to format + * + * @return string + */ + public function getFullText( TitleValue $title ); + + /** + * Returns the name of the namespace for the given title. + * + * @note This must take into account gender sensitive namespace names. + * @todo Move this to a separate interface + * + * @param int $namespace + * @param string $text + * + * @throws InvalidArgumentException + * @return string + */ + public function getNamespaceName( $namespace, $text ); +} diff --git a/includes/title/TitleParser.php b/includes/title/TitleParser.php new file mode 100644 index 00000000..0635ee86 --- /dev/null +++ b/includes/title/TitleParser.php @@ -0,0 +1,47 @@ +<?php +/** + * A title parser service for %MediaWiki. + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License along + * with this program; if not, write to the Free Software Foundation, Inc., + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + * http://www.gnu.org/copyleft/gpl.html + * + * @file + * @license GPL 2+ + * @author Daniel Kinzler + */ + +/** + * A title parser service for %MediaWiki. + * + * This is designed to encapsulate knowledge about conventions for the title + * forms to be used in the database, in urls, in wikitext, etc. + * + * @see https://www.mediawiki.org/wiki/Requests_for_comment/TitleValue + */ +interface TitleParser { + /** + * Parses the given text and constructs a TitleValue. Normalization + * is applied according to the rules appropriate for the form specified by $form. + * + * @note this only parses local page links, interwiki-prefixes etc. are not considered! + * + * @param string $text The text to parse + * @param int $defaultNamespace Namespace to assume per default (usually NS_MAIN) + * + * @throws MalformedTitleException If the text is not a valid representation of a page title. + * @return TitleValue + */ + public function parseTitle( $text, $defaultNamespace ); +} diff --git a/includes/title/TitleValue.php b/includes/title/TitleValue.php new file mode 100644 index 00000000..402247c2 --- /dev/null +++ b/includes/title/TitleValue.php @@ -0,0 +1,161 @@ +<?php +/** + * Representation of a page title within %MediaWiki. + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License along + * with this program; if not, write to the Free Software Foundation, Inc., + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + * http://www.gnu.org/copyleft/gpl.html + * + * @file + * @license GPL 2+ + * @author Daniel Kinzler + */ + +/** + * Represents a page (or page fragment) title within %MediaWiki. + * + * @note In contrast to Title, this is designed to be a plain value object. That is, + * it is immutable, does not use global state, and causes no side effects. + * + * @note TitleValue represents the title of a local page (or fragment of a page). + * It does not represent a link, and does not support interwiki prefixes etc. + * + * @see https://www.mediawiki.org/wiki/Requests_for_comment/TitleValue + */ +class TitleValue { + /** + * @var int + */ + protected $namespace; + + /** + * @var string + */ + protected $dbkey; + + /** + * @var string + */ + protected $fragment; + + /** + * Constructs a TitleValue. + * + * @note TitleValue expects a valid DB key; typically, a TitleValue is constructed either + * from a database entry, or by a TitleParser. We could apply "some" normalization here, + * such as substituting spaces by underscores, but that would encourage the use of + * un-normalized text when constructing TitleValues. For constructing a TitleValue from + * user input or external sources, use a TitleParser. + * + * @param int $namespace The namespace ID. This is not validated. + * @param string $dbkey The page title in valid DBkey form. No normalization is applied. + * @param string $fragment The fragment title. Use '' to represent the whole page. + * No validation or normalization is applied. + * + * @throws InvalidArgumentException + */ + public function __construct( $namespace, $dbkey, $fragment = '' ) { + if ( !is_int( $namespace ) ) { + throw new InvalidArgumentException( '$namespace must be an integer' ); + } + + if ( !is_string( $dbkey ) ) { + throw new InvalidArgumentException( '$dbkey must be a string' ); + } + + // Sanity check, no full validation or normalization applied here! + if ( preg_match( '/^_|[ \r\n\t]|_$/', $dbkey ) ) { + throw new InvalidArgumentException( '$dbkey must be a valid DB key: ' . $dbkey ); + } + + if ( !is_string( $fragment ) ) { + throw new InvalidArgumentException( '$fragment must be a string' ); + } + + if ( $dbkey === '' ) { + throw new InvalidArgumentException( '$dbkey must not be empty' ); + } + + $this->namespace = $namespace; + $this->dbkey = $dbkey; + $this->fragment = $fragment; + } + + /** + * @return int + */ + public function getNamespace() { + return $this->namespace; + } + + /** + * @return string + */ + public function getFragment() { + return $this->fragment; + } + + /** + * Returns the title's DB key, as supplied to the constructor, + * without namespace prefix or fragment. + * + * @return string + */ + public function getDBkey() { + return $this->dbkey; + } + + /** + * Returns the title in text form, + * without namespace prefix or fragment. + * + * This is computed from the DB key by replacing any underscores with spaces. + * + * @note To get a title string that includes the namespace and/or fragment, + * use a TitleFormatter. + * + * @return string + */ + public function getText() { + return str_replace( '_', ' ', $this->getDBkey() ); + } + + /** + * Creates a new TitleValue for a different fragment of the same page. + * + * @param string $fragment The fragment name, or "" for the entire page. + * + * @return TitleValue + */ + public function createFragmentTitle( $fragment ) { + return new TitleValue( $this->namespace, $this->dbkey, $fragment ); + } + + /** + * Returns a string representation of the title, for logging. This is purely informative + * and must not be used programmatically. Use the appropriate TitleFormatter to generate + * the correct string representation for a given use. + * + * @return string + */ + public function __toString() { + $name = $this->namespace . ':' . $this->dbkey; + + if ( $this->fragment !== '' ) { + $name .= '#' . $this->fragment; + } + + return $name; + } +} |