includes/content/Content.php

   1 <?php
   2 /**
   3  * A content object represents page content, e.g. the text to show on a page.
   4  * Content objects have no knowledge about how they relate to wiki pages.
   5  *
   6  * @since 1.21
   7  */
   8 interface Content {
   9
  10         /**
  11          * @since 1.21
  12          *
  13          * @return string A string representing the content in a way useful for
  14          *   building a full text search index. If no useful representation exists,
  15          *   this method returns an empty string.
  16          *
  17          * @todo: test that this actually works
  18          * @todo: make sure this also works with LuceneSearch / WikiSearch
  19          */
  20         public function getTextForSearchIndex();
  21
  22         /**
  23          * @since 1.21
  24          *
  25          * @return string The wikitext to include when another page includes this
  26          * content, or false if the content is not includable in a wikitext page.
  27          *
  28          * @TODO: allow native handling, bypassing wikitext representation, like
  29          *    for includable special pages.
  30          * @TODO: allow transclusion into other content models than Wikitext!
  31          * @TODO: used in WikiPage and MessageCache to get message text. Not so
  32          *    nice. What should we use instead?!
  33          */
  34         public function getWikitextForTransclusion();
  35
  36         /**
  37          * Returns a textual representation of the content suitable for use in edit
  38          * summaries and log messages.
  39          *
  40          * @since 1.21
  41          *
  42          * @param $maxLength int Maximum length of the summary text
  43          * @return string The summary text
  44          */
  45         public function getTextForSummary( $maxLength = 250 );
  46
  47         /**
  48          * Returns native representation of the data. Interpretation depends on
  49          * the data model used, as given by getDataModel().
  50          *
  51          * @since 1.21
  52          *
  53          * @return mixed The native representation of the content. Could be a
  54          *    string, a nested array structure, an object, a binary blob...
  55          *    anything, really.
  56          *
  57          * @NOTE: Caller must be aware of content model!
  58          */
  59         public function getNativeData();
  60
  61         /**
  62          * Returns the content's nominal size in bogo-bytes.
  63          *
  64          * @return int
  65          */
  66         public function getSize();
  67
  68         /**
  69          * Returns the ID of the content model used by this Content object.
  70          * Corresponds to the CONTENT_MODEL_XXX constants.
  71          *
  72          * @since 1.21
  73          *
  74          * @return String The model id
  75          */
  76         public function getModel();
  77
  78         /**
  79          * Convenience method that returns the ContentHandler singleton for handling
  80          * the content model that this Content object uses.
  81          *
  82          * Shorthand for ContentHandler::getForContent( $this )
  83          *
  84          * @since 1.21
  85          *
  86          * @return ContentHandler
  87          */
  88         public function getContentHandler();
  89
  90         /**
  91          * Convenience method that returns the default serialization format for the
  92          * content model that this Content object uses.
  93          *
  94          * Shorthand for $this->getContentHandler()->getDefaultFormat()
  95          *
  96          * @since 1.21
  97          *
  98          * @return String
  99          */
 100         public function getDefaultFormat();
 101
 102         /**
 103          * Convenience method that returns the list of serialization formats
 104          * supported for the content model that this Content object uses.
 105          *
 106          * Shorthand for $this->getContentHandler()->getSupportedFormats()
 107          *
 108          * @since 1.21
 109          *
 110          * @return Array of supported serialization formats
 111          */
 112         public function getSupportedFormats();
 113
 114         /**
 115          * Returns true if $format is a supported serialization format for this
 116          * Content object, false if it isn't.
 117          *
 118          * Note that this should always return true if $format is null, because null
 119          * stands for the default serialization.
 120          *
 121          * Shorthand for $this->getContentHandler()->isSupportedFormat( $format )
 122          *
 123          * @since 1.21
 124          *
 125          * @param $format string The format to check
 126          * @return bool Whether the format is supported
 127          */
 128         public function isSupportedFormat( $format );
 129
 130         /**
 131          * Convenience method for serializing this Content object.
 132          *
 133          * Shorthand for $this->getContentHandler()->serializeContent( $this, $format )
 134          *
 135          * @since 1.21
 136          *
 137          * @param $format null|string The desired serialization format (or null for
 138          *    the default format).
 139          * @return string Serialized form of this Content object
 140          */
 141         public function serialize( $format = null );
 142
 143         /**
 144          * Returns true if this Content object represents empty content.
 145          *
 146          * @since 1.21
 147          *
 148          * @return bool Whether this Content object is empty
 149          */
 150         public function isEmpty();
 151
 152         /**
 153          * Returns whether the content is valid. This is intended for local validity
 154          * checks, not considering global consistency.
 155          *
 156          * Content needs to be valid before it can be saved.
 157          *
 158          * This default implementation always returns true.
 159          *
 160          * @since 1.21
 161          *
 162          * @return boolean
 163          */
 164         public function isValid();
 165
 166         /**
 167          * Returns true if this Content objects is conceptually equivalent to the
 168          * given Content object.
 169          *
 170          * Contract:
 171          *
 172          * - Will return false if $that is null.
 173          * - Will return true if $that === $this.
 174          * - Will return false if $that->getModel() != $this->getModel().
 175          * - Will return false if $that->getNativeData() is not equal to $this->getNativeData(),
 176          *   where the meaning of "equal" depends on the actual data model.
 177          *
 178          * Implementations should be careful to make equals() transitive and reflexive:
 179          *
 180          * - $a->equals( $b ) <=> $b->equals( $a )
 181          * - $a->equals( $b ) &&  $b->equals( $c ) ==> $a->equals( $c )
 182          *
 183          * @since 1.21
 184          *
 185          * @param $that Content The Content object to compare to
 186          * @return bool True if this Content object is equal to $that, false otherwise.
 187          */
 188         public function equals( Content $that = null );
 189
 190         /**
 191          * Return a copy of this Content object. The following must be true for the
 192          * object returned:
 193          *
 194          * if $copy = $original->copy()
 195          *
 196          * - get_class($original) === get_class($copy)
 197          * - $original->getModel() === $copy->getModel()
 198          * - $original->equals( $copy )
 199          *
 200          * If and only if the Content object is immutable, the copy() method can and
 201          * should return $this. That is, $copy === $original may be true, but only
 202          * for immutable content objects.
 203          *
 204          * @since 1.21
 205          *
 206          * @return Content. A copy of this object
 207          */
 208         public function copy( );
 209
 210         /**
 211          * Returns true if this content is countable as a "real" wiki page, provided
 212          * that it's also in a countable location (e.g. a current revision in the
 213          * main namespace).
 214          *
 215          * @since 1.21
 216          *
 217          * @param $hasLinks Bool: If it is known whether this content contains
 218          *    links, provide this information here, to avoid redundant parsing to
 219          *    find out.
 220          * @return boolean
 221          */
 222         public function isCountable( $hasLinks = null );
 223
 224
 225         /**
 226          * Parse the Content object and generate a ParserOutput from the result.
 227          * $result->getText() can be used to obtain the generated HTML. If no HTML
 228          * is needed, $generateHtml can be set to false; in that case,
 229          * $result->getText() may return null.
 230          *
 231          * @param $title Title The page title to use as a context for rendering
 232          * @param $revId null|int The revision being rendered (optional)
 233          * @param $options null|ParserOptions Any parser options
 234          * @param $generateHtml Boolean Whether to generate HTML (default: true). If false,
 235          *        the result of calling getText() on the ParserOutput object returned by
 236          *        this method is undefined.
 237          *
 238          * @since 1.21
 239          *
 240          * @return ParserOutput
 241          */
 242         public function getParserOutput( Title $title,
 243                 $revId = null,
 244                 ParserOptions $options = null, $generateHtml = true );
 245         # TODO: make RenderOutput and RenderOptions base classes
 246
 247         /**
 248          * Returns a list of DataUpdate objects for recording information about this
 249          * Content in some secondary data store. If the optional second argument,
 250          * $old, is given, the updates may model only the changes that need to be
 251          * made to replace information about the old content with information about
 252          * the new content.
 253          *
 254          * This default implementation calls
 255          * $this->getParserOutput( $content, $title, null, null, false ),
 256          * and then calls getSecondaryDataUpdates( $title, $recursive ) on the
 257          * resulting ParserOutput object.
 258          *
 259          * Subclasses may implement this to determine the necessary updates more
 260          * efficiently, or make use of information about the old content.
 261          *
 262          * @param $title Title The context for determining the necessary updates
 263          * @param $old Content|null An optional Content object representing the
 264          *    previous content, i.e. the content being replaced by this Content
 265          *    object.
 266          * @param $recursive boolean Whether to include recursive updates (default:
 267          *    false).
 268          * @param $parserOutput ParserOutput|null Optional ParserOutput object.
 269          *    Provide if you have one handy, to avoid re-parsing of the content.
 270          *
 271          * @return Array. A list of DataUpdate objects for putting information
 272          *    about this content object somewhere.
 273          *
 274          * @since 1.21
 275          */
 276         public function getSecondaryDataUpdates( Title $title,
 277                 Content $old = null,
 278                 $recursive = true, ParserOutput $parserOutput = null
 279         );
 280
 281         /**
 282          * Construct the redirect destination from this content and return an
 283          * array of Titles, or null if this content doesn't represent a redirect.
 284          * The last element in the array is the final destination after all redirects
 285          * have been resolved (up to $wgMaxRedirects times).
 286          *
 287          * @since 1.21
 288          *
 289          * @return Array of Titles, with the destination last
 290          */
 291         public function getRedirectChain();
 292
 293         /**
 294          * Construct the redirect destination from this content and return a Title,
 295          * or null if this content doesn't represent a redirect.
 296          * This will only return the immediate redirect target, useful for
 297          * the redirect table and other checks that don't need full recursion.
 298          *
 299          * @since 1.21
 300          *
 301          * @return Title: The corresponding Title
 302          */
 303         public function getRedirectTarget();
 304
 305         /**
 306          * Construct the redirect destination from this content and return the
 307          * Title, or null if this content doesn't represent a redirect.
 308          *
 309          * This will recurse down $wgMaxRedirects times or until a non-redirect
 310          * target is hit in order to provide (hopefully) the Title of the final
 311          * destination instead of another redirect.
 312          *
 313          * There is usually no need to override the default behaviour, subclasses that
 314          * want to implement redirects should override getRedirectTarget().
 315          *
 316          * @since 1.21
 317          *
 318          * @return Title
 319          */
 320         public function getUltimateRedirectTarget();
 321
 322         /**
 323          * Returns whether this Content represents a redirect.
 324          * Shorthand for getRedirectTarget() !== null.
 325          *
 326          * @since 1.21
 327          *
 328          * @return bool
 329          */
 330         public function isRedirect();
 331
 332         /**
 333          * If this Content object is a redirect, this method updates the redirect target.
 334          * Otherwise, it does nothing.
 335          *
 336          * @since 1.21
 337          *
 338          * @param Title $target the new redirect target
 339          *
 340          * @return Content a new Content object with the updated redirect (or $this if this Content object isn't a redirect)
 341          */
 342         public function updateRedirect( Title $target );
 343
 344         /**
 345          * Returns the section with the given ID.
 346          *
 347          * @since 1.21
 348          *
 349          * @param $sectionId string The section's ID, given as a numeric string.
 350          *    The ID "0" retrieves the section before the first heading, "1" the
 351          *    text between the first heading (included) and the second heading
 352          *    (excluded), etc.
 353          * @return Content|Boolean|null The section, or false if no such section
 354          *    exist, or null if sections are not supported.
 355          */
 356         public function getSection( $sectionId );
 357
 358         /**
 359          * Replaces a section of the content and returns a Content object with the
 360          * section replaced.
 361          *
 362          * @since 1.21
 363          *
 364          * @param $section Empty/null/false or a section number (0, 1, 2, T1, T2...), or "new"
 365          * @param $with Content: new content of the section
 366          * @param $sectionTitle String: new section's subject, only if $section is 'new'
 367          * @return string Complete article text, or null if error
 368          */
 369         public function replaceSection( $section, Content $with, $sectionTitle = ''  );
 370
 371         /**
 372          * Returns a Content object with pre-save transformations applied (or this
 373          * object if no transformations apply).
 374          *
 375          * @since 1.21
 376          *
 377          * @param $title Title
 378          * @param $user User
 379          * @param $popts null|ParserOptions
 380          * @return Content
 381          */
 382         public function preSaveTransform( Title $title, User $user, ParserOptions $popts );
 383
 384         /**
 385          * Returns a new WikitextContent object with the given section heading
 386          * prepended, if supported. The default implementation just returns this
 387          * Content object unmodified, ignoring the section header.
 388          *
 389          * @since 1.21
 390          *
 391          * @param $header string
 392          * @return Content
 393          */
 394         public function addSectionHeader( $header );
 395
 396         /**
 397          * Returns a Content object with preload transformations applied (or this
 398          * object if no transformations apply).
 399          *
 400          * @since 1.21
 401          *
 402          * @param $title Title
 403          * @param $popts null|ParserOptions
 404          * @return Content
 405          */
 406         public function preloadTransform( Title $title, ParserOptions $popts );
 407
 408         /**
 409          * Prepare Content for saving. Called before Content is saved by WikiPage::doEditContent() and in
 410          * similar places.
 411          *
 412          * This may be used to check the content's consistency with global state. This function should
 413          * NOT write any information to the database.
 414          *
 415          * Note that this method will usually be called inside the same transaction bracket that will be used
 416          * to save the new revision.
 417          *
 418          * Note that this method is called before any update to the page table is performed. This means that
 419          * $page may not yet know a page ID.
 420          *
 421          * @since 1.21
 422          *
 423          * @param WikiPage $page The page to be saved.
 424          * @param int      $flags bitfield for use with EDIT_XXX constants, see WikiPage::doEditContent()
 425          * @param int      $baseRevId the ID of the current revision
 426          * @param User     $user
 427          *
 428          * @return Status A status object indicating whether the content was successfully prepared for saving.
 429          *                If the returned status indicates an error, a rollback will be performed and the
 430          *                transaction aborted.
 431          *
 432          * @see see WikiPage::doEditContent()
 433          */
 434         public function prepareSave( WikiPage $page, $flags, $baseRevId, User $user );
 435
 436         /**
 437          * Returns a list of updates to perform when this content is deleted.
 438          * The necessary updates may be taken from the Content object, or depend on
 439          * the current state of the database.
 440          *
 441          * @since 1.21
 442          *
 443          * @param $page \WikiPage the deleted page
 444          * @param $parserOutput null|\ParserOutput optional parser output object
 445          *    for efficient access to meta-information about the content object.
 446          *    Provide if you have one handy.
 447          *
 448          * @return array A list of DataUpdate instances that will clean up the
 449          *    database after deletion.
 450          */
 451         public function getDeletionUpdates( WikiPage $page,
 452                 ParserOutput $parserOutput = null );
 453
 454         /**
 455          * Returns true if this Content object matches the given magic word.
 456          *
 457          * @since 1.21
 458          *
 459          * @param MagicWord $word the magic word to match
 460          *
 461          * @return bool whether this Content object matches the given magic word.
 462          */
 463         public function matchMagicWord( MagicWord $word );
 464
 465         # TODO: ImagePage and CategoryPage interfere with per-content action handlers
 466         # TODO: nice&sane integration of GeSHi syntax highlighting
 467         #   [11:59] <vvv> Hooks are ugly; make CodeHighlighter interface and a
 468         #   config to set the class which handles syntax highlighting
 469         #   [12:00] <vvv> And default it to a DummyHighlighter
 470 }