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\DAO\WikiAwareEntity;
24
25	/**
26	* Interface for objects (potentially) representing a page that can be viewable and linked to
27	* on a wiki. This includes special pages.
28	*
29	* The identity of any PageReference object is defined by the
30	* namespace, the dbkey, and the wiki ID.
31	* If the wiki ID is self::LOCAL, the identity is relative to the local wiki.
32	*
33	* @note For compatibility with the Title class, PageReference instances
34	*   may for represent things that are not viewable pages, such as interwiki links
35	*   and section links. This is intended to change in the future.
36	*
37	* @note Instances of Title shall be the only instances of PageReference that are not
38	*   viewable pages. Other classes implementing PageReference must not permit an empty DB key.
39	*   The idea is that once Title has been removed, all PageReference are then viewable pages.
40	*
41	* @note Code that deserializes instances of PageReference must ensure that the original
42	*   meaning of the "local" Wiki ID is preserved if the PageReference originated on
43	*   another wiki.
44	*
45	* @see https://www.mediawiki.org/wiki/Manual:Modeling_pages
46	*
47	* @stable to type
48	* @since 1.37
49	* @ingroup Page
50	*/
51	interface PageReference extends WikiAwareEntity {
52
53	/**
54	* Get the ID of the wiki this page belongs to.
55	*
56	* @return string|false The wiki's logical name,
57	*         or self::LOCAL to indicate the local wiki.
58	*/
59	public function getWikiId();
60
61	/**
62	* Returns the page's namespace number.
63	*
64	* The value returned by this method should represent a valid namespace,
65	* but this cannot be guaranteed in all cases.
66	*
67	* @return int
68	*/
69	public function getNamespace(): int;
70
71	/**
72	* Get the page title in DB key form.
73	*
74	* @note This may return a string starting with a hash, if the PageReference represents
75	*       the target of a block or unblock operation. This is due to the way the block target
76	*       is represented in the logging table. This is intended to change in the future.
77	*
78	* @note This may return an empty string, if this PageReference is a Title that represents
79	*       a relative section link. This is intended to change in the future.
80	*
81	* @return string
82	*/
83	public function getDBkey(): string;
84
85	/**
86	* Checks whether the given PageReference refers to the same page as this PageReference.
87	*
88	* Two PageReference instances are considered to refer to the same page if
89	* they belong to the same wiki, and have the same namespace and DB key.
90	*
91	* @param PageReference $other
92	*
93	* @return bool
94	*/
95	public function isSamePageAs( PageReference $other ): bool;
96
97	/**
98	* Returns an informative human readable unique representation of the page identity,
99	* for use as a cache key and for logging and debugging.
100	*
101	* @return string
102	*/
103	public function __toString(): string;
104
105	}