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