1	<?php
2	/**
3	* Service for constructing RevisionRecord objects.
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 MediaWiki\Page\PageIdentity;
26	use Wikimedia\Rdbms\IDBAccessObject;
27	use Wikimedia\Rdbms\IReadableDatabase;
28
29	/**
30	* Service for constructing RevisionRecord objects.
31	*
32	* @since 1.31
33	* @since 1.32 Renamed from MediaWiki\Storage\RevisionFactory
34	*
35	* @note This was written to act as a drop-in replacement for the corresponding
36	*       static methods in the old Revision class (which was later removed in 1.37).
37	*/
38	interface RevisionFactory {
39
40	/**
41	* Constructs a RevisionRecord given a database row and content slots.
42	*
43	* MCR migration note: this replaced Revision::newFromRow for rows based on the
44	* revision, slot, and content tables defined for MCR since MW1.31.
45	*
46	* @param \stdClass $row A query result row as a raw object.
47	*        Use getQueryInfo() to build a query that yields the required fields.
48	* @param int $queryFlags Flags for lazy loading behavior, see IDBAccessObject::READ_XXX.
49	* @param PageIdentity|null $page A page object for the revision.
50	*
51	* @return RevisionRecord
52	*/
53	public function newRevisionFromRow(
54	$row,
55	$queryFlags = IDBAccessObject::READ_NORMAL,
56	?PageIdentity $page = null
57	);
58
59	/**
60	* Make a fake RevisionRecord object from an archive table row. This is queried
61	* for permissions or even inserted (as in Special:Undelete).
62	*
63	* The user ID and user name may optionally be supplied using the aliases
64	* ar_user and ar_user_text (the names of fields which existed before
65	* MW 1.34).
66	*
67	* MCR migration note: this replaced Revision::newFromArchiveRow
68	*
69	* @param \stdClass $row A query result row as a raw object.
70	*        Use getArchiveQueryInfo() to build a query that yields the required fields.
71	* @param int $queryFlags Flags for lazy loading behavior, see IDBAccessObject::READ_XXX.
72	* @param PageIdentity|null $page
73	* @param array $overrides An associative array that allows fields in $row to be overwritten.
74	*        Keys in this array correspond to field names in $row without the "ar_" prefix, so
75	*        $overrides['user'] will override $row->ar_user, etc.
76	*
77	* @return RevisionRecord
78	*/
79	public function newRevisionFromArchiveRow(
80	$row,
81	$queryFlags = IDBAccessObject::READ_NORMAL,
82	?PageIdentity $page = null,
83	array $overrides = []
84	);
85
86	/**
87	* Return the tables, fields, and join conditions to be selected to create
88	* a new RevisionArchiveRecord object.
89	*
90	* @since 1.37, since 1.31 on RevisionStore
91	* @deprecated since 1.41 use RevisionStore::newArchiveSelectQueryBuilder() instead.
92	*
93	* @return array[] With three keys:
94	*   - tables: (string[]) to include in the `$table` to `IDatabase->select()` or `SelectQueryBuilder::tables`
95	*   - fields: (string[]) to include in the `$vars` to `IDatabase->select()` or `SelectQueryBuilder::fields`
96	*   - joins: (array) to include in the `$join_conds` to `IDatabase->select()` or `SelectQueryBuilder::joinConds`
97	* @phan-return array{tables:string[],fields:string[],joins:array}
98	*/
99	public function getArchiveQueryInfo();
100
101	/**
102	* Return the tables, fields, and join conditions to be selected to create
103	* a new RevisionStoreRecord object.
104	*
105	* MCR migration note: this replaced Revision::getQueryInfo
106	*
107	* If the format of fields returned changes in any way then the cache key provided by
108	* self::getRevisionRowCacheKey should be updated.
109	*
110	* @since 1.37, since 1.31 on RevisionStore
111	* @deprecated since 1.41 use RevisionStore::newSelectQueryBuilder() instead.
112	*
113	* @param array $options Any combination of the following strings
114	*  - 'page': Join with the page table, and select fields to identify the page
115	*  - 'user': Join with the user table, and select the user name
116	*
117	* @return array[] With three keys:
118	*  - tables: (string[]) to include in the `$table` to `IDatabase->select()` or `SelectQueryBuilder::tables`
119	*  - fields: (string[]) to include in the `$vars` to `IDatabase->select()` or `SelectQueryBuilder::fields`
120	*  - joins: (array) to include in the `$join_conds` to `IDatabase->select()` or `SelectQueryBuilder::joinConds`
121	* @phan-return array{tables:string[],fields:string[],joins:array}
122	*/
123	public function getQueryInfo( $options = [] );
124
125	/**
126	* Return a SelectQueryBuilder to allow querying revision store
127	*
128	* @since 1.41
129	*
130	* @param IReadableDatabase $dbr A db object to do the query on.
131	*
132	* @return RevisionSelectQueryBuilder
133	*/
134	public function newSelectQueryBuilder( IReadableDatabase $dbr ): RevisionSelectQueryBuilder;
135
136	/**
137	* Return a SelectQueryBuilder to allow querying archive table
138	*
139	* @since 1.41
140	*
141	* @param IReadableDatabase $dbr A db object to do the query on.
142	*
143	* @return ArchiveSelectQueryBuilder
144	*/
145	public function newArchiveSelectQueryBuilder( IReadableDatabase $dbr ): ArchiveSelectQueryBuilder;
146
147	/**
148	* Determine whether the parameter is a row containing all the fields
149	* that RevisionFactory needs to create a RevisionRecord from the row.
150	*
151	* @param mixed $row
152	* @param string $table 'archive' or empty
153	* @return bool
154	*/
155	public function isRevisionRow( $row, string $table = '' );
156
157	}