1	<?php
2	/**
3	*  Service for looking up page revisions.
4	*
5	* This program is free software; you can redistribute it and/or modify
6	* it under the terms of the GNU General Public License as published by
7	* the Free Software Foundation; either version 2 of the License, or
8	* (at your option) any later version.
9	*
10	* This program is distributed in the hope that it will be useful,
11	* but WITHOUT ANY WARRANTY; without even the implied warranty of
12	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13	* GNU General Public License for more details.
14	*
15	* You should have received a copy of the GNU General Public License along
16	* with this program; if not, write to the Free Software Foundation, Inc.,
17	* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18	* http://www.gnu.org/copyleft/gpl.html
19	*
20	* @file
21	*/
22
23	namespace MediaWiki\Revision;
24
25	use IDBAccessObject;
26	use MediaWiki\Linker\LinkTarget;
27	use MediaWiki\Page\PageIdentity;
28
29	/**
30	* Service for looking up page revisions.
31	*
32	* @note This was written to act as a drop-in replacement for the corresponding
33	*       static methods in the old Revision class (which was later removed in 1.37).
34	*
35	* @since 1.31
36	* @since 1.32 Renamed from MediaWiki\Storage\RevisionLookup
37	*/
38	interface RevisionLookup {
39
40	/**
41	* Load a page revision from a given revision ID number.
42	* Returns null if no such revision can be found.
43	*
44	* MCR migration note: this replaced Revision::newFromId
45	*
46	* $flags include:
47	*
48	* @param int $id
49	* @param int $flags bit field, see IDBAccessObject::READ_XXX
50	* @param PageIdentity|null $page The page the revision belongs to.
51	*        Providing the page may improve performance.
52	*
53	* @return RevisionRecord|null
54	*/
55	public function getRevisionById( $id, $flags = 0, PageIdentity $page = null );
56
57	/**
58	* Load either the current, or a specified, revision
59	* that's attached to a given link target. If not attached
60	* to that link target, will return null.
61	*
62	* MCR migration note: this replaced Revision::newFromTitle
63	*
64	* @param LinkTarget|PageIdentity $page Calling with LinkTarget is deprecated since 1.36
65	* @param int $revId (optional)
66	* @param int $flags bit field, see IDBAccessObject::READ_XXX
67	* @return RevisionRecord|null
68	*/
69	public function getRevisionByTitle( $page, $revId = 0, $flags = 0 );
70
71	/**
72	* Load either the current, or a specified, revision
73	* that's attached to a given page ID.
74	* Returns null if no such revision can be found.
75	*
76	* MCR migration note: this replaced Revision::newFromPageId
77	*
78	* @param int $pageId
79	* @param int $revId (optional)
80	* @param int $flags bit field, see IDBAccessObject::READ_XXX
81	* @return RevisionRecord|null
82	*/
83	public function getRevisionByPageId( $pageId, $revId = 0, $flags = 0 );
84
85	/**
86	* Load the revision for the given title with the given timestamp.
87	* WARNING: Timestamps may in some circumstances not be unique,
88	* so this isn't the best key to use.
89	*
90	* MCR migration note: this replaced Revision::loadFromTimestamp
91	*
92	* @param LinkTarget|PageIdentity $page Calling with LinkTarget is deprecated since 1.36
93	* @param string $timestamp
94	* @param int $flags Bitfield (optional) include:
95	*      IDBAccessObject::READ_LATEST: Select the data from the primary DB
96	*      IDBAccessObject::READ_LOCKING: Select & lock the data from the primary DB
97	*      Default: IDBAccessObject::READ_NORMAL
98	* @return RevisionRecord|null
99	*/
100	public function getRevisionByTimestamp(
101	$page,
102	string $timestamp,
103	int $flags = IDBAccessObject::READ_NORMAL
104	): ?RevisionRecord;
105
106	/**
107	* Get previous revision for this title
108	*
109	* MCR migration note: this replaced Revision::getPrevious
110	*
111	* @param RevisionRecord $rev
112	* @param int $flags (optional) $flags include:
113	*      IDBAccessObject::READ_LATEST: Select the data from the primary DB
114	*
115	* @return RevisionRecord|null
116	*/
117	public function getPreviousRevision( RevisionRecord $rev, $flags = 0 );
118
119	/**
120	* Get next revision for this title
121	*
122	* MCR migration note: this replaced Revision::getNext
123	*
124	* @param RevisionRecord $rev
125	* @param int $flags (optional) $flags include:
126	*      IDBAccessObject::READ_LATEST: Select the data from the primary DB
127	*
128	* @return RevisionRecord|null
129	*/
130	public function getNextRevision( RevisionRecord $rev, $flags = 0 );
131
132	/**
133	* Get rev_timestamp from rev_id, without loading the rest of the row.
134	*
135	* MCR migration note: this replaced Revision::getTimestampFromId
136	*
137	* @param int $id
138	* @param int $flags
139	* @return string|false False if not found
140	* @since 1.34 (present earlier in RevisionStore)
141	*/
142	public function getTimestampFromId( $id, $flags = 0 );
143
144	/**
145	* Load a revision based on a known page ID and current revision ID from the DB
146	*
147	* This method allows for the use of caching, though accessing anything that normally
148	* requires permission checks (aside from the text) will trigger a small DB lookup.
149	*
150	* MCR migration note: this replaced Revision::newKnownCurrent
151	*
152	* @param PageIdentity $page the associated page
153	* @param int $revId current revision of this page
154	*
155	* @return RevisionRecord|false Returns false if missing
156	*/
157	public function getKnownCurrentRevision( PageIdentity $page, $revId = 0 );
158
159	/**
160	* Get the first revision of the page.
161	*
162	* @since 1.35
163	* @param LinkTarget|PageIdentity $page Calling with LinkTarget is deprecated since 1.36
164	* @param int $flags bit field, see IDBAccessObject::READ_* constants.
165	* @return RevisionRecord|null
166	*/
167	public function getFirstRevision(
168	$page,
169	int $flags = IDBAccessObject::READ_NORMAL
170	): ?RevisionRecord;
171
172	}