/**
* Create a new Title from a prefixed DB key
*
- * @param $key String The database key, which has underscores
+ * @param $key String the database key, which has underscores
* instead of spaces, possibly including namespace and
* interwiki prefixes
- * @return Title the new object, or NULL on an error
+ * @return Title, or NULL on an error
*/
public static function newFromDBkey( $key ) {
$t = new Title();
* Create a new Title from text, such as what one would find in a link. De-
* codes any HTML entities in the text.
*
- * @param $text String The link text; spaces, prefixes, and an
+ * @param $text String the link text; spaces, prefixes, and an
* initial ':' indicating the main namespace are accepted.
- * @param $defaultNamespace int The namespace to use if none is speci-
+ * @param $defaultNamespace Int the namespace to use if none is speci-
* fied by a prefix. If you want to force a specific namespace even if
* $text might begin with a namespace prefix, use makeTitle() or
* makeTitleSafe().
- * @return Title The new object, or null on an error.
+ * @return Title, or null on an error.
*/
public static function newFromText( $text, $defaultNamespace = NS_MAIN ) {
if ( is_object( $text ) ) {
return Title::$titleCache[$text];
}
- /**
- * Convert things like é ā or 〗 into normalized (bug 14952) text
- */
+ # Convert things like é ā or 〗 into normalized (bug 14952) text
$filteredText = Sanitizer::decodeCharReferencesAndNormalize( $text );
$t = new Title();
*
* @param $ns Int the namespace of the article
* @param $title String the unprefixed database key form
- * @param $fragment String The link fragment (after the "#")
- * @param $interwiki String The interwiki prefix
+ * @param $fragment String the link fragment (after the "#")
+ * @param $interwiki String the interwiki prefix
* @return Title the new object
*/
public static function &makeTitle( $ns, $title, $fragment = '', $interwiki = '' ) {
* than makeTitle() but safer for user-provided data.
*
* @param $ns Int the namespace of the article
- * @param $title String the database key form
- * @param $fragment String The link fragment (after the "#")
- * @param $interwiki String The interwiki prefix
+ * @param $title String database key form
+ * @param $fragment String the link fragment (after the "#")
+ * @param $interwiki String interwiki prefix
* @return Title the new object, or NULL on an error
*/
public static function makeTitleSafe( $ns, $title, $fragment = '', $interwiki = '' ) {
* in order to provide (hopefully) the Title of the final destination instead of another redirect
*
* @param $text String Text with possible redirect
- * @return Title The corresponding Title
+ * @return Title
*/
public static function newFromRedirectRecurse( $text ) {
$titles = self::newFromRedirectArray( $text );
* Do not call this function directly, use one of the newFromRedirect* functions above
*
* @param $text String Text with possible redirect
- * @return Title The corresponding Title
+ * @return Title
*/
protected static function newFromRedirectInternal( $text ) {
$redir = MagicWord::get( 'redirect' );
* Get the prefixed DB key associated with an ID
*
* @param $id Int the page_id of the article
- * @return Title an object representing the article, or NULL
- * if no such article was found
+ * @return Title an object representing the article, or NULL if no such article was found
*/
public static function nameOf( $id ) {
$dbr = wfGetDB( DB_SLAVE );
*
* @param $ns Int a namespace index
* @param $title String text-form main part
- * @return String a stripped-down title string ready for the
- * search index
+ * @return String a stripped-down title string ready for the search index
*/
public static function indexTitle( $ns, $title ) {
global $wgContLang;
* Determine whether the object refers to a page within
* this project.
*
- * @return Bool TRUE if this is an in-project interwiki link
- * or a wikilink, FALSE otherwise
+ * @return Bool TRUE if this is an in-project interwiki link or a wikilink, FALSE otherwise
*/
public function isLocal() {
if ( $this->mInterwiki != '' ) {
}
/**
- * Returns the DB name of the distant wiki
- * which owns the object.
+ * Returns the DB name of the distant wiki which owns the object.
*
* @return String the DB name
*/
public function getDBkey() { return $this->mDbkeyform; }
/**
- * Get the namespace index, i.e.\ one of the NS_xxxx constants.
+ * Get the namespace index, i.e. one of the NS_xxxx constants.
*
* @return Integer: Namespace index
*/
* Get the prefixed title with spaces, plus any fragment
* (part beginning with '#')
*
- * @return String the prefixed title, with spaces and
- * the fragment, including '#'
+ * @return String the prefixed title, with spaces and the fragment, including '#'
*/
public function getFullText() {
$text = $this->getPrefixedText();
*
* @param $query Array of Strings An associative array of key => value pairs for the
* query string. Keys and values will be escaped.
- * @param $variant String Language variant of URL (for sr, zh..). Ignored
+ * @param $variant String language variant of URL (for sr, zh..). Ignored
* for external links. Default is "false" (same variant as current page,
* for anonymous users).
* @return String the URL
* @param $user User to check
* @param $doExpensiveQueries Bool Set this to false to avoid doing unnecessary queries.
* @param $ignoreErrors Array of Strings Set this to a list of message keys whose corresponding errors may be ignored.
- * @return Array of arrays of the arguments to wfMsg to explain permissions problems.
+ * @return Array of arguments to wfMsg to explain permissions problems.
*/
public function getUserPermissionsErrors( $action, $user, $doExpensiveQueries = true, $ignoreErrors = array() ) {
$errors = $this->getUserPermissionsErrorsInternal( $action, $user, $doExpensiveQueries );
* Check restrictions on cascading pages.
*
* @param $action String the action to check
- * @param $user User user to check
+ * @param $user User to check
* @param $errors Array list of current errors
* @param $doExpensiveQueries Boolean whether or not to perform expensive queries
* @param $short Boolean short circuit on first error
* Check action permissions not already checked in checkQuickPermissions
*
* @param $action String the action to check
- * @param $user User user to check
+ * @param $user User to check
* @param $errors Array list of current errors
* @param $doExpensiveQueries Boolean whether or not to perform expensive queries
* @param $short Boolean short circuit on first error
* Check that the user isn't blocked from editting.
*
* @param $action String the action to check
- * @param $user User user to check
+ * @param $user User to check
* @param $errors Array list of current errors
* @param $doExpensiveQueries Boolean whether or not to perform expensive queries
* @param $short Boolean short circuit on first error
} else {
global $wgWhitelistRead;
- /**
- * Always grant access to the login page.
- * Even anons need to be able to log in.
- */
+ # Always grant access to the login page.
+ # Even anons need to be able to log in.
if ( $this->isSpecial( 'Userlogin' ) || $this->isSpecial( 'Resetpass' ) ) {
return true;
}
- /**
- * Bail out if there isn't whitelist
- */
+ # Bail out if there isn't whitelist
if ( !is_array( $wgWhitelistRead ) ) {
return false;
}
- /**
- * Check for explicit whitelisting
- */
+ # Check for explicit whitelisting
$name = $this->getPrefixedText();
$dbName = $this->getPrefixedDBKey();
// Check with and without underscores
if ( in_array( $name, $wgWhitelistRead, true ) || in_array( $dbName, $wgWhitelistRead, true ) )
return true;
- /**
- * Old settings might have the title prefixed with
- * a colon for main-namespace pages
- */
+ # Old settings might have the title prefixed with
+ # a colon for main-namespace pages
if ( $this->getNamespace() == NS_MAIN ) {
if ( in_array( ':' . $name, $wgWhitelistRead ) ) {
return true;
}
}
- /**
- * If it's a special page, ditch the subpage bit
- * and check again
- */
+ # If it's a special page, ditch the subpage bit and check again
if ( $this->getNamespace() == NS_SPECIAL ) {
$name = $this->getDBkey();
list( $name, /* $subpage */ ) = SpecialPage::resolveAliasWithSubpage( $name );
* Is this a *valid* .css or .js subpage of a user page?
*
* @return Bool
- * @deprecated
+ * @deprecated @since 1.17
*/
public function isValidCssJsSubpage() {
return $this->isCssJsSubpage();
*
* @param $getPages Bool Whether or not to retrieve the actual pages
* that the restrictions have come from.
- * @return Mixed Array of the Title
- * objects of the pages from which cascading restrictions have come,
- * false for none, or true if such restrictions exist, but $getPages was not set.
- * The restriction array is an array of each type, each of which contains a
- * array of unique groups.
+ * @return Mixed Array of Title objects of the pages from which cascading restrictions
+ * have come, false for none, or true if such restrictions exist, but $getPages
+ * was not set. The restriction array is an array of each type, each of which
+ * contains a array of unique groups.
*/
public function getCascadeProtectionSources( $getPages = true ) {
$pagerestrictions = array();
* Loads a string into mRestrictions array
*
* @param $res Resource restrictions as an SQL result.
- * @param $oldFashionedRestrictions string comma-separated list of page
+ * @param $oldFashionedRestrictions String comma-separated list of page
* restrictions from page table (pre 1.10)
*/
private function loadRestrictionsFromResultWrapper( $res, $oldFashionedRestrictions = null ) {
$now = wfTimestampNow();
$purgeExpired = false;
+ # Cycle through all the restrictions.
foreach ( $rows as $row ) {
- # Cycle through all the restrictions.
// Don't take care of restrictions types that aren't allowed
-
if ( !in_array( $row->pr_type, $restrictionTypes ) )
continue;
/**
* Load restrictions from the page_restrictions table
*
- * @param $oldFashionedRestrictions string comma-separated list of page
+ * @param $oldFashionedRestrictions String comma-separated list of page
* restrictions from page table (pre 1.10)
*/
public function loadRestrictions( $oldFashionedRestrictions = null ) {
/**
* Get the expiry time for the restriction against a given action
*
- * @return 14-char timestamp, or 'infinity' if the page is protected forever
+ * @return String|Bool 14-char timestamp, or 'infinity' if the page is protected forever
* or not protected at all, or false if the action is not recognised.
*/
public function getRestrictionExpiry( $action ) {
* Note that this doesn't pick up many things that could be wrong with titles, but that
* replacing this regex with something valid will make many titles valid.
*
- * @return string regex string
+ * @return String regex string
*/
static function getTitleInvalidRegex() {
static $rxTc = false;
/**
* Capitalize a text string for a title if it belongs to a namespace that capitalizes
*
- * @param $text string containing title to capitalize
+ * @param $text String containing title to capitalize
* @param $ns int namespace index, defaults to NS_MAIN
* @return String containing capitalized title
*/
# 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, '_' );
# For Talk:X pages, check if X has a "namespace" prefix
if ( $ns == NS_TALK && preg_match( $prefixRegexp, $dbkey, $x ) ) {
if ( $wgContLang->getNsIndex( $x[1] ) ) {
- return false; # Disallow Talk:File:x type titles...
+ # Disallow Talk:File:x type titles...
+ return false;
} else if ( Interwiki::isValidInterwiki( $x[1] ) ) {
- return false; # Disallow Talk:Interwiki:x type titles...
+ # Disallow Talk:Interwiki:x type titles...
+ return false;
}
}
} elseif ( Interwiki::isValidInterwiki( $p ) ) {
} while ( true );
# We already know that some pages won't be in the database!
- #
if ( $this->mInterwiki != '' || NS_SPECIAL == $this->mNamespace ) {
$this->mArticleID = 0;
}
}
# Reject illegal characters.
- #
if ( preg_match( $rxTc, $dbkey ) ) {
return false;
}
- /**
- * 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.
- */
+ # 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 ||
return false;
}
- /**
- * Magic tilde sequences? Nu-uh!
- */
+ # Magic tilde sequences? Nu-uh!
if ( strpos( $dbkey, '~~~' ) !== false ) {
return false;
}
- /**
- * 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]]
- */
+ # 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 ( ( $this->mNamespace != NS_SPECIAL && strlen( $dbkey ) > 255 ) ||
strlen( $dbkey ) > 512 )
{
return false;
}
- /**
- * 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.
- */
+ # 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.
$this->mUserCaseDBKey = $dbkey;
if ( $this->mInterwiki == '' ) {
$dbkey = self::capitalize( $dbkey, $this->mNamespace );
}
- /**
- * Can't make a link to a namespace alone...
- * "empty" local links can only be self-links
- * with a fragment identifier.
- */
- if ( $dbkey == '' &&
- $this->mInterwiki == '' &&
- $this->mNamespace != NS_MAIN ) {
+ # Can't make a link to a namespace alone... "empty" local links can only be
+ # self-links with a fragment identifier.
+ if ( $dbkey == '' && $this->mInterwiki == '' && $this->mNamespace != NS_MAIN ) {
return false;
}
+
// 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.
- $dbkey = ( $this->mNamespace == NS_USER || $this->mNamespace == NS_USER_TALK ) ?
- IP::sanitizeIP( $dbkey ) : $dbkey;
+ $dbkey = ( $this->mNamespace == NS_USER || $this->mNamespace == NS_USER_TALK )
+ ? IP::sanitizeIP( $dbkey )
+ : $dbkey;
+
// Any remaining initial :s are illegal.
if ( $dbkey !== '' && ':' == $dbkey { 0 } ) {
return false;
* @param $nt Title the new title
* @param $auth Bool indicates whether $wgUser's permissions
* should be checked
- * @param $reason String The reason for the move
+ * @param $reason String the reason for the move
* @param $createRedirect Bool Whether to create a redirect from the old title to the new title.
* Ignored if the user doesn't have the suppressredirect right.
* @return Mixed true on success, getUserPermissionsErrors()-like array on failure
return $err;
}
- // If it is a file, move it first. It is done before all other moving stuff is done because it's hard to revert
+ // If it is a file, move it first. It is done before all other moving stuff is
+ // done because it's hard to revert
$dbw = wfGetDB( DB_MASTER );
if ( $this->getNamespace() == NS_FILE ) {
$file = wfLocalFile( $this );
* Move page to a title which is either a redirect to the
* source page or nonexistent
*
- * @param $nt Title the page to move to, which should
- * be a redirect or nonexistent
+ * @param $nt Title the page to move to, which should be a redirect or nonexistent
* @param $reason String The reason for the move
- * @param $createRedirect Bool Whether to leave a
- * redirect at the old title. Ignored if the user doesn't
- * have the suppressredirect right
+ * @param $createRedirect Bool Whether to leave a redirect at the old title. Ignored
+ * if the user doesn't have the suppressredirect right
*/
private function moveToInternal( &$nt, $reason = '', $createRedirect = true ) {
global $wgUser, $wgContLang;
* @param $nt Title Move target
* @param $auth bool Whether $wgUser's permissions should be checked
* @param $reason string The reason for the move
- * @param $createRedirect bool Whether to create redirects from the old subpages to the new ones
- * Ignored if the user doesn't have the 'suppressredirect' right
+ * @param $createRedirect bool Whether to create redirects from the old subpages to
+ * the new ones Ignored if the user doesn't have the 'suppressredirect' right
* @return mixed array with old page titles as keys, and strings (new page titles) or
- * arrays (errors) as values, or an error array with numeric indices if no pages were moved
+ * arrays (errors) as values, or an error array with numeric indices if no pages
+ * were moved
*/
public function moveSubpages( $nt, $auth = true, $reason = '', $createRedirect = true ) {
global $wgMaximumMovedPages;
* - Selects for update, so don't call it unless you mean business
*
* @param $nt Title the new title to check
- * @return Bool TRUE or FALSE
+ * @return Bool
*/
public function isValidMoveTarget( $nt ) {
# Is it an existing file?
* categories' names.
*
* @return Array of parents in the form:
- * $parent => $currentarticle
+ * $parent => $currentarticle
*/
public function getParentCategories() {
global $wgContLang;
* Get an associative array for selecting this title from
* the "page" table
*
- * @return Array Selection array
+ * @return Array suitable for the $where parameter of DB::select()
*/
public function pageCond() {
if ( $this->mArticleID > 0 ) {
*
* @param $revId Int Revision ID. Get the revision that was before this one.
* @param $flags Int Title::GAID_FOR_UPDATE
- * @return \twotypes{\int,\bool} Old revision ID, or FALSE if none exists
+ * @return Int|Bool Old revision ID, or FALSE if none exists
*/
public function getPreviousRevisionID( $revId, $flags = 0 ) {
$db = ( $flags & self::GAID_FOR_UPDATE ) ? wfGetDB( DB_MASTER ) : wfGetDB( DB_SLAVE );
*
* @param $revId Int Revision ID. Get the revision that was after this one.
* @param $flags Int Title::GAID_FOR_UPDATE
- * @return \twotypes{\int,\bool} Next revision ID, or FALSE if none exists
+ * @return Int|Bool Next revision ID, or FALSE if none exists
*/
public function getNextRevisionID( $revId, $flags = 0 ) {
$db = ( $flags & self::GAID_FOR_UPDATE ) ? wfGetDB( DB_MASTER ) : wfGetDB( DB_SLAVE );
* Get the first revision of the page
*
* @param $flags Int Title::GAID_FOR_UPDATE
- * @return Revision (or NULL if page doesn't exist)
+ * @return Revision|Null if page doesn't exist
*/
public function getFirstRevision( $flags = 0 ) {
$db = ( $flags & self::GAID_FOR_UPDATE ) ? wfGetDB( DB_MASTER ) : wfGetDB( DB_SLAVE );
* Compare with another title.
*
* @param $title Title
- * @return Bool TRUE or FALSE
+ * @return Bool
*/
public function equals( Title $title ) {
// Note: === is necessary for proper matching of number-like titles.
/**
* Return a string representation of this title
*
- * @return String String representation of this title
+ * @return String representation of this title
*/
public function __toString() {
return $this->getPrefixedText();
switch( $this->mNamespace ) {
case NS_MEDIA:
case NS_FILE:
- return (bool)wfFindFile( $this ); // file exists, possibly in a foreign repo
+ // file exists, possibly in a foreign repo
+ return (bool)wfFindFile( $this );
case NS_SPECIAL:
- return SpecialPage::exists( $this->getDBkey() ); // valid special page
+ // valid special page
+ return SpecialPage::exists( $this->getDBkey() );
case NS_MAIN:
- return $this->mDbkeyform == ''; // selflink, possibly with fragment
+ // selflink, possibly with fragment
+ return $this->mDbkeyform == '';
case NS_MEDIAWIKI:
// If the page is form Mediawiki:message/lang, calling wfMsgWeirdKey causes
// the full l10n of that language to be loaded. That takes much memory and
// isn't needed. So we strip the language part away.
list( $basename, /* rest */ ) = explode( '/', $this->mDbkeyform, 2 );
- return (bool)wfMsgWeirdKey( $basename ); // known system message
+ // known system message
+ return (bool)wfMsgWeirdKey( $basename );
default:
return false;
}
* Get the last touched timestamp
*
* @param $db DatabaseBase: optional db
- * @return String Last touched timestamp
+ * @return String last-touched timestamp
*/
public function getTouched( $db = null ) {
$db = isset( $db ) ? $db : wfGetDB( DB_SLAVE );
* Get the timestamp when this page was updated since the user last saw it.
*
* @param $user User
- * @return Mixed: string/null
+ * @return String|Null
*/
public function getNotificationTimestamp( $user = null ) {
global $wgUser, $wgShowUpdatedMarker;
}
/**
- * If the Title refers to a special page alias which is not the local default,
+ * If the Title refers to a special page alias which is not the local default, resolve
+ * the alias, and localise the name as necessary. Otherwise, return $this
*
- * @return Title A new Title which points to the local default.
- * Otherwise, returns $this.
+ * @return Title
*/
public function fixSpecialName() {
if ( $this->getNamespace() == NS_SPECIAL ) {
/**
* Get all extant redirects to this Title
*
- * @param $ns Int|Null Single namespace to consider;
- * NULL to consider all namespaces
+ * @param $ns Int|Null Single namespace to consider; NULL to consider all namespaces
* @return Array of Title redirects to this title
*/
public function getRedirectsHere( $ns = null ) {
}
/**
- * Whether the magic words __INDEX__ and __NOINDEX__ function for
- * this page.
+ * Whether the magic words __INDEX__ and __NOINDEX__ function for this page.
*
* @return Boolean
*/