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, which cannot 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.