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