1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
|
<?php
/**
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License along
* with this program; if not, write to the Free Software Foundation, Inc.,
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
* http://www.gnu.org/copyleft/gpl.html
*
* @file
*/
namespace MediaWiki\Page;
use MediaWiki\Title\Title;
use RuntimeException;
use Wikimedia\Assert\PreconditionException;
/**
* 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.
*
* @note 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.
*
* @note 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.
*
* @note 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.
*
* @see https://www.mediawiki.org/wiki/Manual:Modeling_pages
*
* @stable to type
* @since 1.36
* @ingroup Page
*/
interface PageIdentity extends PageReference {
/**
* 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.
*
* @param string|false $wikiId Must 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.
*
* @return int
* @throws RuntimeException if this PageIdentity is not a "proper"
* page identity, but e.g. a relative section link, an interwiki
* link, etc.
* @throws PreconditionException if this PageIdentity does not belong to the wiki
* identified by $wikiId.
* @see Title::getArticleID()
* @see Title::toPageIdentity()
* @see canExist()
*
*/
public function getId( $wikiId = self::LOCAL ): int;
/**
* 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.
*
* @note Eventually, this method should be guaranteed to return true,
* then be deprecated, and then removed.
*
* @return bool
* @see Title::getArticleID()
* @see Title::toPageIdentity()
*
* @see getId()
*/
public function canExist(): bool;
/**
* 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 Title::exists()
*
* @return bool
*/
public function exists(): bool;
}
|
