includes/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.WD
   7  */
   8 interface Content {
   9
  10         /**
  11          * @since WD.1
  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 WD.1
  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 WD.1
  41          *
  42          * @param $maxlength int Maximum length of the summary text
  43          * @return   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 WD.1
  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: review all calls carefully, 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 WD.1
  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 WD.1
  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 WD.1
  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 WD.1
 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 WD.1
 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 WD.1
 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 WD.1
 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 WD.1
 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->getModelName() != $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 WD.1
 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 WD.1
 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 WD.1
 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 WD.1
 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 WD.1
 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 WD.1
 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 WD.1
 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 WD.1
 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 WD.1
 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 WD.1
 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 WD.1
 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 WD.1
 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 WD.1
 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 WD.1
 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 WD.1
 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          * @param WikiPage $page The page to be saved.
 422          * @param int      $flags bitfield for use with EDIT_XXX constants, see WikiPage::doEditContent()
 423          * @param int      $baseRevId the ID of the current revision
 424          * @param User     $user
 425          *
 426          * @return Status A status object indicating whether the content was successfully prepared for saving.
 427          *                If the returned status indicates an error, a rollback will be performed and the
 428          *                transaction aborted.
 429          *
 430          * @see see WikiPage::doEditContent()
 431          */
 432         public function prepareSave( WikiPage $page, $flags, $baseRevId, User $user );
 433
 434         /**
 435          * Returns a list of updates to perform when this content is deleted.
 436          * The necessary updates may be taken from the Content object, or depend on
 437          * the current state of the database.
 438          *
 439          * @since WD.1
 440          *
 441          * @param $title \Title the title of the deleted page
 442          * @param $parserOutput null|\ParserOutput optional parser output object
 443          *    for efficient access to meta-information about the content object.
 444          *    Provide if you have one handy.
 445          *
 446          * @return array A list of DataUpdate instances that will clean up the
 447          *    database after deletion.
 448          */
 449         public function getDeletionUpdates( Title $title,
 450                 ParserOutput $parserOutput = null );
 451
 452         /**
 453          * Returns true if this Content object matches the given magic word.
 454          *
 455          * @param MagicWord $word the magic word to match
 456          *
 457          * @return bool whether this Content object matches the given magic word.
 458          */
 459         public function matchMagicWord( MagicWord $word );
 460
 461         # TODO: handle ImagePage and CategoryPage
 462         # TODO: make sure we cover lucene search / wikisearch.
 463         # TODO: make sure ReplaceTemplates still works
 464         # FUTURE: nice&sane integration of GeSHi syntax highlighting
 465         #   [11:59] <vvv> Hooks are ugly; make CodeHighlighter interface and a
 466         #   config to set the class which handles syntax highlighting
 467         #   [12:00] <vvv> And default it to a DummyHighlighter
 468
 469         # TODO: make sure we cover the external editor interface (does anyone actually use that?!)
 470
 471         # TODO: tie into API to provide contentModel for Revisions
 472         # TODO: tie into API to provide serialized version and contentFormat for Revisions
 473         # TODO: tie into API edit interface
 474         # FUTURE: make EditForm plugin for EditPage
 475
 476         # FUTURE: special type for redirects?!
 477         # FUTURE: MultipartMultipart < WikipageContent (Main + Links + X)
 478         # FUTURE: LinksContent < LanguageLinksContent, CategoriesContent
 479 }
 480
 481
 482 /**
 483  * A content object represents page content, e.g. the text to show on a page.
 484  * Content objects have no knowledge about how they relate to Wiki pages.
 485  *
 486  * @since 1.WD
 487  */
 488 abstract class AbstractContent implements Content {
 489
 490         /**
 491          * Name of the content model this Content object represents.
 492          * Use with CONTENT_MODEL_XXX constants
 493          *
 494          * @var string $model_id
 495          */
 496         protected $model_id;
 497
 498         /**
 499          * @param String $model_id
 500          */
 501         public function __construct( $model_id = null ) {
 502                 $this->model_id = $model_id;
 503         }
 504
 505         /**
 506          * @see Content::getModel()
 507          */
 508         public function getModel() {
 509                 return $this->model_id;
 510         }
 511
 512         /**
 513          * Throws an MWException if $model_id is not the id of the content model
 514          * supported by this Content object.
 515          *
 516          * @param $model_id int the model to check
 517          *
 518          * @throws MWException
 519          */
 520         protected function checkModelID( $model_id ) {
 521                 if ( $model_id !== $this->model_id ) {
 522                         throw new MWException( "Bad content model: " .
 523                                 "expected {$this->model_id}  " .
 524                                 "but got $model_id." );
 525                 }
 526         }
 527
 528         /**
 529          * @see Content::getContentHandler()
 530          */
 531         public function getContentHandler() {
 532                 return ContentHandler::getForContent( $this );
 533         }
 534
 535         /**
 536          * @see Content::getDefaultFormat()
 537          */
 538         public function getDefaultFormat() {
 539                 return $this->getContentHandler()->getDefaultFormat();
 540         }
 541
 542         /**
 543          * @see Content::getSupportedFormats()
 544          */
 545         public function getSupportedFormats() {
 546                 return $this->getContentHandler()->getSupportedFormats();
 547         }
 548
 549         /**
 550          * @see Content::isSupportedFormat()
 551          */
 552         public function isSupportedFormat( $format ) {
 553                 if ( !$format ) {
 554                         return true; // this means "use the default"
 555                 }
 556
 557                 return $this->getContentHandler()->isSupportedFormat( $format );
 558         }
 559
 560         /**
 561          * Throws an MWException if $this->isSupportedFormat( $format ) doesn't
 562          * return true.
 563          *
 564          * @param $format
 565          * @throws MWException
 566          */
 567         protected function checkFormat( $format ) {
 568                 if ( !$this->isSupportedFormat( $format ) ) {
 569                         throw new MWException( "Format $format is not supported for content model " .
 570                                 $this->getModel() );
 571                 }
 572         }
 573
 574         /**
 575          * @see Content::serialize
 576          */
 577         public function serialize( $format = null ) {
 578                 return $this->getContentHandler()->serializeContent( $this, $format );
 579         }
 580
 581         /**
 582          * @see Content::isEmpty()
 583          */
 584         public function isEmpty() {
 585                 return $this->getSize() == 0;
 586         }
 587
 588         /**
 589          * @see Content::isValid()
 590          */
 591         public function isValid() {
 592                 return true;
 593         }
 594
 595         /**
 596          * @see Content::equals()
 597          */
 598         public function equals( Content $that = null ) {
 599                 if ( is_null( $that ) ) {
 600                         return false;
 601                 }
 602
 603                 if ( $that === $this ) {
 604                         return true;
 605                 }
 606
 607                 if ( $that->getModel() !== $this->getModel() ) {
 608                         return false;
 609                 }
 610
 611                 return $this->getNativeData() === $that->getNativeData();
 612         }
 613
 614
 615         /**
 616          * Returns a list of DataUpdate objects for recording information about this
 617          * Content in some secondary data store.
 618          *
 619          * This default implementation calls
 620          * $this->getParserOutput( $content, $title, null, null, false ),
 621          * and then calls getSecondaryDataUpdates( $title, $recursive ) on the
 622          * resulting ParserOutput object.
 623          *
 624          * Subclasses may override this to determine the secondary data updates more
 625          * efficiently, preferrably without the need to generate a parser output object.
 626          *
 627          * @see Content::getSecondaryDataUpdates()
 628          *
 629          * @param $title Title The context for determining the necessary updates
 630          * @param $old Content|null An optional Content object representing the
 631          *    previous content, i.e. the content being replaced by this Content
 632          *    object.
 633          * @param $recursive boolean Whether to include recursive updates (default:
 634          *    false).
 635          * @param $parserOutput ParserOutput|null Optional ParserOutput object.
 636          *    Provide if you have one handy, to avoid re-parsing of the content.
 637          *
 638          * @return Array. A list of DataUpdate objects for putting information
 639          *    about this content object somewhere.
 640          *
 641          * @since WD.1
 642          */
 643         public function getSecondaryDataUpdates( Title $title,
 644                 Content $old = null,
 645                 $recursive = true, ParserOutput $parserOutput = null
 646         ) {
 647                 if ( !$parserOutput ) {
 648                         $parserOutput = $this->getParserOutput( $title, null, null, false );
 649                 }
 650
 651                 return $parserOutput->getSecondaryDataUpdates( $title, $recursive );
 652         }
 653
 654
 655         /**
 656          * @see Content::getRedirectChain()
 657          */
 658         public function getRedirectChain() {
 659                 global $wgMaxRedirects;
 660                 $title = $this->getRedirectTarget();
 661                 if ( is_null( $title ) ) {
 662                         return null;
 663                 }
 664                 // recursive check to follow double redirects
 665                 $recurse = $wgMaxRedirects;
 666                 $titles = array( $title );
 667                 while ( --$recurse > 0 ) {
 668                         if ( $title->isRedirect() ) {
 669                                 $page = WikiPage::factory( $title );
 670                                 $newtitle = $page->getRedirectTarget();
 671                         } else {
 672                                 break;
 673                         }
 674                         // Redirects to some special pages are not permitted
 675                         if ( $newtitle instanceOf Title && $newtitle->isValidRedirectTarget() ) {
 676                                 // The new title passes the checks, so make that our current
 677                                 // title so that further recursion can be checked
 678                                 $title = $newtitle;
 679                                 $titles[] = $newtitle;
 680                         } else {
 681                                 break;
 682                         }
 683                 }
 684                 return $titles;
 685         }
 686
 687         /**
 688          * @see Content::getRedirectTarget()
 689          */
 690         public function getRedirectTarget() {
 691                 return null;
 692         }
 693
 694         /**
 695          * @see Content::getUltimateRedirectTarget()
 696          * @note: migrated here from Title::newFromRedirectRecurse
 697          */
 698         public function getUltimateRedirectTarget() {
 699                 $titles = $this->getRedirectChain();
 700                 return $titles ? array_pop( $titles ) : null;
 701         }
 702
 703         /**
 704          * @see Content::isRedirect()
 705          *
 706          * @since WD.1
 707          *
 708          * @return bool
 709          */
 710         public function isRedirect() {
 711                 return $this->getRedirectTarget() !== null;
 712         }
 713
 714         /**
 715          * @see Content::updateRedirect()
 716          *
 717          * This default implementation always returns $this.
 718          *
 719          * @since WD.1
 720          *
 721          * @return Content $this
 722          */
 723         public function updateRedirect( Title $target ) {
 724                 return $this;
 725         }
 726
 727         /**
 728          * @see Content::getSection()
 729          */
 730         public function getSection( $sectionId ) {
 731                 return null;
 732         }
 733
 734         /**
 735          * @see Content::replaceSection()
 736          */
 737         public function replaceSection( $section, Content $with, $sectionTitle = ''  ) {
 738                 return null;
 739         }
 740
 741         /**
 742          * @see Content::preSaveTransform()
 743          */
 744         public function preSaveTransform( Title $title, User $user, ParserOptions $popts ) {
 745                 return $this;
 746         }
 747
 748         /**
 749          * @see Content::addSectionHeader()
 750          */
 751         public function addSectionHeader( $header ) {
 752                 return $this;
 753         }
 754
 755         /**
 756          * @see Content::preloadTransform()
 757          */
 758         public function preloadTransform( Title $title, ParserOptions $popts ) {
 759                 return $this;
 760         }
 761
 762         /**
 763          * @see  Content::prepareSave()
 764          */
 765         public function prepareSave( WikiPage $page, $flags, $baseRevId, User $user ) {
 766                 if ( $this->isValid() ) {
 767                         return Status::newGood();
 768                 } else {
 769                         return Status::newFatal( "invalid-content-data" );
 770                 }
 771         }
 772
 773         /**
 774          * @see  Content::getDeletionUpdates()
 775          *
 776          * @since WD.1
 777          *
 778          * @param $title \Title the title of the deleted page
 779          * @param $parserOutput null|\ParserOutput optional parser output object
 780          *    for efficient access to meta-information about the content object.
 781          *    Provide if you have one handy.
 782          *
 783          * @return array A list of DataUpdate instances that will clean up the
 784          *    database after deletion.
 785          */
 786         public function getDeletionUpdates( Title $title,
 787                 ParserOutput $parserOutput = null )
 788         {
 789                 return array(
 790                         new LinksDeletionUpdate( $title ),
 791                 );
 792         }
 793
 794         /**
 795          * @see  Content::matchMagicWord()
 796          *
 797          * This default implementation always returns false. Subclasses may override this to supply matching logic.
 798          *
 799          * @param MagicWord $word
 800          *
 801          * @return bool
 802          */
 803         public function matchMagicWord( MagicWord $word ) {
 804                 return false;
 805         }
 806 }
 807
 808 /**
 809  * Content object implementation for representing flat text.
 810  *
 811  * TextContent instances are immutable
 812  *
 813  * @since WD.1
 814  */
 815 abstract class TextContent extends AbstractContent {
 816
 817         public function __construct( $text, $model_id = null ) {
 818                 parent::__construct( $model_id );
 819
 820                 $this->mText = $text;
 821         }
 822
 823         public function copy() {
 824                 return $this; # NOTE: this is ok since TextContent are immutable.
 825         }
 826
 827         public function getTextForSummary( $maxlength = 250 ) {
 828                 global $wgContLang;
 829
 830                 $text = $this->getNativeData();
 831
 832                 $truncatedtext = $wgContLang->truncate(
 833                         preg_replace( "/[\n\r]/", ' ', $text ),
 834                         max( 0, $maxlength ) );
 835
 836                 return $truncatedtext;
 837         }
 838
 839         /**
 840          * returns the text's size in bytes.
 841          *
 842          * @return int The size
 843          */
 844         public function getSize( ) {
 845                 $text = $this->getNativeData( );
 846                 return strlen( $text );
 847         }
 848
 849         /**
 850          * Returns true if this content is not a redirect, and $wgArticleCountMethod
 851          * is "any".
 852          *
 853          * @param $hasLinks Bool: if it is known whether this content contains links,
 854          * provide this information here, to avoid redundant parsing to find out.
 855          *
 856          * @return bool True if the content is countable
 857          */
 858         public function isCountable( $hasLinks = null ) {
 859                 global $wgArticleCountMethod;
 860
 861                 if ( $this->isRedirect( ) ) {
 862                         return false;
 863                 }
 864
 865                 if (  $wgArticleCountMethod === 'any' ) {
 866                         return true;
 867                 }
 868
 869                 return false;
 870         }
 871
 872         /**
 873          * Returns the text represented by this Content object, as a string.
 874          *
 875          * @param   the raw text
 876          */
 877         public function getNativeData( ) {
 878                 $text = $this->mText;
 879                 return $text;
 880         }
 881
 882         /**
 883          * Returns the text represented by this Content object, as a string.
 884          *
 885          * @param   the raw text
 886          */
 887         public function getTextForSearchIndex( ) {
 888                 return $this->getNativeData();
 889         }
 890
 891         /**
 892          * Returns the text represented by this Content object, as a string.
 893          *
 894          * @param   the raw text
 895          */
 896         public function getWikitextForTransclusion( ) {
 897                 return $this->getNativeData();
 898         }
 899
 900         /**
 901          * Diff this content object with another content object..
 902          *
 903          * @since WD.diff
 904          *
 905          * @param $that Content the other content object to compare this content object to
 906          * @param $lang Language the language object to use for text segmentation.
 907          *    If not given, $wgContentLang is used.
 908          *
 909          * @return DiffResult a diff representing the changes that would have to be
 910          *    made to this content object to make it equal to $that.
 911          */
 912         public function diff( Content $that, Language $lang = null ) {
 913                 global $wgContLang;
 914
 915                 $this->checkModelID( $that->getModel() );
 916
 917                 # @todo: could implement this in DifferenceEngine and just delegate here?
 918
 919                 if ( !$lang ) $lang = $wgContLang;
 920
 921                 $otext = $this->getNativeData();
 922                 $ntext = $this->getNativeData();
 923
 924                 # Note: Use native PHP diff, external engines don't give us abstract output
 925                 $ota = explode( "\n", $wgContLang->segmentForDiff( $otext ) );
 926                 $nta = explode( "\n", $wgContLang->segmentForDiff( $ntext ) );
 927
 928                 $diff = new Diff( $ota, $nta );
 929                 return $diff;
 930         }
 931
 932
 933         /**
 934          * Returns a generic ParserOutput object, wrapping the HTML returned by
 935          * getHtml().
 936          *
 937          * @param $title Title Context title for parsing
 938          * @param $revId int|null Revision ID (for {{REVISIONID}})
 939          * @param $options ParserOptions|null Parser options
 940          * @param $generateHtml bool Whether or not to generate HTML
 941          *
 942          * @return ParserOutput representing the HTML form of the text
 943          */
 944         public function getParserOutput( Title $title,
 945                 $revId = null,
 946                 ParserOptions $options = null, $generateHtml = true
 947         ) {
 948                 # Generic implementation, relying on $this->getHtml()
 949
 950                 if ( $generateHtml ) {
 951                         $html = $this->getHtml();
 952                 } else {
 953                         $html = '';
 954                 }
 955
 956                 $po = new ParserOutput( $html );
 957                 return $po;
 958         }
 959
 960         /**
 961          * Generates an HTML version of the content, for display. Used by
 962          * getParserOutput() to construct a ParserOutput object.
 963          *
 964          * This default implementation just calls getHighlightHtml(). Content
 965          * models that have another mapping to HTML (as is the case for markup
 966          * languages like wikitext) should override this method to generate the
 967          * appropriate HTML.
 968          *
 969          * @return string An HTML representation of the content
 970          */
 971         protected function getHtml() {
 972                 return $this->getHighlightHtml();
 973         }
 974
 975         /**
 976          * Generates a syntax-highlighted version of the content, as HTML.
 977          * Used by the default implementation of getHtml().
 978          *
 979          * @return string an HTML representation of the content's markup
 980          */
 981         protected function getHighlightHtml( ) {
 982                 # TODO: make Highlighter interface, use highlighter here, if available
 983                 return htmlspecialchars( $this->getNativeData() );
 984         }
 985 }
 986
 987 /**
 988  * @since WD.1
 989  */
 990 class WikitextContent extends TextContent {
 991
 992         public function __construct( $text ) {
 993                 parent::__construct( $text, CONTENT_MODEL_WIKITEXT );
 994         }
 995
 996         /**
 997          * @see Content::getSection()
 998          */
 999         public function getSection( $section ) {
1000                 global $wgParser;
1001
1002                 $text = $this->getNativeData();
1003                 $sect = $wgParser->getSection( $text, $section, false );
1004
1005                 return  new WikitextContent( $sect );
1006         }
1007
1008         /**
1009          * @see Content::replaceSection()
1010          */
1011         public function replaceSection( $section, Content $with, $sectionTitle = '' ) {
1012                 wfProfileIn( __METHOD__ );
1013
1014                 $myModelId = $this->getModel();
1015                 $sectionModelId = $with->getModel();
1016
1017                 if ( $sectionModelId != $myModelId  ) {
1018                         throw new MWException( "Incompatible content model for section: " .
1019                                 "document uses $myModelId but " .
1020                                 "section uses $sectionModelId." );
1021                 }
1022
1023                 $oldtext = $this->getNativeData();
1024                 $text = $with->getNativeData();
1025
1026                 if ( $section === '' ) {
1027                         return $with; # XXX: copy first?
1028                 } if ( $section == 'new' ) {
1029                         # Inserting a new section
1030                         if ( $sectionTitle ) {
1031                                 $subject = wfMessage( 'newsectionheaderdefaultlevel' )
1032                                                         ->inContentLanguage()->params( $sectionTitle )->text();
1033                                 $subject .= "\n\n";
1034                         } else {
1035                                 $subject = '';
1036                         }
1037                         if ( wfRunHooks( 'PlaceNewSection', array( $this, $oldtext, $subject, &$text ) ) ) {
1038                                 $text = strlen( trim( $oldtext ) ) > 0
1039                                         ? "{$oldtext}\n\n{$subject}{$text}"
1040                                         : "{$subject}{$text}";
1041                         }
1042                 } else {
1043                         # Replacing an existing section; roll out the big guns
1044                         global $wgParser;
1045
1046                         $text = $wgParser->replaceSection( $oldtext, $section, $text );
1047                 }
1048
1049                 $newContent = new WikitextContent( $text );
1050
1051                 wfProfileOut( __METHOD__ );
1052                 return $newContent;
1053         }
1054
1055         /**
1056          * Returns a new WikitextContent object with the given section heading
1057          * prepended.
1058          *
1059          * @param $header string
1060          * @return Content
1061          */
1062         public function addSectionHeader( $header ) {
1063                 $text = wfMessage( 'newsectionheaderdefaultlevel' )
1064                                 ->inContentLanguage()->params( $header )->text();
1065                 $text .= "\n\n";
1066                 $text .= $this->getNativeData();
1067
1068                 return new WikitextContent( $text );
1069         }
1070
1071         /**
1072          * Returns a Content object with pre-save transformations applied using
1073          * Parser::preSaveTransform().
1074          *
1075          * @param $title Title
1076          * @param $user User
1077          * @param $popts ParserOptions
1078          * @return Content
1079          */
1080         public function preSaveTransform( Title $title, User $user, ParserOptions $popts ) {
1081                 global $wgParser;
1082
1083                 $text = $this->getNativeData();
1084                 $pst = $wgParser->preSaveTransform( $text, $title, $user, $popts );
1085
1086                 return new WikitextContent( $pst );
1087         }
1088
1089         /**
1090          * Returns a Content object with preload transformations applied (or this
1091          * object if no transformations apply).
1092          *
1093          * @param $title Title
1094          * @param $popts ParserOptions
1095          * @return Content
1096          */
1097         public function preloadTransform( Title $title, ParserOptions $popts ) {
1098                 global $wgParser;
1099
1100                 $text = $this->getNativeData();
1101                 $plt = $wgParser->getPreloadText( $text, $title, $popts );
1102
1103                 return new WikitextContent( $plt );
1104         }
1105
1106         /**
1107          * Implement redirect extraction for wikitext.
1108          *
1109          * @return null|Title
1110          *
1111          * @note: migrated here from Title::newFromRedirectInternal()
1112          *
1113          * @see Content::getRedirectTarget
1114          * @see AbstractContent::getRedirectTarget
1115          */
1116         public function getRedirectTarget() {
1117                 global $wgMaxRedirects;
1118                 if ( $wgMaxRedirects < 1 ) {
1119                         // redirects are disabled, so quit early
1120                         return null;
1121                 }
1122                 $redir = MagicWord::get( 'redirect' );
1123                 $text = trim( $this->getNativeData() );
1124                 if ( $redir->matchStartAndRemove( $text ) ) {
1125                         // Extract the first link and see if it's usable
1126                         // Ensure that it really does come directly after #REDIRECT
1127                         // Some older redirects included a colon, so don't freak about that!
1128                         $m = array();
1129                         if ( preg_match( '!^\s*:?\s*\[{2}(.*?)(?:\|.*?)?\]{2}!', $text, $m ) ) {
1130                                 // Strip preceding colon used to "escape" categories, etc.
1131                                 // and URL-decode links
1132                                 if ( strpos( $m[1], '%' ) !== false ) {
1133                                         // Match behavior of inline link parsing here;
1134                                         $m[1] = rawurldecode( ltrim( $m[1], ':' ) );
1135                                 }
1136                                 $title = Title::newFromText( $m[1] );
1137                                 // If the title is a redirect to bad special pages or is invalid, return null
1138                                 if ( !$title instanceof Title || !$title->isValidRedirectTarget() ) {
1139                                         return null;
1140                                 }
1141                                 return $title;
1142                         }
1143                 }
1144                 return null;
1145         }
1146
1147         /**
1148          * @see   Content::updateRedirect()
1149          *
1150          * This implementation replaces the first link on the page with the given new target
1151          * if this Content object is a redirect. Otherwise, this method returns $this.
1152          *
1153          * @since WD.1
1154          *
1155          * @param Title $target
1156          *
1157          * @return Content a new Content object with the updated redirect (or $this if this Content object isn't a redirect)
1158          */
1159         public function updateRedirect( Title $target ) {
1160                 if ( !$this->isRedirect() ) {
1161                         return $this;
1162                 }
1163
1164                 # Fix the text
1165                 # Remember that redirect pages can have categories, templates, etc.,
1166                 # so the regex has to be fairly general
1167                 $newText = preg_replace( '/ \[ \[  [^\]]*  \] \] /x',
1168                         '[[' . $target->getFullText() . ']]',
1169                         $this->getNativeData(), 1 );
1170
1171                 return new WikitextContent( $newText );
1172         }
1173
1174         /**
1175          * Returns true if this content is not a redirect, and this content's text
1176          * is countable according to the criteria defined by $wgArticleCountMethod.
1177          *
1178          * @param $hasLinks Bool  if it is known whether this content contains
1179          *    links, provide this information here, to avoid redundant parsing to
1180          *    find out.
1181          * @param $title null|\Title
1182          *
1183          * @internal param \IContextSource $context context for parsing if necessary
1184          *
1185          * @return bool True if the content is countable
1186          */
1187         public function isCountable( $hasLinks = null, Title $title = null ) {
1188                 global $wgArticleCountMethod;
1189
1190                 if ( $this->isRedirect( ) ) {
1191                         return false;
1192                 }
1193
1194                 $text = $this->getNativeData();
1195
1196                 switch ( $wgArticleCountMethod ) {
1197                         case 'any':
1198                                 return true;
1199                         case 'comma':
1200                                 return strpos( $text,  ',' ) !== false;
1201                         case 'link':
1202                                 if ( $hasLinks === null ) { # not known, find out
1203                                         if ( !$title ) {
1204                                                 $context = RequestContext::getMain();
1205                                                 $title = $context->getTitle();
1206                                         }
1207
1208                                         $po = $this->getParserOutput( $title, null, null, false );
1209                                         $links = $po->getLinks();
1210                                         $hasLinks = !empty( $links );
1211                                 }
1212
1213                                 return $hasLinks;
1214                 }
1215
1216                 return false;
1217         }
1218
1219         public function getTextForSummary( $maxlength = 250 ) {
1220                 $truncatedtext = parent::getTextForSummary( $maxlength );
1221
1222                 # clean up unfinished links
1223                 # XXX: make this optional? wasn't there in autosummary, but required for
1224                 # deletion summary.
1225                 $truncatedtext = preg_replace( '/\[\[([^\]]*)\]?$/', '$1', $truncatedtext );
1226
1227                 return $truncatedtext;
1228         }
1229
1230
1231         /**
1232          * Returns a ParserOutput object resulting from parsing the content's text
1233          * using $wgParser.
1234          *
1235          * @since    WD.1
1236          *
1237          * @param $content Content the content to render
1238          * @param $title \Title
1239          * @param $revId null
1240          * @param $options null|ParserOptions
1241          * @param $generateHtml bool
1242          *
1243          * @internal param \IContextSource|null $context
1244          * @return ParserOutput representing the HTML form of the text
1245          */
1246         public function getParserOutput( Title $title,
1247                 $revId = null,
1248                 ParserOptions $options = null, $generateHtml = true
1249         ) {
1250                 global $wgParser;
1251
1252                 if ( !$options ) {
1253                         $options = new ParserOptions();
1254                 }
1255
1256                 $po = $wgParser->parse( $this->getNativeData(), $title, $options, true, true, $revId );
1257                 return $po;
1258         }
1259
1260         protected function getHtml() {
1261                 throw new MWException(
1262                         "getHtml() not implemented for wikitext. "
1263                                 . "Use getParserOutput()->getText()."
1264                 );
1265         }
1266
1267         /**
1268          * @see  Content::matchMagicWord()
1269          *
1270          * This implementation calls $word->match() on the this TextContent object's text.
1271          *
1272          * @param MagicWord $word
1273          *
1274          * @return bool whether this Content object matches the given magic word.
1275          */
1276         public function matchMagicWord( MagicWord $word ) {
1277                 return $word->match( $this->getNativeData() );
1278         }
1279 }
1280
1281 /**
1282  * Wrapper allowing us to handle a system message as a Content object. Note that this is generally *not* used
1283  * to represent content from the MediaWiki namespace, and that there is no MessageContentHandler. MessageContent
1284  * is just intended as glue for wrapping a message programatically.
1285  *
1286  * @since WD.1
1287  */
1288 class MessageContent extends AbstractContent {
1289
1290         /**
1291          * @var Message
1292          */
1293         protected $mMessage;
1294
1295         /**
1296          * @param Message|String $msg    A Message object, or a message key
1297          * @param array|null     $params An optional array of message parameters
1298          */
1299         public function __construct( $msg, $params = null ) {
1300                 # XXX: messages may be wikitext, html or plain text! and maybe even something else entirely.
1301                 parent::__construct( CONTENT_MODEL_WIKITEXT );
1302
1303                 if ( is_string( $msg ) ) {
1304                         $this->mMessage = wfMessage( $msg );
1305                 } else {
1306                         $this->mMessage = clone $msg;
1307                 }
1308
1309                 if ( $params ) {
1310                         $this->mMessage = $this->mMessage->params( $params );
1311                 }
1312         }
1313
1314         /**
1315          * Returns the message as rendered HTML
1316          *
1317          * @return string The message text, parsed into html
1318          */
1319         public function getHtml() {
1320                 return $this->mMessage->parse();
1321         }
1322
1323         /**
1324          * Returns the message as rendered HTML
1325          *
1326          * @return string The message text, parsed into html
1327          */
1328         public function getWikitext() {
1329                 return $this->mMessage->text();
1330         }
1331
1332         /**
1333          * Returns the message object, with any parameters already substituted.
1334          *
1335          * @return Message The message object.
1336          */
1337         public function getNativeData() {
1338                 //NOTE: Message objects are mutable. Cloning here makes MessageContent immutable.
1339                 return clone $this->mMessage;
1340         }
1341
1342         /**
1343          * @see Content::getTextForSearchIndex
1344          */
1345         public function getTextForSearchIndex() {
1346                 return $this->mMessage->plain();
1347         }
1348
1349         /**
1350          * @see Content::getWikitextForTransclusion
1351          */
1352         public function getWikitextForTransclusion() {
1353                 return $this->getWikitext();
1354         }
1355
1356         /**
1357          * @see Content::getTextForSummary
1358          */
1359         public function getTextForSummary( $maxlength = 250 ) {
1360                 return substr( $this->mMessage->plain(), 0, $maxlength );
1361         }
1362
1363         /**
1364          * @see Content::getSize
1365          *
1366          * @return int
1367          */
1368         public function getSize() {
1369                 return strlen( $this->mMessage->plain() );
1370         }
1371
1372         /**
1373          * @see Content::copy
1374          *
1375          * @return Content. A copy of this object
1376          */
1377         public function copy() {
1378                 // MessageContent is immutable (because getNativeData() returns a clone of the Message object)
1379                 return $this;
1380         }
1381
1382         /**
1383          * @see Content::isCountable
1384          *
1385          * @return bool false
1386          */
1387         public function isCountable( $hasLinks = null ) {
1388                 return false;
1389         }
1390
1391         /**
1392          * @see Content::getParserOutput
1393          *
1394          * @return ParserOutput
1395          */
1396         public function getParserOutput(
1397                 Title $title, $revId = null,
1398                 ParserOptions $options = null, $generateHtml = true
1399         ) {
1400
1401                 if ( $generateHtml ) {
1402                         $html = $this->getHtml();
1403                 } else {
1404                         $html = '';
1405                 }
1406
1407                 $po = new ParserOutput( $html );
1408                 return $po;
1409         }
1410 }
1411
1412 /**
1413  * @since WD.1
1414  */
1415 class JavaScriptContent extends TextContent {
1416         public function __construct( $text ) {
1417                 parent::__construct( $text, CONTENT_MODEL_JAVASCRIPT );
1418         }
1419
1420         /**
1421          * Returns a Content object with pre-save transformations applied using
1422          * Parser::preSaveTransform().
1423          *
1424          * @param Title $title
1425          * @param User $user
1426          * @param ParserOptions $popts
1427          * @return Content
1428          */
1429         public function preSaveTransform( Title $title, User $user, ParserOptions $popts ) {
1430                 global $wgParser;
1431                 // @todo: make pre-save transformation optional for script pages
1432                 // See bug #32858
1433
1434                 $text = $this->getNativeData();
1435                 $pst = $wgParser->preSaveTransform( $text, $title, $user, $popts );
1436
1437                 return new JavaScriptContent( $pst );
1438         }
1439
1440
1441         protected function getHtml( ) {
1442                 $html = "";
1443                 $html .= "<pre class=\"mw-code mw-js\" dir=\"ltr\">\n";
1444                 $html .= $this->getHighlightHtml( );
1445                 $html .= "\n</pre>\n";
1446
1447                 return $html;
1448         }
1449 }
1450
1451 /**
1452  * @since WD.1
1453  */
1454 class CssContent extends TextContent {
1455         public function __construct( $text ) {
1456                 parent::__construct( $text, CONTENT_MODEL_CSS );
1457         }
1458
1459         /**
1460          * Returns a Content object with pre-save transformations applied using
1461          * Parser::preSaveTransform().
1462          *
1463          * @param $title Title
1464          * @param $user User
1465          * @param $popts ParserOptions
1466          * @return Content
1467          */
1468         public function preSaveTransform( Title $title, User $user, ParserOptions $popts ) {
1469                 global $wgParser;
1470                 // @todo: make pre-save transformation optional for script pages
1471
1472                 $text = $this->getNativeData();
1473                 $pst = $wgParser->preSaveTransform( $text, $title, $user, $popts );
1474
1475                 return new CssContent( $pst );
1476         }
1477
1478
1479         protected function getHtml( ) {
1480                 $html = "";
1481                 $html .= "<pre class=\"mw-code mw-css\" dir=\"ltr\">\n";
1482                 $html .= $this->getHighlightHtml( );
1483                 $html .= "\n</pre>\n";
1484
1485                 return $html;
1486         }
1487 }