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