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 building a full text search index.
  14          *         If no useful representation exists, this method returns an empty string.
  15          *
  16          * @todo: test that this actually works
  17          * @todo: make sure this also works with LuceneSearch / WikiSearch
  18          */
  19         public function getTextForSearchIndex( );
  20
  21         /**
  22          * @since WD.1
  23          *
  24          * @return String the wikitext to include when another page includes this  content, or false if the content is not
  25          *         includable in a wikitext page.
  26          *
  27          * @TODO: allow native handling, bypassing wikitext representation, like for includable special pages.
  28          * @TODO: use in parser, etc!
  29          */
  30         public function getWikitextForTransclusion( );
  31
  32         /**
  33          * Returns a textual representation of the content suitable for use in edit summaries and log messages.
  34          *
  35          * @since WD.1
  36          *
  37          * @param int $maxlength maximum length of the summary text
  38          * @return String the summary text
  39          */
  40         public function getTextForSummary( $maxlength = 250 );
  41
  42         /**
  43          * Returns native representation of the data. Interpretation depends on the data model used,
  44          * as given by getDataModel().
  45          *
  46          * @since WD.1
  47          *
  48          * @return mixed the native representation of the content. Could be a string, a nested array
  49          *         structure, an object, a binary blob... anything, really.
  50          *
  51          * @NOTE: review all calls carefully, caller must be aware of content model!
  52          */
  53         public function getNativeData( );
  54
  55         /**
  56          * returns the content's nominal size in bogo-bytes.
  57          *
  58          * @return int
  59          */
  60         public function getSize( );
  61
  62         /**
  63          * Returns the id of the content model used by this content objects.
  64          * Corresponds to the CONTENT_MODEL_XXX constants.
  65          *
  66          * @since WD.1
  67          *
  68          * @return int the model id
  69          */
  70         public function getModel();
  71
  72         /**
  73          * Convenience method that returns the ContentHandler singleton for handling the content
  74          * model this Content object uses.
  75          *
  76          * Shorthand for ContentHandler::getForContent( $this )
  77          *
  78          * @since WD.1
  79          *
  80          * @return ContentHandler
  81          */
  82         public function getContentHandler();
  83
  84         /**
  85          * Convenience method that returns the default serialization format for the content model
  86          * model this Content object uses.
  87          *
  88          * Shorthand for $this->getContentHandler()->getDefaultFormat()
  89          *
  90          * @since WD.1
  91          *
  92          * @return ContentHandler
  93          */
  94         public function getDefaultFormat();
  95
  96         /**
  97          * Convenience method that returns the list of serialization formats supported
  98          * for the content model model this Content object uses.
  99          *
 100          * Shorthand for $this->getContentHandler()->getSupportedFormats()
 101          *
 102          * @since WD.1
 103          *
 104          * @return array of supported serialization formats
 105          */
 106         public function getSupportedFormats();
 107
 108         /**
 109          * Returns true if $format is a supported serialization format for this Content object,
 110          * false if it isn't.
 111          *
 112          * Note that this should always return true if $format is null, because null stands for the
 113          * default serialization.
 114          *
 115          * Shorthand for $this->getContentHandler()->isSupportedFormat( $format )
 116          *
 117          * @since WD.1
 118          *
 119          * @param String $format the format to check
 120          * @return bool whether the format is supported
 121          */
 122         public function isSupportedFormat( $format );
 123
 124         /**
 125          * Convenience method for serializing this Content object.
 126          *
 127          * Shorthand for $this->getContentHandler()->serializeContent( $this, $format )
 128          *
 129          * @since WD.1
 130          *
 131          * @param null|String $format the desired serialization format (or null for the default format).
 132          * @return String serialized form of this Content object
 133          */
 134         public function serialize( $format = null );
 135
 136         /**
 137          * Returns true if this Content object represents empty content.
 138          *
 139          * @since WD.1
 140          *
 141          * @return bool whether this Content object is empty
 142          */
 143         public function isEmpty();
 144
 145         /**
 146          * Returns whether the content is valid. This is intended for local validity checks, not considering global consistency.
 147          * Content needs to be valid before it can be saved.
 148          *
 149          * This default implementation always returns true.
 150          *
 151          * @since WD.1
 152          *
 153          * @return boolean
 154          */
 155         public function isValid();
 156
 157         /**
 158          * Returns true if this Content objects is conceptually equivalent to the given Content object.
 159          * Contract:
 160          *
 161          * * Will return false if $that is null.
 162          * * Will return true if $that === $this.
 163          * * Will return false if $that->getModelName() != $this->getModel().
 164          * * Will return false if $that->getNativeData() is not equal to $this->getNativeData(),
 165          *   where the meaning of "equal" depends on the actual data model.
 166          *
 167          * Implementations should be careful to make equals() transitive and reflexive:
 168          *
 169          * * $a->equals( $b ) <=> $b->equals( $a )
 170          * * $a->equals( $b ) &&  $b->equals( $c ) ==> $a->equals( $c )
 171          *
 172          * @since WD.1
 173          *
 174          * @param Content $that the Content object to compare to
 175          * @return bool true if this Content object is equal to $that, false otherwise.
 176          */
 177         public function equals( Content $that = null );
 178
 179         /**
 180          * Return a copy of this Content object. The following must be true for the object returned
 181          * if $copy = $original->copy()
 182          *
 183          * * get_class($original) === get_class($copy)
 184          * * $original->getModel() === $copy->getModel()
 185          * * $original->equals( $copy )
 186          *
 187          * If and only if the Content object is immutable, the copy() method can and should
 188          * return $this. That is,  $copy === $original may be true, but only for immutable content
 189          * objects.
 190          *
 191          * @since WD.1
 192          *
 193          * @return Content. A copy of this object
 194          */
 195         public function copy( );
 196
 197         /**
 198          * Returns true if this content is countable as a "real" wiki page, provided
 199          * that it's also in a countable location (e.g. a current revision in the main namespace).
 200          *
 201          * @since WD.1
 202          *
 203          * @param $hasLinks Bool: if it is known whether this content contains links, provide this information here,
 204          *                        to avoid redundant parsing to find out.
 205          * @return boolean
 206          */
 207         public function isCountable( $hasLinks = null ) ;
 208
 209         /**
 210          * Convenience method, shorthand for
 211          * $this->getContentHandler()->getParserOutput( $this, $title, $revId, $options, $generateHtml )
 212          *
 213          * @note: subclasses should NOT override this to provide custom rendering.
 214          *        Override ContentHandler::getParserOutput() instead!
 215          *
 216          * @param Title $title
 217          * @param null $revId
 218          * @param null|ParserOptions $options
 219          * @param Boolean $generateHtml whether to generate Html (default: true). If false,
 220          *        the result of calling getText() on the ParserOutput object returned by
 221          *        this method is undefined.
 222          *
 223          * @since WD.1
 224          *
 225          * @return ParserOutput
 226          */
 227         public function getParserOutput( Title $title, $revId = null, ParserOptions $options = null, $generateHtml = true );
 228
 229         /**
 230          * Construct the redirect destination from this content and return an
 231          * array of Titles, or null if this content doesn't represent a redirect.
 232          * The last element in the array is the final destination after all redirects
 233          * have been resolved (up to $wgMaxRedirects times).
 234          *
 235          * @since WD.1
 236          *
 237          * @return Array of Titles, with the destination last
 238          */
 239         public function getRedirectChain();
 240
 241         /**
 242          * Construct the redirect destination from this content and return a Title,
 243          * or null if this content doesn't represent a redirect.
 244          * This will only return the immediate redirect target, useful for
 245          * the redirect table and other checks that don't need full recursion.
 246          *
 247          * @since WD.1
 248          *
 249          * @return Title: The corresponding Title
 250          */
 251         public function getRedirectTarget();
 252
 253         /**
 254          * Construct the redirect destination from this content and return the
 255          * Title, or null if this content doesn't represent a redirect.
 256          * This will recurse down $wgMaxRedirects times or until a non-redirect target is hit
 257          * in order to provide (hopefully) the Title of the final destination instead of another redirect.
 258          *
 259          * @since WD.1
 260          *
 261          * @return Title
 262          */
 263         public function getUltimateRedirectTarget();
 264
 265         /**
 266          * Returns whether this Content represents a redirect.
 267          * Shorthand for getRedirectTarget() !== null.
 268          *
 269          * @since WD.1
 270          *
 271          * @return bool
 272          */
 273         public function isRedirect();
 274
 275         /**
 276          * Returns the section with the given id.
 277          *
 278          * @since WD.1
 279          *
 280          * @param String $sectionId the section's id, given as a numeric string. The id "0" retrieves the section before
 281          *          the first heading, "1" the text between the first heading (included) and the second heading (excluded), etc.
 282          * @return Content|Boolean|null the section, or false if no such section exist, or null if sections are not supported
 283          */
 284         public function getSection( $sectionId );
 285
 286         /**
 287          * Replaces a section of the content and returns a Content object with the section replaced.
 288          *
 289          * @since WD.1
 290          *
 291          * @param $section empty/null/false or a section number (0, 1, 2, T1, T2...), or "new"
 292          * @param $with Content: new content of the section
 293          * @param $sectionTitle String: new section's subject, only if $section is 'new'
 294          * @return string Complete article text, or null if error
 295          */
 296         public function replaceSection( $section, Content $with, $sectionTitle = ''  );
 297
 298         /**
 299          * Returns a Content object with pre-save transformations applied (or this object if no transformations apply).
 300          *
 301          * @since WD.1
 302          *
 303          * @param Title $title
 304          * @param User $user
 305          * @param null|ParserOptions $popts
 306          * @return Content
 307          */
 308         public function preSaveTransform( Title $title, User $user, ParserOptions $popts );
 309
 310         /**
 311          * Returns a new WikitextContent object with the given section heading prepended, if supported.
 312          * The default implementation just returns this Content object unmodified, ignoring the section header.
 313          *
 314          * @since WD.1
 315          *
 316          * @param $header String
 317          * @return Content
 318          */
 319         public function addSectionHeader( $header );
 320
 321         /**
 322          * Returns a Content object with preload transformations applied (or this object if no transformations apply).
 323          *
 324          * @since WD.1
 325          *
 326          * @param Title $title
 327          * @param null|ParserOptions $popts
 328          * @return Content
 329          */
 330         public function preloadTransform( Title $title, ParserOptions $popts );
 331
 332         # TODO: handle ImagePage and CategoryPage
 333         # TODO: make sure we cover lucene search / wikisearch.
 334         # TODO: make sure ReplaceTemplates still works
 335         # FUTURE: nice&sane integration of GeSHi syntax highlighting
 336         #   [11:59] <vvv> Hooks are ugly; make CodeHighlighter interface and a config to set the class which handles syntax highlighting
 337         #   [12:00] <vvv> And default it to a DummyHighlighter
 338
 339         # TODO: make sure we cover the external editor interface (does anyone actually use that?!)
 340
 341         # TODO: tie into API to provide contentModel for Revisions
 342         # TODO: tie into API to provide serialized version and contentFormat for Revisions
 343         # TODO: tie into API edit interface
 344         # FUTURE: make EditForm plugin for EditPage
 345
 346         # FUTURE: special type for redirects?!
 347         # FUTURE: MultipartMultipart < WikipageContent (Main + Links + X)
 348         # FUTURE: LinksContent < LanguageLinksContent, CategoriesContent
 349
 350 // @TODO: add support for ar_content_format, ar_content_model, rev_content_format, rev_content_model to API
 351 }
 352
 353
 354 /**
 355  * A content object represents page content, e.g. the text to show on a page.
 356  * Content objects have no knowledge about how they relate to Wiki pages.
 357  *
 358  * @since 1.WD
 359  */
 360 abstract class AbstractContent implements Content {
 361
 362         /**
 363          * Name of the content model this Content object represents.
 364          * Use with CONTENT_MODEL_XXX constants
 365          *
 366          * @var String $model_id
 367          */
 368         protected $model_id;
 369
 370         /**
 371          * @param int $model_id
 372          */
 373         public function __construct( $model_id = null ) {
 374                 $this->model_id = $model_id;
 375         }
 376
 377         /**
 378          * Returns the id of the content model used by this content objects.
 379          * Corresponds to the CONTENT_MODEL_XXX constants.
 380          *
 381          * @since WD.1
 382          *
 383          * @return int the model id
 384          */
 385         public function getModel() {
 386                 return $this->model_id;
 387         }
 388
 389         /**
 390          * Throws an MWException if $model_id is not the id of the content model
 391          * supported by this Content object.
 392          *
 393          * @param int $model_id the model to check
 394          *
 395          * @throws MWException
 396          */
 397         protected function checkModelID( $model_id ) {
 398                 if ( $model_id !== $this->model_id ) {
 399                         $model_name = ContentHandler::getContentModelName( $model_id );
 400                         $own_model_name = ContentHandler::getContentModelName( $this->model_id );
 401
 402                         throw new MWException( "Bad content model: expected {$this->model_id} ($own_model_name) but got found $model_id ($model_name)." );
 403                 }
 404         }
 405
 406         /**
 407          * Convenience method that returns the ContentHandler singleton for handling the content
 408          * model this Content object uses.
 409          *
 410          * Shorthand for ContentHandler::getForContent( $this )
 411          *
 412          * @since WD.1
 413          *
 414          * @return ContentHandler
 415          */
 416         public function getContentHandler() {
 417                 return ContentHandler::getForContent( $this );
 418         }
 419
 420         /**
 421          * Convenience method that returns the default serialization format for the content model
 422          * model this Content object uses.
 423          *
 424          * Shorthand for $this->getContentHandler()->getDefaultFormat()
 425          *
 426          * @since WD.1
 427          *
 428          * @return ContentHandler
 429          */
 430         public function getDefaultFormat() {
 431                 return $this->getContentHandler()->getDefaultFormat();
 432         }
 433
 434         /**
 435          * Convenience method that returns the list of serialization formats supported
 436          * for the content model model this Content object uses.
 437          *
 438          * Shorthand for $this->getContentHandler()->getSupportedFormats()
 439          *
 440          * @since WD.1
 441          *
 442          * @return array of supported serialization formats
 443          */
 444         public function getSupportedFormats() {
 445                 return $this->getContentHandler()->getSupportedFormats();
 446         }
 447
 448         /**
 449          * Returns true if $format is a supported serialization format for this Content object,
 450          * false if it isn't.
 451          *
 452          * Note that this will always return true if $format is null, because null stands for the
 453          * default serialization.
 454          *
 455          * Shorthand for $this->getContentHandler()->isSupportedFormat( $format )
 456          *
 457          * @since WD.1
 458          *
 459          * @param String $format the format to check
 460          * @return bool whether the format is supported
 461          */
 462         public function isSupportedFormat( $format ) {
 463                 if ( !$format ) {
 464                         return true; // this means "use the default"
 465                 }
 466
 467                 return $this->getContentHandler()->isSupportedFormat( $format );
 468         }
 469
 470         /**
 471          * Throws an MWException if $this->isSupportedFormat( $format ) doesn't return true.
 472          *
 473          * @param $format
 474          * @throws MWException
 475          */
 476         protected function checkFormat( $format ) {
 477                 if ( !$this->isSupportedFormat( $format ) ) {
 478                         throw new MWException( "Format $format is not supported for content model " . $this->getModel() );
 479                 }
 480         }
 481
 482         /**
 483          * Convenience method for serializing this Content object.
 484          *
 485          * Shorthand for $this->getContentHandler()->serializeContent( $this, $format )
 486          *
 487          * @since WD.1
 488          *
 489          * @param null|String $format the desired serialization format (or null for the default format).
 490          * @return String serialized form of this Content object
 491          */
 492         public function serialize( $format = null ) {
 493                 return $this->getContentHandler()->serializeContent( $this, $format );
 494         }
 495
 496         /**
 497          * Returns true if this Content object represents empty content.
 498          *
 499          * @since WD.1
 500          *
 501          * @return bool whether this Content object is empty
 502          */
 503         public function isEmpty() {
 504                 return $this->getSize() == 0;
 505         }
 506
 507         /**
 508          * Returns if the content is valid. This is intended for local validity checks, not considering global consistency.
 509          * It needs to be valid before it can be saved.
 510          *
 511          * This default implementation always returns true.
 512          *
 513          * @since WD.1
 514          *
 515          * @return boolean
 516          */
 517         public function isValid() {
 518                 return true;
 519         }
 520
 521         /**
 522          * Returns true if this Content objects is conceptually equivalent to the given Content object.
 523          *
 524          * Will returns false if $that is null.
 525          * Will return true if $that === $this.
 526          * Will return false if $that->getModelName() != $this->getModel().
 527          * Will return false if $that->getNativeData() is not equal to $this->getNativeData(),
 528          * where the meaning of "equal" depends on the actual data model.
 529          *
 530          * Implementations should be careful to make equals() transitive and reflexive:
 531          *
 532          * * $a->equals( $b ) <=> $b->equals( $a )
 533          * * $a->equals( $b ) &&  $b->equals( $c ) ==> $a->equals( $c )
 534          *
 535          * @since WD.1
 536          *
 537          * @param Content $that the Content object to compare to
 538          * @return bool true if this Content object is euqual to $that, false otherwise.
 539          */
 540         public function equals( Content $that = null ) {
 541                 if ( is_null( $that ) ){
 542                         return false;
 543                 }
 544
 545                 if ( $that === $this ) {
 546                         return true;
 547                 }
 548
 549                 if ( $that->getModel() !== $this->getModel() ) {
 550                         return false;
 551                 }
 552
 553                 return $this->getNativeData() === $that->getNativeData();
 554         }
 555
 556         /**
 557          * Convenience method, shorthand for
 558          * $this->getContentHandler()->getParserOutput( $this, $title, $revId, $options, $generateHtml )
 559          *
 560          * @note: subclasses should NOT override this to provide custom rendering.
 561          *        Override ContentHandler::getParserOutput() instead!
 562          *
 563          * @param Title $title
 564          * @param null $revId
 565          * @param null|ParserOptions $options
 566          * @param Boolean $generateHtml whether to generate Html (default: true). If false,
 567          *        the result of calling getText() on the ParserOutput object returned by
 568          *        this method is undefined.
 569          *
 570          * @since WD.1
 571          *
 572          * @return ParserOutput
 573          */
 574         public function getParserOutput( Title $title, $revId = null, ParserOptions $options = null, $generateHtml = true ) {
 575                 return $this->getContentHandler()->getParserOutput( $this, $title, $revId, $options, $generateHtml );
 576         }
 577
 578         /**
 579          * Construct the redirect destination from this content and return an
 580          * array of Titles, or null if this content doesn't represent a redirect.
 581          * The last element in the array is the final destination after all redirects
 582          * have been resolved (up to $wgMaxRedirects times).
 583          *
 584          * @since WD.1
 585          *
 586          * @return Array of Titles, with the destination last
 587          */
 588         public function getRedirectChain() {
 589                 return null;
 590         }
 591
 592         /**
 593          * Construct the redirect destination from this content and return a Title,
 594          * or null if this content doesn't represent a redirect.
 595          * This will only return the immediate redirect target, useful for
 596          * the redirect table and other checks that don't need full recursion.
 597          *
 598          * @since WD.1
 599          *
 600          * @return Title: The corresponding Title
 601          */
 602         public function getRedirectTarget() {
 603                 return null;
 604         }
 605
 606         /**
 607          * Construct the redirect destination from this content and return the
 608          * Title, or null if this content doesn't represent a redirect.
 609          * This will recurse down $wgMaxRedirects times or until a non-redirect target is hit
 610          * in order to provide (hopefully) the Title of the final destination instead of another redirect.
 611          *
 612          * @since WD.1
 613          *
 614          * @return Title
 615          */
 616         public function getUltimateRedirectTarget() {
 617                 return null;
 618         }
 619
 620         /**
 621          * @since WD.1
 622          *
 623          * @return bool
 624          */
 625         public function isRedirect() {
 626                 return $this->getRedirectTarget() !== null;
 627         }
 628
 629         /**
 630          * Returns the section with the given id.
 631          *
 632          * The default implementation returns null.
 633          *
 634          * @since WD.1
 635          *
 636          * @param String $sectionId the section's id, given as a numeric string. The id "0" retrieves the section before
 637          *          the first heading, "1" the text between the first heading (included) and the second heading (excluded), etc.
 638          * @return Content|Boolean|null the section, or false if no such section exist, or null if sections are not supported
 639          */
 640         public function getSection( $sectionId ) {
 641                 return null;
 642         }
 643
 644         /**
 645          * Replaces a section of the content and returns a Content object with the section replaced.
 646          *
 647          * @since WD.1
 648          *
 649          * @param $section empty/null/false or a section number (0, 1, 2, T1, T2...), or "new"
 650          * @param $with Content: new content of the section
 651          * @param $sectionTitle String: new section's subject, only if $section is 'new'
 652          * @return string Complete article text, or null if error
 653          */
 654         public function replaceSection( $section, Content $with, $sectionTitle = ''  ) {
 655                 return null;
 656         }
 657
 658         /**
 659          * Returns a Content object with pre-save transformations applied (or this object if no transformations apply).
 660          *
 661          * @since WD.1
 662          *
 663          * @param Title $title
 664          * @param User $user
 665          * @param null|ParserOptions $popts
 666          * @return Content
 667          */
 668         public function preSaveTransform( Title $title, User $user, ParserOptions $popts ) {
 669                 return $this;
 670         }
 671
 672         /**
 673          * Returns a new WikitextContent object with the given section heading prepended, if supported.
 674          * The default implementation just returns this Content object unmodified, ignoring the section header.
 675          *
 676          * @since WD.1
 677          *
 678          * @param $header String
 679          * @return Content
 680          */
 681         public function addSectionHeader( $header ) {
 682                 return $this;
 683         }
 684
 685         /**
 686          * Returns a Content object with preload transformations applied (or this object if no transformations apply).
 687          *
 688          * @since WD.1
 689          *
 690          * @param Title $title
 691          * @param null|ParserOptions $popts
 692          * @return Content
 693          */
 694         public function preloadTransform( Title $title, ParserOptions $popts ) {
 695                 return $this;
 696         }
 697 }
 698
 699 /**
 700  * Content object implementation for representing flat text.
 701  *
 702  * TextContent instances are immutable
 703  *
 704  * @since WD.1
 705  */
 706 abstract class TextContent extends AbstractContent {
 707
 708         public function __construct( $text, $model_id = null ) {
 709                 parent::__construct( $model_id );
 710
 711                 $this->mText = $text;
 712         }
 713
 714         public function copy() {
 715                 return $this; #NOTE: this is ok since TextContent are immutable.
 716         }
 717
 718         public function getTextForSummary( $maxlength = 250 ) {
 719                 global $wgContLang;
 720
 721                 $text = $this->getNativeData();
 722
 723                 $truncatedtext = $wgContLang->truncate(
 724                         preg_replace( "/[\n\r]/", ' ', $text ),
 725                         max( 0, $maxlength ) );
 726
 727                 return $truncatedtext;
 728         }
 729
 730         /**
 731          * returns the text's size in bytes.
 732          *
 733          * @return int the size
 734          */
 735         public function getSize( ) {
 736                 $text = $this->getNativeData( );
 737                 return strlen( $text );
 738         }
 739
 740         /**
 741          * Returns true if this content is not a redirect, and $wgArticleCountMethod is "any".
 742          *
 743          * @param $hasLinks Bool: if it is known whether this content contains links, provide this information here,
 744          *                        to avoid redundant parsing to find out.
 745          *
 746          * @return bool true if the content is countable
 747          */
 748         public function isCountable( $hasLinks = null ) {
 749                 global $wgArticleCountMethod;
 750
 751                 if ( $this->isRedirect( ) ) {
 752                         return false;
 753                 }
 754
 755                 if (  $wgArticleCountMethod === 'any' ) {
 756                         return true;
 757                 }
 758
 759                 return false;
 760         }
 761
 762         /**
 763          * Returns the text represented by this Content object, as a string.
 764          *
 765          * @return String the raw text
 766          */
 767         public function getNativeData( ) {
 768                 $text = $this->mText;
 769                 return $text;
 770         }
 771
 772         /**
 773          * Returns the text represented by this Content object, as a string.
 774          *
 775          * @return String the raw text
 776          */
 777         public function getTextForSearchIndex( ) {
 778                 return $this->getNativeData();
 779         }
 780
 781         /**
 782          * Returns the text represented by this Content object, as a string.
 783          *
 784          * @return String the raw text
 785          */
 786         public function getWikitextForTransclusion( ) {
 787                 return $this->getNativeData();
 788         }
 789
 790         /**
 791          * Diff this content object with another content object..
 792          *
 793          * @since WD.diff
 794          *
 795          * @param Content $that the other content object to compare this content object to
 796          * @param Language $lang the language object to use for text segmentation. If not given, $wgContentLang is used.
 797          *
 798          * @return DiffResult a diff representing the changes that would have to be made to this content object
 799          *         to make it equal to $that.
 800          */
 801         public function diff( Content $that, Language $lang = null ) {
 802                 global $wgContLang;
 803
 804                 $this->checkModelID( $that->getModel() );
 805
 806                 #@todo: could implement this in DifferenceEngine and just delegate here?
 807
 808                 if ( !$lang ) $lang = $wgContLang;
 809
 810                 $otext = $this->getNativeData();
 811                 $ntext = $this->getNativeData();
 812
 813                 # Note: Use native PHP diff, external engines don't give us abstract output
 814                 $ota = explode( "\n", $wgContLang->segmentForDiff( $otext ) );
 815                 $nta = explode( "\n", $wgContLang->segmentForDiff( $ntext ) );
 816
 817                 $diff = new Diff( $ota, $nta );
 818                 return $diff;
 819         }
 820
 821
 822 }
 823
 824 /**
 825  * @since WD.1
 826  */
 827 class WikitextContent extends TextContent {
 828
 829         public function __construct( $text ) {
 830                 parent::__construct($text, CONTENT_MODEL_WIKITEXT);
 831         }
 832
 833         /**
 834          * Returns the section with the given id.
 835          *
 836          * @param String $section
 837          *
 838          * @internal param String $sectionId the section's id
 839          * @return Content|false|null the section, or false if no such section exist, or null if sections are not supported
 840          */
 841         public function getSection( $section ) {
 842                 global $wgParser;
 843
 844                 $text = $this->getNativeData();
 845                 $sect = $wgParser->getSection( $text, $section, false );
 846
 847                 return  new WikitextContent( $sect );
 848         }
 849
 850         /**
 851          * Replaces a section in the wikitext
 852          *
 853          * @param $section      empty/null/false or a section number (0, 1, 2, T1, T2...), or "new"
 854          * @param $with         Content: new content of the section
 855          * @param $sectionTitle String: new section's subject, only if $section is 'new'
 856          *
 857          * @throws MWException
 858          * @return Content Complete article content, or null if error
 859          */
 860         public function replaceSection( $section, Content $with, $sectionTitle = '' ) {
 861                 wfProfileIn( __METHOD__ );
 862
 863                 $myModelId = $this->getModel();
 864                 $sectionModelId = $with->getModel();
 865
 866                 if ( $sectionModelId != $myModelId  ) {
 867                         $myModelName = ContentHandler::getContentModelName( $myModelId );
 868                         $sectionModelName = ContentHandler::getContentModelName( $sectionModelId );
 869
 870                         throw new MWException( "Incompatible content model for section: document uses $myModelId ($myModelName), "
 871                                                                 . "section uses $sectionModelId ($sectionModelName)." );
 872                 }
 873
 874                 $oldtext = $this->getNativeData();
 875                 $text = $with->getNativeData();
 876
 877                 if ( $section === '' ) {
 878                         return $with; #XXX: copy first?
 879                 } if ( $section == 'new' ) {
 880                         # Inserting a new section
 881                         $subject = $sectionTitle ? wfMsgForContent( 'newsectionheaderdefaultlevel', $sectionTitle ) . "\n\n" : '';
 882                         if ( wfRunHooks( 'PlaceNewSection', array( $this, $oldtext, $subject, &$text ) ) ) {
 883                                 $text = strlen( trim( $oldtext ) ) > 0
 884                                         ? "{$oldtext}\n\n{$subject}{$text}"
 885                                         : "{$subject}{$text}";
 886                         }
 887                 } else {
 888                         # Replacing an existing section; roll out the big guns
 889                         global $wgParser;
 890
 891                         $text = $wgParser->replaceSection( $oldtext, $section, $text );
 892                 }
 893
 894                 $newContent = new WikitextContent( $text );
 895
 896                 wfProfileOut( __METHOD__ );
 897                 return $newContent;
 898         }
 899
 900         /**
 901          * Returns a new WikitextContent object with the given section heading prepended.
 902          *
 903          * @param $header String
 904          * @return Content
 905          */
 906         public function addSectionHeader( $header ) {
 907                 $text = wfMsgForContent( 'newsectionheaderdefaultlevel', $header ) . "\n\n" . $this->getNativeData();
 908
 909                 return new WikitextContent( $text );
 910         }
 911
 912         /**
 913          * Returns a Content object with pre-save transformations applied (or this object if no transformations apply).
 914          *
 915          * @param Title $title
 916          * @param User $user
 917          * @param ParserOptions $popts
 918          * @return Content
 919          */
 920         public function preSaveTransform( Title $title, User $user, ParserOptions $popts ) { #FIXME: also needed for JS/CSS!
 921                 global $wgParser, $wgConteLang;
 922
 923                 $text = $this->getNativeData();
 924                 $pst = $wgParser->preSaveTransform( $text, $title, $user, $popts );
 925
 926                 return new WikitextContent( $pst );
 927         }
 928
 929         /**
 930          * Returns a Content object with preload transformations applied (or this object if no transformations apply).
 931          *
 932          * @param Title $title
 933          * @param ParserOptions $popts
 934          * @return Content
 935          */
 936         public function preloadTransform( Title $title, ParserOptions $popts ) {
 937                 global $wgParser, $wgConteLang;
 938
 939                 $text = $this->getNativeData();
 940                 $plt = $wgParser->getPreloadText( $text, $title, $popts );
 941
 942                 return new WikitextContent( $plt );
 943         }
 944
 945         public function getRedirectChain() {
 946                 $text = $this->getNativeData();
 947                 return Title::newFromRedirectArray( $text );
 948         }
 949
 950         public function getRedirectTarget() {
 951                 $text = $this->getNativeData();
 952                 return Title::newFromRedirect( $text );
 953         }
 954
 955         public function getUltimateRedirectTarget() {
 956                 $text = $this->getNativeData();
 957                 return Title::newFromRedirectRecurse( $text );
 958         }
 959
 960         /**
 961          * Returns true if this content is not a redirect, and this content's text is countable according to
 962          * the criteria defined by $wgArticleCountMethod.
 963          *
 964          * @param Bool        $hasLinks  if it is known whether this content contains links, provide this information here,
 965          *                               to avoid redundant parsing to find out.
 966          * @param null|\Title $title
 967          *
 968          * @internal param \IContextSource $context context for parsing if necessary
 969          *
 970          * @return bool true if the content is countable
 971          */
 972         public function isCountable( $hasLinks = null, Title $title = null ) {
 973                 global $wgArticleCountMethod, $wgRequest;
 974
 975                 if ( $this->isRedirect( ) ) {
 976                         return false;
 977                 }
 978
 979                 $text = $this->getNativeData();
 980
 981                 switch ( $wgArticleCountMethod ) {
 982                         case 'any':
 983                                 return true;
 984                         case 'comma':
 985                                 return strpos( $text,  ',' ) !== false;
 986                         case 'link':
 987                                 if ( $hasLinks === null ) { # not known, find out
 988                                         if ( !$title ) {
 989                                                 $context = RequestContext::getMain();
 990                                                 $title = $context->getTitle();
 991                                         }
 992
 993                                         $po = $this->getParserOutput( $title, null, null, false );
 994                                         $links = $po->getLinks();
 995                                         $hasLinks = !empty( $links );
 996                                 }
 997
 998                                 return $hasLinks;
 999                 }
1000
1001                 return false;
1002         }
1003
1004         public function getTextForSummary( $maxlength = 250 ) {
1005                 $truncatedtext = parent::getTextForSummary( $maxlength );
1006
1007                 #clean up unfinished links
1008                 #XXX: make this optional? wasn't there in autosummary, but required for deletion summary.
1009                 $truncatedtext = preg_replace( '/\[\[([^\]]*)\]?$/', '$1', $truncatedtext );
1010
1011                 return $truncatedtext;
1012         }
1013
1014 }
1015
1016 /**
1017  * @since WD.1
1018  */
1019 class MessageContent extends TextContent {
1020         public function __construct( $msg_key, $params = null, $options = null ) {
1021                 parent::__construct(null, CONTENT_MODEL_WIKITEXT); #XXX: messages may be wikitext, html or plain text! and maybe even something else entirely.
1022
1023                 $this->mMessageKey = $msg_key;
1024
1025                 $this->mParameters = $params;
1026
1027                 if ( is_null( $options ) ) {
1028                         $options = array();
1029                 }
1030                 elseif ( is_string( $options ) ) {
1031                         $options = array( $options );
1032                 }
1033
1034                 $this->mOptions = $options;
1035         }
1036
1037         /**
1038          * Returns the message as rendered HTML, using the options supplied to the constructor plus "parse".
1039          * @return String the message text, parsed
1040          */
1041         public function getHtml(  ) {
1042                 $opt = array_merge( $this->mOptions, array('parse') );
1043
1044                 return wfMsgExt( $this->mMessageKey, $this->mParameters, $opt );
1045         }
1046
1047
1048         /**
1049          * Returns the message as raw text, using the options supplied to the constructor minus "parse" and "parseinline".
1050          *
1051          * @return String the message text, unparsed.
1052          */
1053         public function getNativeData( ) {
1054                 $opt = array_diff( $this->mOptions, array('parse', 'parseinline') );
1055
1056                 return wfMsgExt( $this->mMessageKey, $this->mParameters, $opt );
1057         }
1058
1059 }
1060
1061 /**
1062  * @since WD.1
1063  */
1064 class JavaScriptContent extends TextContent {
1065         public function __construct( $text ) {
1066                 parent::__construct($text, CONTENT_MODEL_JAVASCRIPT);
1067         }
1068
1069 }
1070
1071 /**
1072  * @since WD.1
1073  */
1074 class CssContent extends TextContent {
1075         public function __construct( $text ) {
1076                 parent::__construct($text, CONTENT_MODEL_CSS);
1077         }
1078 }