includes/content/AbstractContent.php

   1 <?php
   2 /**
   3  * A content object represents page content, e.g. the text to show on a page.
   4  * Content objects have no knowledge about how they relate to Wiki pages.
   5  *
   6  * This program is free software; you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation; either version 2 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License along
  17  * with this program; if not, write to the Free Software Foundation, Inc.,
  18  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  19  * http://www.gnu.org/copyleft/gpl.html
  20  *
  21  * @since 1.21
  22  *
  23  * @file
  24  * @ingroup Content
  25  *
  26  * @author Daniel Kinzler
  27  */
  28
  29 /**
  30  * Base implementation for content objects.
  31  *
  32  * @ingroup Content
  33  */
  34 abstract class AbstractContent implements Content {
  35         /**
  36          * Name of the content model this Content object represents.
  37          * Use with CONTENT_MODEL_XXX constants
  38          *
  39          * @since 1.21
  40          *
  41          * @var string $model_id
  42          */
  43         protected $model_id;
  44
  45         /**
  46          * @param string|null $modelId
  47          *
  48          * @since 1.21
  49          */
  50         public function __construct( $modelId = null ) {
  51                 $this->model_id = $modelId;
  52         }
  53
  54         /**
  55          * @since 1.21
  56          *
  57          * @see Content::getModel
  58          * @return string
  59          */
  60         public function getModel() {
  61                 return $this->model_id;
  62         }
  63
  64         /**
  65          * @since 1.21
  66          *
  67          * @param string $modelId The model to check
  68          *
  69          * @throws MWException If the provided ID is not the ID of the content model supported by this
  70          * Content object.
  71          */
  72         protected function checkModelID( $modelId ) {
  73                 if ( $modelId !== $this->model_id ) {
  74                         throw new MWException(
  75                                 "Bad content model: " .
  76                                 "expected {$this->model_id} " .
  77                                 "but got $modelId."
  78                         );
  79                 }
  80         }
  81
  82         /**
  83          * @since 1.21
  84          *
  85          * @see Content::getContentHandler
  86          * @return ContentHandler
  87          */
  88         public function getContentHandler() {
  89                 return ContentHandler::getForContent( $this );
  90         }
  91
  92         /**
  93          * @since 1.21
  94          *
  95          * @see Content::getDefaultFormat
  96          * @return string
  97          */
  98         public function getDefaultFormat() {
  99                 return $this->getContentHandler()->getDefaultFormat();
 100         }
 101
 102         /**
 103          * @since 1.21
 104          *
 105          * @see Content::getSupportedFormats
 106          * @return string[]
 107          */
 108         public function getSupportedFormats() {
 109                 return $this->getContentHandler()->getSupportedFormats();
 110         }
 111
 112         /**
 113          * @since 1.21
 114          *
 115          * @param string $format
 116          *
 117          * @return bool
 118          *
 119          * @see Content::isSupportedFormat
 120          */
 121         public function isSupportedFormat( $format ) {
 122                 if ( !$format ) {
 123                         return true; // this means "use the default"
 124                 }
 125
 126                 return $this->getContentHandler()->isSupportedFormat( $format );
 127         }
 128
 129         /**
 130          * @since 1.21
 131          *
 132          * @param string $format The serialization format to check.
 133          *
 134          * @throws MWException If the format is not supported by this content handler.
 135          */
 136         protected function checkFormat( $format ) {
 137                 if ( !$this->isSupportedFormat( $format ) ) {
 138                         throw new MWException(
 139                                 "Format $format is not supported for content model " .
 140                                 $this->getModel()
 141                         );
 142                 }
 143         }
 144
 145         /**
 146          * @since 1.21
 147          *
 148          * @param string|null $format
 149          *
 150          * @return string
 151          *
 152          * @see Content::serialize
 153          */
 154         public function serialize( $format = null ) {
 155                 return $this->getContentHandler()->serializeContent( $this, $format );
 156         }
 157
 158         /**
 159          * @since 1.21
 160          *
 161          * @return bool
 162          *
 163          * @see Content::isEmpty
 164          */
 165         public function isEmpty() {
 166                 return $this->getSize() === 0;
 167         }
 168
 169         /**
 170          * Subclasses may override this to implement (light weight) validation.
 171          *
 172          * @since 1.21
 173          *
 174          * @return bool Always true.
 175          *
 176          * @see Content::isValid
 177          */
 178         public function isValid() {
 179                 return true;
 180         }
 181
 182         /**
 183          * Decides whether two Content objects are equal.
 184          * Two Content objects MUST not be considered equal if they do not share the same content model.
 185          * Two Content objects that are equal SHOULD have the same serialization.
 186          *
 187          * This default implementation relies on equalsInternal() to determin whether the
 188          * Content objects are logically equivalent. Subclasses that need to implement a custom
 189          * equality check should consider overriding equalsInternal(). Subclasses that override
 190          * equals() itself MUST make sure that the implementation returns false for $that === null,
 191          * and true for $that === this. It MUST also return false if $that does not have the same
 192          * content model.
 193          *
 194          * @since 1.21
 195          *
 196          * @param Content|null $that
 197          *
 198          * @return bool
 199          *
 200          * @see Content::equals
 201          */
 202         public function equals( Content $that = null ) {
 203                 if ( is_null( $that ) ) {
 204                         return false;
 205                 }
 206
 207                 if ( $that === $this ) {
 208                         return true;
 209                 }
 210
 211                 if ( $that->getModel() !== $this->getModel() ) {
 212                         return false;
 213                 }
 214
 215                 // For type safety. Needed for odd cases like MessageContent using CONTENT_MODEL_WIKITEXT
 216                 if ( get_class( $that ) !== get_class( $this ) ) {
 217                         return false;
 218                 }
 219
 220                 return $this->equalsInternal( $that );
 221         }
 222
 223         /**
 224          * Checks whether $that is logically equal to this Content object.
 225          *
 226          * This method can be overwritten by subclasses that need to implement custom
 227          * equality checks.
 228          *
 229          * This default implementation checks whether the serializations
 230          * of $this and $that are the same: $this->serialize() === $that->serialize()
 231          *
 232          * Implementors can assume that $that is an instance of the same class
 233          * as the present Content object, as long as equalsInternal() is only called
 234          * by the standard implementation of equals().
 235          *
 236          * @note Do not call this method directly, call equals() instead.
 237          *
 238          * @param Content $that
 239          * @return bool
 240          */
 241         protected function equalsInternal( Content $that ) {
 242                 return $this->serialize() === $that->serialize();
 243         }
 244
 245         /**
 246          * Returns a list of DataUpdate objects for recording information about this
 247          * Content in some secondary data store.
 248          *
 249          * This default implementation returns a LinksUpdate object and calls the
 250          * SecondaryDataUpdates hook.
 251          *
 252          * Subclasses may override this to determine the secondary data updates more
 253          * efficiently, preferably without the need to generate a parser output object.
 254          * They should however make sure to call SecondaryDataUpdates to give extensions
 255          * a chance to inject additional updates.
 256          *
 257          * @since 1.21
 258          *
 259          * @param Title $title
 260          * @param Content|null $old
 261          * @param bool $recursive
 262          * @param ParserOutput|null $parserOutput
 263          *
 264          * @return DataUpdate[]
 265          *
 266          * @see Content::getSecondaryDataUpdates()
 267          */
 268         public function getSecondaryDataUpdates( Title $title, Content $old = null,
 269                 $recursive = true, ParserOutput $parserOutput = null
 270         ) {
 271                 if ( $parserOutput === null ) {
 272                         $parserOutput = $this->getParserOutput( $title, null, null, false );
 273                 }
 274
 275                 $updates = [
 276                         new LinksUpdate( $title, $parserOutput, $recursive )
 277                 ];
 278
 279                 Hooks::run( 'SecondaryDataUpdates', [ $title, $old, $recursive, $parserOutput, &$updates ] );
 280
 281                 return $updates;
 282         }
 283
 284         /**
 285          * @since 1.21
 286          *
 287          * @return Title[]|null
 288          *
 289          * @see Content::getRedirectChain
 290          */
 291         public function getRedirectChain() {
 292                 global $wgMaxRedirects;
 293                 $title = $this->getRedirectTarget();
 294                 if ( is_null( $title ) ) {
 295                         return null;
 296                 }
 297                 // recursive check to follow double redirects
 298                 $recurse = $wgMaxRedirects;
 299                 $titles = [ $title ];
 300                 while ( --$recurse > 0 ) {
 301                         if ( $title->isRedirect() ) {
 302                                 $page = WikiPage::factory( $title );
 303                                 $newtitle = $page->getRedirectTarget();
 304                         } else {
 305                                 break;
 306                         }
 307                         // Redirects to some special pages are not permitted
 308                         if ( $newtitle instanceof Title && $newtitle->isValidRedirectTarget() ) {
 309                                 // The new title passes the checks, so make that our current
 310                                 // title so that further recursion can be checked
 311                                 $title = $newtitle;
 312                                 $titles[] = $newtitle;
 313                         } else {
 314                                 break;
 315                         }
 316                 }
 317
 318                 return $titles;
 319         }
 320
 321         /**
 322          * Subclasses that implement redirects should override this.
 323          *
 324          * @since 1.21
 325          *
 326          * @return Title|null
 327          *
 328          * @see Content::getRedirectTarget
 329          */
 330         public function getRedirectTarget() {
 331                 return null;
 332         }
 333
 334         /**
 335          * @note Migrated here from Title::newFromRedirectRecurse.
 336          *
 337          * @since 1.21
 338          *
 339          * @return Title|null
 340          *
 341          * @see Content::getUltimateRedirectTarget
 342          */
 343         public function getUltimateRedirectTarget() {
 344                 $titles = $this->getRedirectChain();
 345
 346                 return $titles ? array_pop( $titles ) : null;
 347         }
 348
 349         /**
 350          * @since 1.21
 351          *
 352          * @return bool
 353          *
 354          * @see Content::isRedirect
 355          */
 356         public function isRedirect() {
 357                 return $this->getRedirectTarget() !== null;
 358         }
 359
 360         /**
 361          * This default implementation always returns $this.
 362          * Subclasses that implement redirects should override this.
 363          *
 364          * @since 1.21
 365          *
 366          * @param Title $target
 367          *
 368          * @return Content $this
 369          *
 370          * @see Content::updateRedirect
 371          */
 372         public function updateRedirect( Title $target ) {
 373                 return $this;
 374         }
 375
 376         /**
 377          * @since 1.21
 378          *
 379          * @param string|int $sectionId
 380          * @return null
 381          *
 382          * @see Content::getSection
 383          */
 384         public function getSection( $sectionId ) {
 385                 return null;
 386         }
 387
 388         /**
 389          * @since 1.21
 390          *
 391          * @param string|int|null|bool $sectionId
 392          * @param Content $with
 393          * @param string $sectionTitle
 394          * @return null
 395          *
 396          * @see Content::replaceSection
 397          */
 398         public function replaceSection( $sectionId, Content $with, $sectionTitle = '' ) {
 399                 return null;
 400         }
 401
 402         /**
 403          * @since 1.21
 404          *
 405          * @param Title $title
 406          * @param User $user
 407          * @param ParserOptions $popts
 408          * @return Content $this
 409          *
 410          * @see Content::preSaveTransform
 411          */
 412         public function preSaveTransform( Title $title, User $user, ParserOptions $popts ) {
 413                 return $this;
 414         }
 415
 416         /**
 417          * @since 1.21
 418          *
 419          * @param string $header
 420          * @return Content $this
 421          *
 422          * @see Content::addSectionHeader
 423          */
 424         public function addSectionHeader( $header ) {
 425                 return $this;
 426         }
 427
 428         /**
 429          * @since 1.21
 430          *
 431          * @param Title $title
 432          * @param ParserOptions $popts
 433          * @param array $params
 434          * @return Content $this
 435          *
 436          * @see Content::preloadTransform
 437          */
 438         public function preloadTransform( Title $title, ParserOptions $popts, $params = [] ) {
 439                 return $this;
 440         }
 441
 442         /**
 443          * @since 1.21
 444          *
 445          * @param WikiPage $page
 446          * @param int $flags
 447          * @param int $parentRevId
 448          * @param User $user
 449          * @return Status
 450          *
 451          * @see Content::prepareSave
 452          */
 453         public function prepareSave( WikiPage $page, $flags, $parentRevId, User $user ) {
 454                 if ( $this->isValid() ) {
 455                         return Status::newGood();
 456                 } else {
 457                         return Status::newFatal( "invalid-content-data" );
 458                 }
 459         }
 460
 461         /**
 462          * @since 1.21
 463          *
 464          * @param WikiPage $page
 465          * @param ParserOutput|null $parserOutput
 466          *
 467          * @return DeferrableUpdate[]
 468          *
 469          * @see Content::getDeletionUpdates
 470          */
 471         public function getDeletionUpdates( WikiPage $page, ParserOutput $parserOutput = null ) {
 472                 return [
 473                         new LinksDeletionUpdate( $page ),
 474                 ];
 475         }
 476
 477         /**
 478          * This default implementation always returns false. Subclasses may override
 479          * this to supply matching logic.
 480          *
 481          * @since 1.21
 482          *
 483          * @param MagicWord $word
 484          *
 485          * @return bool Always false.
 486          *
 487          * @see Content::matchMagicWord
 488          */
 489         public function matchMagicWord( MagicWord $word ) {
 490                 return false;
 491         }
 492
 493         /**
 494          * This base implementation calls the hook ConvertContent to enable custom conversions.
 495          * Subclasses may override this to implement conversion for "their" content model.
 496          *
 497          * @param string $toModel
 498          * @param string $lossy
 499          *
 500          * @return Content|bool
 501          *
 502          * @see Content::convert()
 503          */
 504         public function convert( $toModel, $lossy = '' ) {
 505                 if ( $this->getModel() === $toModel ) {
 506                         // nothing to do, shorten out.
 507                         return $this;
 508                 }
 509
 510                 $lossy = ( $lossy === 'lossy' ); // string flag, convert to boolean for convenience
 511                 $result = false;
 512
 513                 Hooks::run( 'ConvertContent', [ $this, $toModel, $lossy, &$result ] );
 514
 515                 return $result;
 516         }
 517
 518         /**
 519          * Returns a ParserOutput object containing information derived from this content.
 520          * Most importantly, unless $generateHtml was false, the return value contains an
 521          * HTML representation of the content.
 522          *
 523          * Subclasses that want to control the parser output may override this, but it is
 524          * preferred to override fillParserOutput() instead.
 525          *
 526          * Subclasses that override getParserOutput() itself should take care to call the
 527          * ContentGetParserOutput hook.
 528          *
 529          * @since 1.24
 530          *
 531          * @param Title $title Context title for parsing
 532          * @param int|null $revId Revision ID being rendered
 533          * @param ParserOptions|null $options
 534          * @param bool $generateHtml Whether or not to generate HTML
 535          *
 536          * @return ParserOutput Containing information derived from this content.
 537          */
 538         public function getParserOutput( Title $title, $revId = null,
 539                 ParserOptions $options = null, $generateHtml = true
 540         ) {
 541                 if ( $options === null ) {
 542                         $options = ParserOptions::newCanonical( 'canonical' );
 543                 }
 544
 545                 $po = new ParserOutput();
 546                 $options->registerWatcher( [ $po, 'recordOption' ] );
 547
 548                 if ( Hooks::run( 'ContentGetParserOutput',
 549                         [ $this, $title, $revId, $options, $generateHtml, &$po ] )
 550                 ) {
 551                         // Save and restore the old value, just in case something is reusing
 552                         // the ParserOptions object in some weird way.
 553                         $oldRedir = $options->getRedirectTarget();
 554                         $options->setRedirectTarget( $this->getRedirectTarget() );
 555                         $this->fillParserOutput( $title, $revId, $options, $generateHtml, $po );
 556                         $options->setRedirectTarget( $oldRedir );
 557                 }
 558
 559                 Hooks::run( 'ContentAlterParserOutput', [ $this, $title, $po ] );
 560                 $options->registerWatcher( null );
 561
 562                 return $po;
 563         }
 564
 565         /**
 566          * Fills the provided ParserOutput with information derived from the content.
 567          * Unless $generateHtml was false, this includes an HTML representation of the content.
 568          *
 569          * This is called by getParserOutput() after consulting the ContentGetParserOutput hook.
 570          * Subclasses are expected to override this method (or getParserOutput(), if need be).
 571          * Subclasses of TextContent should generally override getHtml() instead.
 572          *
 573          * This placeholder implementation always throws an exception.
 574          *
 575          * @since 1.24
 576          *
 577          * @param Title $title Context title for parsing
 578          * @param int|null $revId ID of the revision being rendered.
 579          *  See Parser::parse() for the ramifications.
 580          * @param ParserOptions $options
 581          * @param bool $generateHtml Whether or not to generate HTML
 582          * @param ParserOutput &$output The output object to fill (reference).
 583          *
 584          * @throws MWException
 585          */
 586         protected function fillParserOutput( Title $title, $revId,
 587                 ParserOptions $options, $generateHtml, ParserOutput &$output
 588         ) {
 589                 // Don't make abstract, so subclasses that override getParserOutput() directly don't fail.
 590                 throw new MWException( 'Subclasses of AbstractContent must override fillParserOutput!' );
 591         }
 592 }