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