includes/Content.php

   1 <?php
   2
   3 /**
   4  * A content object represents page content, e.g. the text to show on a page.
   5  * Content objects have no knowledge about how they relate to Wiki pages.
   6  * Content objects are imutable.
   7  *
   8  */
   9 abstract class Content {
  10
  11         // TODO: create actual fields and document them
  12
  13     /**
  14      * @return String a string representing the content in a way useful for building a full text search index.
  15      *         If no useful representation exists, this method returns an empty string.
  16      */
  17     public abstract function getTextForSearchIndex( );
  18
  19     /**
  20      * @return String the wikitext to include when another page includes this  content, or false if the content is not
  21      *         includable in a wikitext page.
  22      */
  23     #TODO: allow native handling, bypassing wikitext representation, like for includable special pages.
  24     public abstract function getWikitextForTransclusion( ); #FIXME: use in parser, etc!
  25
  26     /**
  27      * Returns a textual representation of the content suitable for use in edit summaries and log messages.
  28      *
  29      * @param int $maxlength maximum length of the summary text
  30      * @return String the summary text
  31      */
  32     public abstract function getTextForSummary( $maxlength = 250 );
  33
  34     /**
  35      * Returns native represenation of the data. Interpretation depends on the data model used,
  36      * as given by getDataModel().
  37      *
  38      * @return mixed the native representation of the content. Could be a string, a nested array
  39      *         structure, an object, a binary blob... anything, really.
  40      */
  41     public abstract function getNativeData( ); #FIXME: review all calls carefully, caller must be aware of content model!
  42
  43     /**
  44      * returns the content's nominal size in bogo-bytes.
  45      *
  46      * @return int
  47      */
  48     public abstract function getSize( );
  49
  50         /**
  51          * TODO: do we really need to pass a $modelName here?
  52          * Seems odd and makes lots of stuff hard (ie having a newEmpty static method in TextContent)
  53          *
  54          * @param $modelName
  55          */
  56         public function __construct( $modelName = null ) {
  57                 $this->mModelName = $modelName;
  58         }
  59
  60     /**
  61      * Returns the name of the content model used by this content objects.
  62      * Corresponds to the CONTENT_MODEL_XXX constants.
  63      *
  64      * @return String the model name
  65      */
  66         public function getModelName() {
  67                 return $this->mModelName;
  68         }
  69
  70     /**
  71      * Throws an MWException if $modelName is not the name of the content model
  72      * supported by this Content object.
  73      */
  74         protected function checkModelName( $modelName ) {
  75                 if ( $modelName !== $this->mModelName ) {
  76                         throw new MWException( "Bad content model: expected " . $this->mModelName . " but got found " . $modelName );
  77                 }
  78         }
  79
  80     /**
  81      * Conveniance method that returns the ContentHandler singleton for handling the content
  82      * model this Content object uses.
  83      *
  84      * Shorthand for ContentHandler::getForContent( $this )
  85      *
  86      * @return ContentHandler
  87      */
  88         public function getContentHandler() {
  89                 return ContentHandler::getForContent( $this );
  90         }
  91
  92     /**
  93      * Conveniance method that returns the default serialization format for the content model
  94      * model this Content object uses.
  95      *
  96      * Shorthand for $this->getContentHandler()->getDefaultFormat()
  97      *
  98      * @return ContentHandler
  99      */
 100         public function getDefaultFormat() {
 101                 return $this->getContentHandler()->getDefaultFormat();
 102         }
 103
 104     /**
 105      * Conveniance method that returns the list of serialization formats supported
 106      * for the content model model this Content object uses.
 107      *
 108      * Shorthand for $this->getContentHandler()->getSupportedFormats()
 109      *
 110      * @return array of supported serialization formats
 111      */
 112         public function getSupportedFormats() {
 113                 return $this->getContentHandler()->getSupportedFormats();
 114         }
 115
 116     /**
 117      * Returns true if $format is a supported serialization format for this Content object,
 118      * false if it isn't.
 119      *
 120      * Note that this will always return true if $format is null, because null stands for the
 121      * default serialization.
 122      *
 123      * Shorthand for $this->getContentHandler()->isSupportedFormat( $format )
 124      *
 125      * @param String $format the format to check
 126      * @return bool whether the format is supported
 127      */
 128         public function isSupportedFormat( $format ) {
 129                 if ( !$format ) {
 130                         return true; // this means "use the default"
 131                 }
 132
 133                 return $this->getContentHandler()->isSupportedFormat( $format );
 134         }
 135
 136     /**
 137      * Throws an MWException if $this->isSupportedFormat( $format ) doesn't return true.
 138      *
 139      * @param $format
 140      * @throws MWException
 141      */
 142         protected function checkFormat( $format ) {
 143                 if ( !$this->isSupportedFormat( $format ) ) {
 144                         throw new MWException( "Format $format is not supported for content model " . $this->getModelName() );
 145                 }
 146         }
 147
 148     /**
 149      * Conveniance method for serializing this Content object.
 150      *
 151      * Shorthand for $this->getContentHandler()->serialize( $this, $format )
 152      *
 153      * @param null|String $format the desired serialization format (or null for the default format).
 154      * @return String serialized form of this Content object
 155      */
 156         public function serialize( $format = null ) {
 157                 return $this->getContentHandler()->serialize( $this, $format );
 158         }
 159
 160     /**
 161      * Returns true if this Content object represents empty content.
 162      *
 163      * @return bool whether this Content object is empty
 164      */
 165     public function isEmpty() {
 166         return $this->getSize() == 0;
 167     }
 168
 169     /**
 170      * Returns true if this Content objects is conceptually equivalent to the given Content object.
 171      *
 172      * Will returns false if $that is null.
 173      * Will return true if $that === $this.
 174      *
 175      * Returns false if this Content object uses a different content model than the
 176      *
 177      * @param Content $that the Content object to compare to
 178      * @return bool true if this Content object is euzqla to $that, false otherwise.
 179      */
 180     public function equals( Content $that = null ) {
 181         if ( empty( $that ) ){ // FIXME: empty on an object?
 182                         return false;
 183                 }
 184
 185                 return false;
 186                 // FIXME: something is doing wrong here, causing the compared objects to always be the same.
 187                 // Hence returning false for now, so changes can actually be saved...
 188
 189         if ( $that === $this ) {
 190                         return true;
 191                 }
 192
 193         if ( $that->getModelName() !== $this->getModelName() ) {
 194                         return false;
 195                 }
 196
 197         return $this->getNativeData() === $that->getNativeData();
 198     }
 199
 200     /**
 201      * Returns true if this content is countable as a "real" wiki page, provided
 202      * that it's also in a countable location (e.g. a current revision in the main namespace).
 203      *
 204      * @param $hasLinks Bool: if it is known whether this content contains links, provide this information here,
 205      *                        to avoid redundant parsing to find out.
 206      */
 207     public abstract function isCountable( $hasLinks = null ) ;
 208
 209     /**
 210      * @param IContextSource $context
 211      * @param null $revId
 212      * @param null|ParserOptions $options
 213      * @param Boolean $generateHtml whether to generate Html (default: true). If false,
 214      *        the result of calling getText() on the ParserOutput object returned by
 215      *        this method is undefined.
 216      *
 217      * @return ParserOutput
 218      */
 219     public abstract function getParserOutput( IContextSource $context, $revId = null, ParserOptions $options = NULL, $generateHtml = true );
 220
 221     /**
 222      * Construct the redirect destination from this content and return an
 223      * array of Titles, or null if this content doesn't represent a redirect.
 224      * The last element in the array is the final destination after all redirects
 225      * have been resolved (up to $wgMaxRedirects times).
 226      *
 227      * @return Array of Titles, with the destination last
 228      */
 229     public function getRedirectChain() {
 230         return null;
 231     }
 232
 233     /**
 234      * Construct the redirect destination from this content and return an
 235      * array of Titles, or null if this content doesn't represent a redirect.
 236      * This will only return the immediate redirect target, useful for
 237      * the redirect table and other checks that don't need full recursion.
 238      *
 239      * @return Title: The corresponding Title
 240      */
 241     public function getRedirectTarget() {
 242         return null;
 243     }
 244
 245     /**
 246      * Construct the redirect destination from this content and return the
 247      * Title, or null if this content doesn't represent a redirect.
 248      * This will recurse down $wgMaxRedirects times or until a non-redirect target is hit
 249      * in order to provide (hopefully) the Title of the final destination instead of another redirect.
 250      *
 251      * @return Title
 252      */
 253     public function getUltimateRedirectTarget() {
 254         return null;
 255     }
 256
 257     public function isRedirect() {
 258         return $this->getRedirectTarget() != null;
 259     }
 260
 261     /**
 262      * Returns the section with the given id.
 263      *
 264      * The default implementation returns null.
 265      *
 266      * @param String $sectionId the section's id
 267      * @return Content|Boolean|null the section, or false if no such section exist, or null if sections are not supported
 268      */
 269     public function getSection( $sectionId ) {
 270         return null;
 271     }
 272
 273     /**
 274      * Replaces a section of the content and returns a Content object with the section replaced.
 275      *
 276      * @param $section empty/null/false or a section number (0, 1, 2, T1, T2...), or "new"
 277      * @param $with Content: new content of the section
 278      * @param $sectionTitle String: new section's subject, only if $section is 'new'
 279      * @return string Complete article text, or null if error
 280      */
 281     public function replaceSection( $section, Content $with, $sectionTitle = ''  ) {
 282         return $this;
 283     }
 284
 285     /**
 286      * Returns a Content object with pre-save transformations applied (or this object if no transformations apply).
 287      *
 288      * @param Title $title
 289      * @param User $user
 290      * @param null|ParserOptions $popts
 291      * @return Content
 292      */
 293     public function preSaveTransform( Title $title, User $user, ParserOptions $popts = null ) {
 294         return $this;
 295     }
 296
 297     /**
 298      * Returns a new WikitextContent object with the given section heading prepended, if supported.
 299      * The default implementation just returns this Content object unmodified, ignoring the section header.
 300      *
 301      * @param $header String
 302      * @return Content
 303      */
 304     public function addSectionHeader( $header ) {
 305         return $this;
 306     }
 307
 308     /**
 309      * Returns a Content object with preload transformations applied (or this object if no transformations apply).
 310      *
 311      * @param Title $title
 312      * @param null|ParserOptions $popts
 313      * @return Content
 314      */
 315     public function preloadTransform( Title $title, ParserOptions $popts = null ) {
 316         return $this;
 317     }
 318
 319     # TODO: minimize special cases for CSS/JS; how to handle extra message for JS/CSS previews??
 320     # TODO: handle ImagePage and CategoryPage
 321     # TODO: hook into dump generation to serialize and record model and format!
 322
 323     # TODO: make sure we cover lucene search / wikisearch.
 324     # TODO: make sure ReplaceTemplates still works
 325     # TODO: nice&sane integration of GeSHi syntax highlighting
 326     #   [11:59] <vvv> Hooks are ugly; make CodeHighlighter interface and a config to set the class which handles syntax highlighting
 327     #   [12:00] <vvv> And default it to a DummyHighlighter
 328
 329     # TODO: make sure we cover the external editor interface (does anyone actually use that?!)
 330
 331     # TODO: tie into API to provide contentModel for Revisions
 332     # TODO: tie into API to provide serialized version and contentFormat for Revisions
 333     # TODO: tie into API edit interface
 334     # TODO: make EditForm plugin for EditPage
 335
 336     # XXX: isCacheable( ) # can/should we do this here?
 337 }
 338
 339 /**
 340  * Content object implementation for representing flat text. The
 341  */
 342 abstract class TextContent extends Content {
 343
 344     public function __construct( $text, $modelName = null ) {
 345         parent::__construct( $modelName );
 346
 347         $this->mText = $text;
 348     }
 349
 350     public function getTextForSummary( $maxlength = 250 ) {
 351         global $wgContLang;
 352
 353         $text = $this->getNativeData();
 354
 355         $truncatedtext = $wgContLang->truncate(
 356             preg_replace( "/[\n\r]/", ' ', $text ),
 357             max( 0, $maxlength ) );
 358
 359         return $truncatedtext;
 360     }
 361
 362     /**
 363      * returns the content's nominal size in bogo-bytes.
 364      */
 365     public function getSize( ) { #FIXME: use! replace strlen in WikiPage.
 366         $text = $this->getNativeData( );
 367         return strlen( $text );
 368     }
 369
 370     /**
 371      * Returns true if this content is not a redirect, and $wgArticleCountMethod is "any".
 372      *
 373      * @param $hasLinks Bool: if it is known whether this content contains links, provide this information here,
 374      *                        to avoid redundant parsing to find out.
 375      */
 376     public function isCountable( $hasLinks = null ) {
 377         global $wgArticleCountMethod;
 378
 379         if ( $this->isRedirect( ) ) {
 380             return false;
 381         }
 382
 383         if (  $wgArticleCountMethod === 'any' ) {
 384             return true;
 385         }
 386
 387         return false;
 388     }
 389
 390     /**
 391      * Returns the text represented by this Content object, as a string.
 392      *
 393      * @return String the raw text
 394      */
 395     public function getNativeData( ) {
 396         $text = $this->mText;
 397         return $text;
 398     }
 399
 400     /**
 401      * Returns the text represented by this Content object, as a string.
 402      *
 403      * @return String the raw text
 404      */
 405     public function getTextForSearchIndex( ) { #FIXME: use!
 406         return $this->getNativeData();
 407     }
 408
 409     /**
 410      * Returns the text represented by this Content object, as a string.
 411      *
 412      * @return String the raw text
 413      */
 414     public function getWikitextForTransclusion( ) { #FIXME: use!
 415         return $this->getNativeData();
 416     }
 417
 418     /**
 419      * Returns a generic ParserOutput object, wrapping the HTML returned by getHtml().
 420      *
 421      * @return ParserOutput representing the HTML form of the text
 422      */
 423     public function getParserOutput( IContextSource $context, $revId = null, ParserOptions $options = null, $generateHtml = true ) {
 424         # generic implementation, relying on $this->getHtml()
 425
 426         if ( $generateHtml ) $html = $this->getHtml( $options );
 427         else $html = '';
 428
 429         $po = new ParserOutput( $html );
 430
 431         return $po;
 432     }
 433
 434     protected abstract function getHtml( );
 435
 436 }
 437
 438 class WikitextContent extends TextContent {
 439
 440     public function __construct( $text ) {
 441         parent::__construct($text, CONTENT_MODEL_WIKITEXT);
 442
 443         $this->mDefaultParserOptions = null; #TODO: use per-class static member?!
 444     }
 445
 446     protected function getHtml( ) {
 447         throw new MWException( "getHtml() not implemented for wikitext. Use getParserOutput()->getText()." );
 448     }
 449
 450     public function getDefaultParserOptions() {
 451         global $wgUser, $wgContLang;
 452
 453         if ( !$this->mDefaultParserOptions ) { #TODO: use per-class static member?!
 454             $this->mDefaultParserOptions = ParserOptions::newFromUserAndLang( $wgUser, $wgContLang );
 455         }
 456
 457         return $this->mDefaultParserOptions;
 458     }
 459
 460     /**
 461          * Returns a ParserOutput object resulting from parsing the content's text using $wgParser.
 462          *
 463          * @since WikiData1
 464          *
 465          * @param IContextSource|null $context
 466          * @param null $revId
 467          * @param null|ParserOptions $options
 468          * @param bool $generateHtml
 469          *
 470          * @return ParserOutput representing the HTML form of the text
 471          */
 472     public function getParserOutput( IContextSource $context = null, $revId = null, ParserOptions $options = null, $generateHtml = true ) {
 473         global $wgParser;
 474
 475         if ( !$options ) {
 476             $options = $this->getDefaultParserOptions();
 477         }
 478
 479         $po = $wgParser->parse( $this->mText, $context->getTitle(), $options, true, true, $revId );
 480
 481         return $po;
 482     }
 483
 484     /**
 485      * Returns the section with the given id.
 486      *
 487      * @param String $sectionId the section's id
 488      * @return Content|false|null the section, or false if no such section exist, or null if sections are not supported
 489      */
 490     public function getSection( $section ) {
 491         global $wgParser;
 492
 493         $text = $this->getNativeData();
 494         $sect = $wgParser->getSection( $text, $section, false );
 495
 496         return  new WikitextContent( $sect );
 497     }
 498
 499     /**
 500      * Replaces a section in the wikitext
 501      *
 502      * @param $section empty/null/false or a section number (0, 1, 2, T1, T2...), or "new"
 503      * @param $with Content: new content of the section
 504      * @param $sectionTitle String: new section's subject, only if $section is 'new'
 505      * @return string Complete article text, or null if error
 506      */
 507     public function replaceSection( $section, Content $with, $sectionTitle = '' ) {
 508         wfProfileIn( __METHOD__ );
 509
 510         $myModelName = $this->getModelName();
 511         $sectionModelName = $with->getModelName();
 512
 513         if ( $sectionModelName != $myModelName  ) {
 514             throw new MWException( "Incompatible content model for section: document uses $myModelName, section uses $sectionModelName." );
 515         }
 516
 517         $oldtext = $this->getNativeData();
 518         $text = $with->getNativeData();
 519
 520         if ( $section == 'new' ) {
 521             # Inserting a new section
 522             $subject = $sectionTitle ? wfMsgForContent( 'newsectionheaderdefaultlevel', $sectionTitle ) . "\n\n" : '';
 523             if ( wfRunHooks( 'PlaceNewSection', array( $this, $oldtext, $subject, &$text ) ) ) {
 524                 $text = strlen( trim( $oldtext ) ) > 0
 525                     ? "{$oldtext}\n\n{$subject}{$text}"
 526                     : "{$subject}{$text}";
 527             }
 528         } else {
 529             # Replacing an existing section; roll out the big guns
 530             global $wgParser;
 531
 532             $text = $wgParser->replaceSection( $oldtext, $section, $text );
 533         }
 534
 535         $newContent = new WikitextContent( $text );
 536
 537         wfProfileOut( __METHOD__ );
 538         return $newContent;
 539     }
 540
 541     /**
 542      * Returns a new WikitextContent object with the given section heading prepended.
 543      *
 544      * @param $header String
 545      * @return Content
 546      */
 547     public function addSectionHeader( $header ) {
 548         $text = wfMsgForContent( 'newsectionheaderdefaultlevel', $this->sectiontitle ) . "\n\n" . $this->getNativeData();
 549
 550         return new WikitextContent( $text );
 551     }
 552
 553     /**
 554      * Returns a Content object with pre-save transformations applied (or this object if no transformations apply).
 555      *
 556      * @param Title $title
 557      * @param User $user
 558      * @param null|ParserOptions $popts
 559      * @return Content
 560      */
 561     public function preSaveTransform( Title $title, User $user, ParserOptions $popts = null ) {
 562         global $wgParser;
 563
 564         if ( $popts == null ) $popts = $this->getDefaultParserOptions();
 565
 566         $text = $this->getNativeData();
 567         $pst = $wgParser->preSaveTransform( $text, $title, $user, $popts );
 568
 569         return new WikitextContent( $pst );
 570     }
 571
 572     /**
 573      * Returns a Content object with preload transformations applied (or this object if no transformations apply).
 574      *
 575      * @param Title $title
 576      * @param null|ParserOptions $popts
 577      * @return Content
 578      */
 579     public function preloadTransform( Title $title, ParserOptions $popts = null ) {
 580         global $wgParser;
 581
 582         if ( $popts == null ) $popts = $this->getDefaultParserOptions();
 583
 584         $text = $this->getNativeData();
 585         $plt = $wgParser->getPreloadText( $text, $title, $popts );
 586
 587         return new WikitextContent( $plt );
 588     }
 589
 590     public function getRedirectChain() {
 591         $text = $this->getNativeData();
 592         return Title::newFromRedirectArray( $text );
 593     }
 594
 595     public function getRedirectTarget() {
 596         $text = $this->getNativeData();
 597         return Title::newFromRedirect( $text );
 598     }
 599
 600     public function getUltimateRedirectTarget() {
 601         $text = $this->getNativeData();
 602         return Title::newFromRedirectRecurse( $text );
 603     }
 604
 605     /**
 606      * Returns true if this content is not a redirect, and this content's text is countable according to
 607      * the criteria defiend by $wgArticleCountMethod.
 608      *
 609      * @param $hasLinks Bool: if it is known whether this content contains links, provide this information here,
 610      *                        to avoid redundant parsing to find out.
 611      */
 612     public function isCountable( $hasLinks = null ) {
 613         global $wgArticleCountMethod;
 614
 615         if ( $this->isRedirect( ) ) {
 616             return false;
 617         }
 618
 619         $text = $this->getNativeData();
 620
 621         switch ( $wgArticleCountMethod ) {
 622             case 'any':
 623                 return true;
 624             case 'comma':
 625                 if ( $text === false ) {
 626                     $text = $this->getRawText();
 627                 }
 628                 return strpos( $text,  ',' ) !== false;
 629             case 'link':
 630                 if ( $hasLinks === null ) { # not know, find out
 631                     $po = $this->getParserOutput();
 632                     $links = $po->getLinks();
 633                     $hasLinks = !empty( $links );
 634                 }
 635
 636                 return $hasLinks;
 637         }
 638     }
 639
 640     public function getTextForSummary( $maxlength = 250 ) {
 641         $truncatedtext = parent::getTextForSummary( $maxlength );
 642
 643         #clean up unfinished links
 644         #XXX: make this optional? wasn't there in autosummary, but required for deletion summary.
 645         $truncatedtext = preg_replace( '/\[\[([^\]]*)\]?$/', '$1', $truncatedtext );
 646
 647         return $truncatedtext;
 648     }
 649
 650 }
 651
 652 class MessageContent extends TextContent {
 653     public function __construct( $msg_key, $params = null, $options = null ) {
 654         parent::__construct(null, CONTENT_MODEL_WIKITEXT); #XXX: messages may be wikitext, html or plain text! and maybe even something else entirely.
 655
 656         $this->mMessageKey = $msg_key;
 657
 658         $this->mParameters = $params;
 659
 660         if ( is_null( $options ) ) {
 661                         $options = array();
 662                 }
 663                 elseif ( is_string( $options ) ) {
 664                         $options = array( $options );
 665                 }
 666
 667         $this->mOptions = $options;
 668
 669         $this->mHtmlOptions = null;
 670     }
 671
 672     /**
 673      * Returns the message as rendered HTML, using the options supplied to the constructor plus "parse".
 674      */
 675     protected function getHtml(  ) {
 676         $opt = array_merge( $this->mOptions, array('parse') );
 677
 678         return wfMsgExt( $this->mMessageKey, $this->mParameters, $opt );
 679     }
 680
 681
 682     /**
 683      * Returns the message as raw text, using the options supplied to the constructor minus "parse" and "parseinline".
 684      */
 685     public function getNativeData( ) {
 686         $opt = array_diff( $this->mOptions, array('parse', 'parseinline') );
 687
 688         return wfMsgExt( $this->mMessageKey, $this->mParameters, $opt );
 689     }
 690
 691 }
 692
 693
 694 class JavaScriptContent extends TextContent {
 695     public function __construct( $text ) {
 696         parent::__construct($text, CONTENT_MODEL_JAVASCRIPT);
 697     }
 698
 699     protected function getHtml( ) {
 700         $html = "";
 701         $html .= "<pre class=\"mw-code mw-js\" dir=\"ltr\">\n";
 702         $html .= htmlspecialchars( $this->getNativeData() );
 703         $html .= "\n</pre>\n";
 704
 705         return $html;
 706     }
 707
 708 }
 709
 710 class CssContent extends TextContent {
 711     public function __construct( $text ) {
 712         parent::__construct($text, CONTENT_MODEL_CSS);
 713     }
 714
 715     protected function getHtml( ) {
 716         $html = "";
 717         $html .= "<pre class=\"mw-code mw-css\" dir=\"ltr\">\n";
 718         $html .= htmlspecialchars( $this->getNativeData() );
 719         $html .= "\n</pre>\n";
 720
 721         return $html;
 722     }
 723 }
 724
 725 #FUTURE: special type for redirects?!
 726 #FUTURE: MultipartMultipart < WikipageContent (Main + Links + X)
 727 #FUTURE: LinksContent < LanguageLinksContent, CategoriesContent
 728 #EXAMPLE: CoordinatesContent
 729 #EXAMPLE: WikidataContent