includes/content/Content.php

   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 namespace MediaWiki\Content;
  22
  23 use MediaWiki\Parser\MagicWord;
  24 use 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  */
  39 interface 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 */
 379 class_alias( Content::class, 'Content' );