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	use MediaWiki\Parser\MagicWord;
22	use MediaWiki\Title\Title;
23
24	/**
25	* Base interface for representing page content.
26	*
27	* A content object represents page content, e.g. the text to show on a page.
28	* Content objects have no knowledge about how they relate to wiki pages.
29	*
30	* Must not be implemented directly by extensions, extend AbstractContent instead.
31	*
32	* @stable to type
33	* @since 1.21
34	* @ingroup Content
35	* @author Daniel Kinzler
36	*/
37	interface Content {
38
39	/**
40	* @since 1.21
41	*
42	* @return string A string representing the content in a way useful for
43	*   building a full text search index. If no useful representation exists,
44	*   this method returns an empty string.
45	*
46	* @todo Test that this actually works
47	* @todo Make sure this also works with LuceneSearch / WikiSearch
48	*/
49	public function getTextForSearchIndex();
50
51	/**
52	* @since 1.21
53	*
54	* @return string|false The wikitext to include when another page includes this
55	* content, or false if the content is not includable in a wikitext page.
56	*
57	* @todo Allow native handling, bypassing wikitext representation, like
58	*  for includable special pages.
59	* @todo Allow transclusion into other content models than Wikitext!
60	* @todo Used in WikiPage and MessageCache to get message text. Not so
61	*  nice. What should we use instead?!
62	*/
63	public function getWikitextForTransclusion();
64
65	/**
66	* Returns a textual representation of the content suitable for use in edit
67	* summaries and log messages.
68	*
69	* @since 1.21
70	*
71	* @param int $maxLength Maximum length of the summary text, in bytes.
72	* Usually implemented using {@link Language::truncateForDatabase()}.
73	*
74	* @return string The summary text.
75	*/
76	public function getTextForSummary( $maxLength = 250 );
77
78	/**
79	* Returns native representation of the data. Interpretation depends on
80	* the data model used, as given by getDataModel().
81	*
82	* @since 1.21
83	*
84	* @deprecated since 1.33 use getText() for TextContent instances.
85	*             For other content models, use specialized getters.
86	*
87	* @return mixed The native representation of the content. Could be a
88	*    string, a nested array structure, an object, a binary blob...
89	*    anything, really.
90	*
91	* @note Caller must be aware of content model!
92	*/
93	public function getNativeData();
94
95	/**
96	* Returns the content's nominal size in "bogo-bytes".
97	*
98	* @return int
99	*/
100	public function getSize();
101
102	/**
103	* Returns the ID of the content model used by this Content object.
104	* Corresponds to the CONTENT_MODEL_XXX constants.
105	*
106	* @since 1.21
107	*
108	* @return string The model id
109	*/
110	public function getModel();
111
112	/**
113	* Convenience method that returns the ContentHandler singleton for handling
114	* the content model that this Content object uses.
115	*
116	* Shorthand for ContentHandler::getForContent( $this )
117	*
118	* @since 1.21
119	*
120	* @return ContentHandler
121	*/
122	public function getContentHandler();
123
124	/**
125	* Convenience method that returns the default serialization format for the
126	* content model that this Content object uses.
127	*
128	* Shorthand for $this->getContentHandler()->getDefaultFormat()
129	*
130	* @since 1.21
131	*
132	* @return string
133	*/
134	public function getDefaultFormat();
135
136	/**
137	* Convenience method that returns the list of serialization formats
138	* supported for the content model that this Content object uses.
139	*
140	* Shorthand for $this->getContentHandler()->getSupportedFormats()
141	*
142	* @since 1.21
143	*
144	* @return string[] List of supported serialization formats
145	*/
146	public function getSupportedFormats();
147
148	/**
149	* Returns true if $format is a supported serialization format for this
150	* Content object, false if it isn't.
151	*
152	* Note that this should always return true if $format is null, because null
153	* stands for the default serialization.
154	*
155	* Shorthand for $this->getContentHandler()->isSupportedFormat( $format )
156	*
157	* @since 1.21
158	*
159	* @param string $format The serialization format to check.
160	*
161	* @return bool Whether the format is supported
162	*/
163	public function isSupportedFormat( $format );
164
165	/**
166	* Convenience method for serializing this Content object.
167	*
168	* Shorthand for $this->getContentHandler()->serializeContent( $this, $format )
169	*
170	* @since 1.21
171	*
172	* @param string|null $format The desired serialization format, or null for the default format.
173	*
174	* @return string Serialized form of this Content object.
175	*/
176	public function serialize( $format = null );
177
178	/**
179	* Returns true if this Content object represents empty content.
180	*
181	* @since 1.21
182	*
183	* @return bool Whether this Content object is empty
184	*/
185	public function isEmpty();
186
187	/**
188	* Returns whether the content is valid. This is intended for local validity
189	* checks, not considering global consistency.
190	*
191	* Content needs to be valid before it can be saved.
192	*
193	* This default implementation always returns true.
194	*
195	* @since 1.21
196	*
197	* @return bool
198	*/
199	public function isValid();
200
201	/**
202	* Returns true if this Content objects is conceptually equivalent to the
203	* given Content object.
204	*
205	* Contract:
206	*
207	* - Will return false if $that is null.
208	* - Will return true if $that === $this.
209	* - Will return false if $that->getModel() !== $this->getModel().
210	* - Will return false if get_class( $that ) !== get_class( $this )
211	* - Should return false if $that->getModel() == $this->getModel() and
212	*     $that is not semantically equivalent to $this, according to
213	*     the data model defined by $this->getModel().
214	*
215	* Implementations should be careful to make equals() transitive and reflexive:
216	*
217	* - $a->equals( $b ) <=> $b->equals( $a )
218	* - $a->equals( $b ) &&  $b->equals( $c ) ==> $a->equals( $c )
219	*
220	* @since 1.21
221	*
222	* @param Content|null $that The Content object to compare to.
223	*
224	* @return bool True if this Content object is equal to $that, false otherwise.
225	*/
226	public function equals( Content $that = null );
227
228	/**
229	* Return a copy of this Content object. The following must be true for the
230	* object returned:
231	*
232	* if $copy = $original->copy()
233	*
234	* - get_class($original) === get_class($copy)
235	* - $original->getModel() === $copy->getModel()
236	* - $original->equals( $copy )
237	*
238	* If and only if the Content object is immutable, the copy() method can and
239	* should return $this. That is, $copy === $original may be true, but only
240	* for immutable content objects.
241	*
242	* @since 1.21
243	*
244	* @return Content A copy of this object
245	*/
246	public function copy();
247
248	/**
249	* Returns true if this content is countable as a "real" wiki page, provided
250	* that it's also in a countable location (e.g. a current revision in the
251	* main namespace).
252	*
253	* @see SlotRoleHandler::supportsArticleCount
254	*
255	* @since 1.21
256	*
257	* @param bool|null $hasLinks If it is known whether this content contains
258	*    links, provide this information here, to avoid redundant parsing to
259	*    find out.
260	*
261	* @return bool
262	*/
263	public function isCountable( $hasLinks = null );
264
265	/**
266	* Construct the redirect destination from this content and return a Title,
267	* or null if this content doesn't represent a redirect.
268	*
269	* @since 1.21
270	*
271	* @return Title|null
272	*/
273	public function getRedirectTarget();
274
275	/**
276	* Returns whether this Content represents a redirect.
277	* Shorthand for getRedirectTarget() !== null.
278	*
279	* @see SlotRoleHandler::supportsRedirects
280	*
281	* @since 1.21
282	*
283	* @return bool
284	*/
285	public function isRedirect();
286
287	/**
288	* If this Content object is a redirect, this method updates the redirect target.
289	* Otherwise, it does nothing.
290	*
291	* @since 1.21
292	*
293	* @param Title $target The new redirect target
294	*
295	* @return Content A new Content object with the updated redirect (or $this
296	*   if this Content object isn't a redirect)
297	*/
298	public function updateRedirect( Title $target );
299
300	/**
301	* Returns the section with the given ID.
302	*
303	* @since 1.21
304	*
305	* @param string|int $sectionId Section identifier as a number or string
306	* (e.g. 0, 1 or 'T-1'). The ID "0" retrieves the section before the first heading, "1" the
307	* text between the first heading (included) and the second heading (excluded), etc.
308	*
309	* @return Content|false|null The section, or false if no such section
310	*    exist, or null if sections are not supported.
311	*/
312	public function getSection( $sectionId );
313
314	/**
315	* Replaces a section of the content and returns a Content object with the
316	* section replaced.
317	*
318	* @since 1.21
319	*
320	* @param string|int|null|false $sectionId Section identifier as a number or string
321	* (e.g. 0, 1 or 'T-1'), null/false or an empty string for the whole page
322	* or 'new' for a new section.
323	* @param Content $with New content of the section
324	* @param string $sectionTitle New section's subject, only if $section is 'new'
325	*
326	* @return Content|null New content of the entire page, or null if error
327	*/
328	public function replaceSection( $sectionId, Content $with, $sectionTitle = '' );
329
330	/**
331	* Returns a new WikitextContent object with the given section heading
332	* prepended, if supported. The default implementation just returns this
333	* Content object unmodified, ignoring the section header.
334	*
335	* @since 1.21
336	*
337	* @param string $header
338	*
339	* @return Content
340	*/
341	public function addSectionHeader( $header );
342
343	/**
344	* Returns true if this Content object matches the given magic word.
345	*
346	* @since 1.21
347	*
348	* @param MagicWord $word The magic word to match
349	*
350	* @return bool Whether this Content object matches the given magic word.
351	*/
352	public function matchMagicWord( MagicWord $word );
353
354	/**
355	* Converts this content object into another content object with the given content model,
356	* if that is possible.
357	*
358	* @param string $toModel The desired content model, use the CONTENT_MODEL_XXX flags.
359	* @param string $lossy Optional flag, set to "lossy" to allow lossy conversion. If lossy
360	* conversion is not allowed, full round-trip conversion is expected to work without losing
361	* information.
362	*
363	* @return Content|false A content object with the content model $toModel, or false if
364	* that conversion is not supported.
365	*/
366	public function convert( $toModel, $lossy = '' );
367
368	// @todo ImagePage and CategoryPage interfere with per-content action handlers
369	// @todo nice integration of GeSHi syntax highlighting
370	//   [11:59] <vvv> Hooks are ugly; make CodeHighlighter interface and a
371	//   config to set the class which handles syntax highlighting
372	//   [12:00] <vvv> And default it to a DummyHighlighter
373
374	}