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