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