1	<?php
2	/**
3	* This program is free software; you can redistribute it and/or modify
4	* it under the terms of the GNU General Public License as published by
5	* the Free Software Foundation; either version 2 of the License, or
6	* (at your option) any later version.
7	*
8	* This program is distributed in the hope that it will be useful,
9	* but WITHOUT ANY WARRANTY; without even the implied warranty of
10	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11	* GNU General Public License for more details.
12	*
13	* You should have received a copy of the GNU General Public License along
14	* with this program; if not, write to the Free Software Foundation, Inc.,
15	* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
16	* http://www.gnu.org/copyleft/gpl.html
17	*
18	* @file
19	*/
20
21	namespace MediaWiki\Page;
22
23	use MediaWiki\Title\Title;
24	use RuntimeException;
25	use Wikimedia\Assert\PreconditionException;
26
27	/**
28	* Interface for objects (potentially) representing an editable wiki page.
29	*
30	* The identity of any PageIdentity object is defined by the
31	* namespace, the dbkey, and the wiki ID.
32	* The page ID together with the wiki ID also identifies the page,
33	* unless the page ID is 0.
34	* If the wiki ID is self::LOCAL, the identity is relative to the local wiki.
35	*
36	* @note For compatibility with the Title class, PageIdentity instances
37	*   may for now not only represent non-existing pages, but also things
38	*   that are not actually pages, such as interwiki links, section links,
39	*   or Special pages (which exist, but are not proper editable pages).
40	*   This is intended to change in the future, so that a PageIdentity always
41	*   represents a "proper" page. Until then, code that requires a proper page
42	*   should call canExist() to check, or require a ProperPageIdentity.
43	*   Eventually, ProperPageIdentity is intended to become an alias for
44	*   PageIdentity.
45	*
46	* @note For compatibility with the Title class, PageIdentity instances may
47	*   be mutable, and return different values from methods such as getId() or exist()
48	*   at different times. In the future, the contract of this interface is intended
49	*   to be changed to disallow this.
50	*
51	* @note Instances of Title shall be the only instances of PageIdentity that are not
52	*   proper pages. Other classes implementing PageIdentity must represent proper pages,
53	*   and also implement ProperPageIdentity. The idea is that once Title has been removed,
54	*   all PageIdentities are then proper pages, and the distinction between PageIdentity
55	*   and ProperPageIdentity becomes redundant.
56	*
57	* @note  Code that deserializes instances of PageIdentity must ensure that the original
58	*   meaning of the "local" Wiki ID is preserved if the PageIdentity originated on
59	*   another wiki.
60	*
61	* @see https://www.mediawiki.org/wiki/Manual:Modeling_pages
62	*
63	* @stable to type
64	* @since 1.36
65	* @ingroup Page
66	*/
67	interface PageIdentity extends PageReference {
68
69	/**
70	* Returns the page ID.
71	*
72	* If this ID is 0, this means the page does not exist.
73	*
74	* Implementations must call assertWiki().
75	*
76	* @note As a concession to allowing Title to implement this interface,
77	*       PageIdentity instances may represent things that are not pages,
78	*       such as relative section links or interwiki links. If getId()
79	*       is called on a PageIdentity that does not actually represent a
80	*       page, it must throw a RuntimeException. The idea is that code that
81	*       expects a PageIdentity is expecting an actual page.
82	*       The canExist() method can be used to ensure that it is.
83	*
84	* @param string|false $wikiId Must be provided when accessing the ID of a non-local
85	*        PageIdentity, to prevent data corruption when using a PageIdentity belonging
86	*        to one wiki in the context of another. Should be omitted if expecting the local wiki.
87	*
88	* @return int
89	* @throws RuntimeException if this PageIdentity is not a "proper"
90	*         page identity, but e.g. a relative section link, an interwiki
91	*         link, etc.
92	* @throws PreconditionException if this PageIdentity does not belong to the wiki
93	*         identified by $wikiId.
94	* @see Title::getArticleID()
95	* @see Title::toPageIdentity()
96	* @see canExist()
97	*
98	*/
99	public function getId( $wikiId = self::LOCAL ): int;
100
101	/**
102	* Checks whether this PageIdentity represents a "proper" page,
103	* meaning that it could exist as an editable page on the wiki.
104	*
105	* @note This method only exists to allow Title to implement this interface.
106	*       Title instances may represent things that are not pages,
107	*       such as relative section links or interwiki links.
108	*       The idea is that code that expects a PageIdentity is expecting an
109	*       actual page. The canExist() method can be used to ensure that it is.
110	*
111	* @note Eventually, this method should be guaranteed to return true,
112	*       then be deprecated, and then removed.
113	*
114	* @return bool
115	* @see Title::getArticleID()
116	* @see Title::toPageIdentity()
117	*
118	* @see getId()
119	*/
120	public function canExist(): bool;
121
122	/**
123	* Checks if the page currently exists.
124	*
125	* Implementations must ensure that this method returns false
126	* when getId() would throw or return 0.
127	* This also implies that this method must return false
128	* if canExist() would return false.
129	*
130	* @see Title::exists()
131	*
132	* @return bool
133	*/
134	public function exists(): bool;
135
136	}