User:DKinzler (WMF)/Title and page

Overview of classes representing titles, pages and links in MediaWiki.

LinkTarget

A LinkTarget represents the target of a wikitext link. There are various kinds of link targets:

• links to proper wiki pages
• links to special pages or magic namespaces (e.g. Media)
• interwiki links to pages on other sites
• links to sections of pages
• relative links to subpages
• relative links to sections on the same page

These cannot be distinguished using the type system, but only by inspecting the properties of the LinkTarget.

The value object implementation of LinkTarget is TitleValue. Title implements LinkTarget for backwards-compatibility.

Note: conceptually, LinkTarget is strongly connected to the parsing and rendering of wikitext links. It is distinct from the Page types below, which represent locations and resources on the site.

PageReference

A PageReference represents a page in a wiki that can be visited and link to. Example include editable wiki pages and special pages.

The default value object implementation of PageReference is PageReferenceValue. Title implements PageReference for backwards-compatibility.

Note: conceptually, every PageReference is a link target. However, they are presently not compatible types. One reason for this is that PageReferences are wiki-aware, while LinkTargets are not. Also, most properties of LinkTarget are meaningless for a PageReference.

PageIdentity

A PageIdentity represents a wiki page that could be edited or created. This excludes special pages.

Every PageIdentity is a PageReference, but not every PageReference can be a PageIdentity: in particular, PageReferences that represent special pages fall outside of the scope of PageIdentity.

The default value object implementation of PageIdentity is PageIdentityValue. Title implements PageIdentity for backwards-compatibility.

Note: for backwards compatibility reasons, PageIdentity objects may be "improper", that is, they may represent things that are not wiki page that could be edited or created. This would be the case for Title objects that represent special pages or interwiki links or such, since Title implements PageIdentity. This can be checked using the canExist() method: if it returns false, the PageIdentity is improper. To provide a way to require a "safe" PageIdentity using the type system, the ProperPageIdentity interface is provided, which guarantees that the PageIdentity really represents wiki page that could be edited or created (rather than a e.g. special or an interwiki link). In the future, Title will be removed or at least will no longer implement the PageIdentity interface. At that point, PageIdentity will gain full guarantees, and ProperPageIdenity will become an alias for PageIdentity.

PageRecord

A PageRecord represents an editable wiki page that currently exists. This excludes non-existing pages as well as special pages.

Every PageRecord is a PageIdentity (and thus also a PageReference), but not every PageIdentity can be a PageRecord: in particular, PageIdentities that represent a non-existing page fall outside of the scope of PageRecord.

The default value object implementation of PageRecord is PageRecordValue. WikiPage implements PageRecord for backwards-compatibility.

Note: for backwards compatibility reasons, PageRecord objects may be non-existing. This would be the case for WikiPage objects that represent a non-existing page, since WikiPage implements PageRecord. This can be checked using the exists() method: if it returns false, the PageRecord is non-existing. To provide a way to require a "safe" PageRecord using the type system, the ExistingPageRecord interface is provided, which guarantees that the PageRecord really represents wiki page exists. In the future, WikiPage will be removed or at least will no longer implement the PageRecord interface. At that point, PageRecord will gain full guarantees, and ExistingPageRecord will become an alias for PageRecord.

Title

The Title class is a large legacy class with somewhat unclear semantics. It may represent any kind of wikitext link target, or it may represent a page on the wiki. It may also represent a malformed link target. Traditionally, functionality related to the page, such as protecting or renaming, was implemented in Title. Much of this functionality has been extracted into service objects now.

The usage of the Title type is discouraged in new code, especially in public method signatures that extensions may bind to.

For reasons of backwards compatibility, Title implements PageIdentity as well as LinkTarget, so it can be used directly with new code that requires the new interfaces in its method signatures.

WikiPage

The WikiPage class is a large legacy class that encapsulates functionality for interacting with the content of a page, such as editing.

Usage of WikiPage should be avoided in new code if possible. The relevant functionality is being extracted into service objects.

For reasons of backwards compatibility, WikiPage implements PageRecord, so it can be used directly with new code that requires the new interfaces in its method signatures.