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