MediaWiki  master
Page\PageIdentity Interface Reference

Interface for objects (potentially) representing an editable wiki page. More...

Inheritance diagram for Page\PageIdentity:
Collaboration diagram for Page\PageIdentity:

Public Member Functions

 __toString ()
 Returns an informative human readable representation of the page identity, for use in logging and debugging. More...
 
 canExist ()
 Checks whether this PageIdentity represents a "proper" page, meaning that it could exist as an editable page on the wiki. More...
 
 exists ()
 Checks if the page currently exists. More...
 
 getDBkey ()
 Get the page title in DB key form. More...
 
 getId ( $wikiId=self::LOCAL)
 Returns the page ID. More...
 
 getNamespace ()
 Returns the page's namespace number. More...
 
 getWikiId ()
 Get the ID of the wiki this page belongs to. More...
 
 isSamePageAs (PageIdentity $other)
 Checks whether the given PageIdentity refers to the same page as this PageIdentity. More...
 
- Public Member Functions inherited from MediaWiki\DAO\WikiAwareEntity
 assertWiki ( $wikiId)
 Throws if $wikiId is different from the return value of getWikiId(). More...
 

Detailed Description

Interface for objects (potentially) representing an editable wiki page.

The identity of any PageIdentity object is defined by the namespace, the dbkey, and the wiki ID. The page ID together with the wiki ID also identifies the page, unless the page ID is 0. If the wiki ID is self::LOCAL, the identity is relative to the local wiki.

Note
For compatibility with the Title class, PageIdentity instances may for now not only represent non-existing pages, but also things that are not actually pages, such as interwiki links, section links, or Special pages (which exist, but are not proper editable pages). This is intended to change in the future, so that a PageIdentity always represents a "proper" page. Until then, code that requires a proper page should call canExist() to check, or require a ProperPageIdentity. Eventually, ProperPageIdentity is intended to become an alias for PageIdentity.
For compatibility with the Title class, PageIdentity instances may be mutable, and return different values from methods such as getId() or exist() at different times. In the future, the contract of this interface is intended to be changed to disallow this.
Instances of Title shall be the only instances of PageIdentity that are not proper pages. Other classes implementing PageIdentity must represent proper pages, and also implement ProperPageIdentity. The idea is that once Title has been removed, all PageIdentities are then proper pages, and the distinction between PageIdentity and ProperPageIdentity becomes redundant.
Code that deserializes instances of PageIdentity must ensure that the original meaning of the "local" Wiki ID is preserved if the PageIdentity originated on another wiki.

Stable to type

Since
1.36

Definition at line 65 of file PageIdentity.php.

Member Function Documentation

◆ __toString()

Page\PageIdentity::__toString ( )

Returns an informative human readable representation of the page identity, for use in logging and debugging.

Returns
string

Implemented in Title, WikiPage, and Page\PageIdentityValue.

◆ canExist()

Page\PageIdentity::canExist ( )

Checks whether this PageIdentity represents a "proper" page, meaning that it could exist as an editable page on the wiki.

Note
This method only exists to allow Title to implement this interface. Title instances may represent things that are not pages, such as relative section links or interwiki links. The idea is that code that expects a PageIdentity is expecting an actual page. The canExist() method can be used to ensure that it is.
Eventually, this method should be guaranteed to return true, then be deprecated, and then removed.
Returns
bool
See also
Title::getArticleID()
Title::toPageIdentity()
getId()

Implemented in Title, WikiPage, Page\ProperPageIdentity, and Page\PageIdentityValue.

Referenced by Page\WikiPageFactory\newFromTitle().

◆ exists()

Page\PageIdentity::exists ( )

Checks if the page currently exists.

Implementations must ensure that this method returns false when getId() would throw or return 0. This also implies that this method must return false if canExist() would return false.

See also
Title::exists()
Returns
bool

Implemented in WikiPage, and Page\PageIdentityValue.

Referenced by Title\estimateRevisionCount(), Title\getRestrictionTypes(), Title\getTitleProtectionInternal(), Title\hasSourceText(), Title\isKnown(), and Title\makeTitleSafe().

◆ getDBkey()

Page\PageIdentity::getDBkey ( )

Get the page title in DB key form.

Note
When getId() would throw, the behavior of this method is undefined. This is necessary to allow the Title class to implement this interface.
Returns
string

Implemented in Title, WikiPage, and Page\PageIdentityValue.

Referenced by Title\castFromPageIdentity(), WikiPage\isSamePageAs(), Title\isSamePageAs(), and TitleValue\newFromPage().

◆ getId()

Page\PageIdentity::getId (   $wikiId = self::LOCAL)

Returns the page ID.

If this ID is 0, this means the page does not exist.

Implementations must call assertWiki().

Note
As a concession to allowing Title to implement this interface, PageIdentity instances may represent things that are not pages, such as relative section links or interwiki links. If getId() is called on a PageIdentity that does not actually represent a page, it must throw a RuntimeException. The idea is that code that expects a PageIdentity is expecting an actual page. The canExist() method can be used to ensure that it is.
Parameters
string | false$wikiIdMust be provided when accessing the ID of a non-local PageIdentity, to prevent data corruption when using a PageIdentity belonging to one wiki in the context of another. Should be omitted if expecting the local wiki.
Returns
int
Exceptions
RuntimeExceptionif this PageIdentity is not a "proper" page identity, but e.g. a relative section link, an interwiki link, etc.
PreconditionExceptionif this PageIdentity does not belong to the wiki identified by $wikiId.
See also
Title::getArticleID()
Title::toPageIdentity()
canExist()

Implemented in Title, WikiPage, Page\ProperPageIdentity, and Page\PageIdentityValue.

Referenced by Title\castFromPageIdentity(), WikiPage\isSamePageAs(), and Title\isSamePageAs().

◆ getNamespace()

Page\PageIdentity::getNamespace ( )

Returns the page's namespace number.

The value returned by this method should represent a valid namespace, but this cannot be guaranteed in all cases.

Note
When getId() would throw, the behavior of this method is undefined. This is necessary to allow the Title class to implement this interface.
Returns
int

Implemented in Title, WikiPage, and Page\PageIdentityValue.

Referenced by Title\castFromPageIdentity(), WikiPage\isSamePageAs(), Title\isSamePageAs(), TitleValue\newFromPage(), and Page\WikiPageFactory\newFromTitle().

◆ getWikiId()

Page\PageIdentity::getWikiId ( )

Get the ID of the wiki this page belongs to.

Note
When getId() would throw, the behavior of this method is undefined. This is necessary to allow the Title class to implement this interface.
See also
RevisionRecord::getWikiId()
Returns
string|false The wiki's logical name, or self::LOCAL to indicate the local wiki.

Implements MediaWiki\DAO\WikiAwareEntity.

Implemented in Title, WikiPage, Page\ProperPageIdentity, and Page\PageIdentityValue.

Referenced by WikiPage\isSamePageAs(), Title\isSamePageAs(), and TitleValue\newFromPage().

◆ isSamePageAs()

Page\PageIdentity::isSamePageAs ( PageIdentity  $other)

Checks whether the given PageIdentity refers to the same page as this PageIdentity.

Two PageIdentity instances are considered to refer to the same page if the page exists, they belong to the same wiki, and have the same ID; or the page does not exist, they belong to the same wiki, and have the same namespace and DB key.

Parameters
PageIdentity$other
Returns
bool

Implemented in Title, WikiPage, and Page\PageIdentityValue.


The documentation for this interface was generated from the following file: