Manual:Title.php

From MediaWiki.org
Jump to: navigation, search


The MediaWiki software's Title class represents article titles, which are used for many purposes, including:

  • as the human-readable text title of the article
  • in the URL used to access the article
  • the wikitext link to the article
  • the key into the article database

The class is instantiated with one of these formats. Once instantiated, the title can be retrieved in other formats or queried for its attributes. Title is intended to be an immutable "value" class, so there are no mutator functions.

To instantiate Title, call one of the static factory methods:

  • Title::newFromDBKey( $key )
  • Title::newFromID( ($id, $flags=0) )
  • Title::newFromText( ($text, $defaultNamespace=NS_MAIN) )
  • Title::newFromURL( $url ) ("THIS IS NOT THE FUNCTION YOU WANT. Use Title::newFromText().")
  • Title::newFromIDs( $ids ) (returns an array of Titles)
  • Title::newFromRedirect ($text)
  • Title::makeTitleSafe ($ns, $title, $fragment= , $interwiki= ) Create a new Title from a namespace index and a DB key. Returns null on an error.
  • newFromRedirectArray ($text)
  • newFromRedirectRecurse ($text)
  • newFromRow ($row)
  • newMainPage ()

Once instantiated, the other non-static accessor methods can be used, such as getText(), getDBKey(), getNamespace(), etc.

If you have a Title object, you can get a:

  • Article object, using Article::newFromTitle ( $title, IContextSource $context )
  • WikiPage object, using WikiPage::factory ( Title $title )

Title structure[edit | edit source]

A title consists of an optional Interwiki prefix (such as "mw:" for pages from mediawiki.org or "w:" for Wikipedia articles), followed by an optional namespace (such as "Manual:"), followed by the article name.

prefix: namespace: article name
optional optional required

Interwiki prefixes and namespaces[edit | edit source]

Interwiki prefixes and namespaces follow the same content rules:

  • they must start with a letter
  • they must end with a colon
  • they may only contain digits, letters, the space character and the underscore character
  • spaces and underscores may be used interchangeably
  • they are case-insensitive

Interwiki prefixes and namespaces are only recognized if they are known to a given installation of MediaWiki, either by default or through configuration.

For example: On this wiki, "w:Name" is a link to the article "Name" on Wikipedia, because "w" is recognized as one of the allowable interwiki prefixes. The title "talk:Name" is a link to the article "name" in the "talk" namespace of the current wiki, because "talk" is a recognized namespace. Both may be present, and if so, the interwiki must come first, for example, "w:talk:name".

If a title begins with a colon as its first character, no prefixes are scanned for, and the colon is removed before the title is processed. Because of this rule, it is possible to have articles with colons in their names. "E. Coli 0157:H7" is a valid title, as is "Commandos: Behind Enemy Lines", because "E. Coli 0157" and "Commandos" are not valid interwikis or namespaces.

Article name[edit | edit source]

In the article name spaces and underscores are treated as equivalent and each is converted to the other in the appropriate context (underscore in URL and database keys, spaces in plain text). "Extended" characters in the 0x80..0xFF range are allowed in all places, and are valid characters. They are encoded in URLs. Extended characters are not urlencoded when used as text or database keys. Other characters may be ASCII letters, digits, hyphen, comma, period, apostrophe, parentheses and colon. No other ASCII characters are allowed, and will be deleted if found (they will probably cause a browser to misinterpret the URL).

Canonical forms[edit | edit source]

The canonical form of a title will always be returned by the object. In this form, the first (and only the first) character of the namespace and title will be uppercase; the rest of the namespace will be lowercase, while the rest of the title will be left as is.

The text form will use spaces, the URL and DBkey forms will use underscores. Interwiki prefixes are all lowercase. The namespace will use underscores when returned alone; it will use spaces only when attached to the text title.


getArticleID() needs some explanation: for "internal" articles, it should return the "page_id" field if the article exists, else it returns 0. For all external articles it returns 0. All of the IDs for all instances of Title created during a request are cached, so they can be looked up quickly while rendering wikitext with lots of internal links.

Example[edit | edit source]

To check and see if a given page already exists:

$titleObject = Title::newFromText( 'Talk:Your desired title here' );
if ( !$titleObject->exists() ) echo "There is no page with that name.";

Create a new Title from text, such as what one would find in a link. Decodes any HTML entities in the text. Spaces, prefixes, and an initial ':' indicating the main namespace are accepted. Note that if the page does not exist, this will not create it. For that, see Manual:Article.php.

Functions[edit | edit source]

Many of these functions are used by Manual:CoreParserFunctions.php to generate magic words.

getArticleID()[edit | edit source]

Get the article ID for this Title from the link cache, adding it if necessary

getBaseText()[edit | edit source]

Get the base page name, i.e. the leftmost part excluding namespace and before any slashes, without converting spaces to underscores. See magic words {{BASEPAGENAME}} and {{BASEPAGENAMEE}}.

getText()[edit | edit source]

Gets the text form (spaces not underscores) of the main part, i.e. the title excluding namespace, but including slashes and everything after. See magic word {{PAGENAME}}.

getDBKey()[edit | edit source]

Get the main part (i.e. the title excluding namespace) with underscores.

getPrefixedDBKey()[edit | edit source]

Get the prefixed database key form with underscores.

getFragment()[edit | edit source]

Get the Title fragment (i.e. the bit after the #) in text form.

getFullText()[edit | edit source]

Get the prefixed title with spaces, plus any fragment (part beginning with '#').

getPartialURL()[edit | edit source]

Get the URL-encoded form of the main part. See magic word {{PAGENAMEE}}.

getFullURL()[edit | edit source]

Get a real URL referring to this title, with interwiki link and fragment.

getLocalURL()[edit | edit source]

Get a URL with no fragment or server name.

getPrefixedText()[edit | edit source]

Get the prefixed title with spaces. This is the form usually used for display. See magic word {{FULLPAGENAME}}.

getPrefixedUrl()[edit | edit source]

Get a URL-encoded title (not an actual URL) including interwiki. See magic word {{FULLPAGENAMEE}}.

getSubjectNsText()[edit | edit source]

Get the namespace text of the subject (rather than talk) page. See magic words {{SUBJECTSPACE}} and {{SUBJECTSPACEE}}.

getSubjectPage()[edit | edit source]

Get a title object associated with the subject page of this talk page. See magic word {{SUBJECTPAGENAME}}.

getSubpageText()[edit | edit source]

Get the lowest-level subpage name, i.e. the rightmost part after any slashes. See magic word {{SUBPAGENAME}}.

getSubpageUrlForm()[edit | edit source]

Get a URL-encoded form of the subpage text. See magic word {{SUBPAGENAMEE}}.

getTalkNsText()[edit | edit source]

Get the namespace text of the talk page. See magic word {{TALKSPACE}} and {{TALKSPACEE}}.

getTalkPage()[edit | edit source]

Get a Title object associated with the talk page of this article. See {{TALKPAGENAME}} and {{TALKPAGENAMEE}}.

getNamespace()[edit | edit source]

Get the namespace index. See {{NAMESPACENUMBER}}.

See also[edit | edit source]

Language: English  • 日本語 • português do Brasil