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