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 $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          */
  59         public function getModel() {
  60                 return $this->model_id;
  61         }
  62
  63         /**
  64          * @since 1.21
  65          *
  66          * @param string $modelId The model to check
  67          *
  68          * @throws MWException If the provided ID is not the ID of the content model supported by this
  69          * Content object.
  70          */
  71         protected function checkModelID( $modelId ) {
  72                 if ( $modelId !== $this->model_id ) {
  73                         throw new MWException(
  74                                 "Bad content model: " .
  75                                 "expected {$this->model_id} " .
  76                                 "but got $modelId."
  77                         );
  78                 }
  79         }
  80
  81         /**
  82          * @since 1.21
  83          *
  84          * @see Content::getContentHandler
  85          */
  86         public function getContentHandler() {
  87                 return ContentHandler::getForContent( $this );
  88         }
  89
  90         /**
  91          * @since 1.21
  92          *
  93          * @see Content::getDefaultFormat
  94          */
  95         public function getDefaultFormat() {
  96                 return $this->getContentHandler()->getDefaultFormat();
  97         }
  98
  99         /**
 100          * @since 1.21
 101          *
 102          * @see Content::getSupportedFormats
 103          */
 104         public function getSupportedFormats() {
 105                 return $this->getContentHandler()->getSupportedFormats();
 106         }
 107
 108         /**
 109          * @since 1.21
 110          *
 111          * @param string $format
 112          *
 113          * @return bool
 114          *
 115          * @see Content::isSupportedFormat
 116          */
 117         public function isSupportedFormat( $format ) {
 118                 if ( !$format ) {
 119                         return true; // this means "use the default"
 120                 }
 121
 122                 return $this->getContentHandler()->isSupportedFormat( $format );
 123         }
 124
 125         /**
 126          * @since 1.21
 127          *
 128          * @param string $format The serialization format to check.
 129          *
 130          * @throws MWException If the format is not supported by this content handler.
 131          */
 132         protected function checkFormat( $format ) {
 133                 if ( !$this->isSupportedFormat( $format ) ) {
 134                         throw new MWException(
 135                                 "Format $format is not supported for content model " .
 136                                 $this->getModel()
 137                         );
 138                 }
 139         }
 140
 141         /**
 142          * @since 1.21
 143          *
 144          * @param string $format
 145          *
 146          * @return string
 147          *
 148          * @see Content::serialize
 149          */
 150         public function serialize( $format = null ) {
 151                 return $this->getContentHandler()->serializeContent( $this, $format );
 152         }
 153
 154         /**
 155          * @since 1.21
 156          *
 157          * @return bool
 158          *
 159          * @see Content::isEmpty
 160          */
 161         public function isEmpty() {
 162                 return $this->getSize() === 0;
 163         }
 164
 165         /**
 166          * Subclasses may override this to implement (light weight) validation.
 167          *
 168          * @since 1.21
 169          *
 170          * @return bool Always true.
 171          *
 172          * @see Content::isValid
 173          */
 174         public function isValid() {
 175                 return true;
 176         }
 177
 178         /**
 179          * @since 1.21
 180          *
 181          * @param Content $that
 182          *
 183          * @return bool
 184          *
 185          * @see Content::equals
 186          */
 187         public function equals( Content $that = null ) {
 188                 if ( is_null( $that ) ) {
 189                         return false;
 190                 }
 191
 192                 if ( $that === $this ) {
 193                         return true;
 194                 }
 195
 196                 if ( $that->getModel() !== $this->getModel() ) {
 197                         return false;
 198                 }
 199
 200                 return $this->getNativeData() === $that->getNativeData();
 201         }
 202
 203         /**
 204          * Returns a list of DataUpdate objects for recording information about this
 205          * Content in some secondary data store.
 206          *
 207          * This default implementation returns a LinksUpdate object and calls the
 208          * SecondaryDataUpdates hook.
 209          *
 210          * Subclasses may override this to determine the secondary data updates more
 211          * efficiently, preferably without the need to generate a parser output object.
 212          * They should however make sure to call SecondaryDataUpdates to give extensions
 213          * a chance to inject additional updates.
 214          *
 215          * @since 1.21
 216          *
 217          * @param Title $title
 218          * @param Content $old
 219          * @param bool $recursive
 220          * @param ParserOutput $parserOutput
 221          *
 222          * @return DataUpdate[]
 223          *
 224          * @see Content::getSecondaryDataUpdates()
 225          */
 226         public function getSecondaryDataUpdates( Title $title, Content $old = null,
 227                 $recursive = true, ParserOutput $parserOutput = null
 228         ) {
 229                 if ( $parserOutput === null ) {
 230                         $parserOutput = $this->getParserOutput( $title, null, null, false );
 231                 }
 232
 233                 $updates = array(
 234                         new LinksUpdate( $title, $parserOutput, $recursive )
 235                 );
 236
 237                 Hooks::run( 'SecondaryDataUpdates', array( $title, $old, $recursive, $parserOutput, &$updates ) );
 238
 239                 return $updates;
 240         }
 241
 242         /**
 243          * @since 1.21
 244          *
 245          * @return Title[]|null
 246          *
 247          * @see Content::getRedirectChain
 248          */
 249         public function getRedirectChain() {
 250                 global $wgMaxRedirects;
 251                 $title = $this->getRedirectTarget();
 252                 if ( is_null( $title ) ) {
 253                         return null;
 254                 }
 255                 // recursive check to follow double redirects
 256                 $recurse = $wgMaxRedirects;
 257                 $titles = array( $title );
 258                 while ( --$recurse > 0 ) {
 259                         if ( $title->isRedirect() ) {
 260                                 $page = WikiPage::factory( $title );
 261                                 $newtitle = $page->getRedirectTarget();
 262                         } else {
 263                                 break;
 264                         }
 265                         // Redirects to some special pages are not permitted
 266                         if ( $newtitle instanceof Title && $newtitle->isValidRedirectTarget() ) {
 267                                 // The new title passes the checks, so make that our current
 268                                 // title so that further recursion can be checked
 269                                 $title = $newtitle;
 270                                 $titles[] = $newtitle;
 271                         } else {
 272                                 break;
 273                         }
 274                 }
 275
 276                 return $titles;
 277         }
 278
 279         /**
 280          * Subclasses that implement redirects should override this.
 281          *
 282          * @since 1.21
 283          *
 284          * @return null
 285          *
 286          * @see Content::getRedirectTarget
 287          */
 288         public function getRedirectTarget() {
 289                 return null;
 290         }
 291
 292         /**
 293          * @note Migrated here from Title::newFromRedirectRecurse.
 294          *
 295          * @since 1.21
 296          *
 297          * @return Title|null
 298          *
 299          * @see Content::getUltimateRedirectTarget
 300          */
 301         public function getUltimateRedirectTarget() {
 302                 $titles = $this->getRedirectChain();
 303
 304                 return $titles ? array_pop( $titles ) : null;
 305         }
 306
 307         /**
 308          * @since 1.21
 309          *
 310          * @return bool
 311          *
 312          * @see Content::isRedirect
 313          */
 314         public function isRedirect() {
 315                 return $this->getRedirectTarget() !== null;
 316         }
 317
 318         /**
 319          * This default implementation always returns $this.
 320          * Subclasses that implement redirects should override this.
 321          *
 322          * @since 1.21
 323          *
 324          * @param Title $target
 325          *
 326          * @return Content $this
 327          *
 328          * @see Content::updateRedirect
 329          */
 330         public function updateRedirect( Title $target ) {
 331                 return $this;
 332         }
 333
 334         /**
 335          * @since 1.21
 336          *
 337          * @return null
 338          *
 339          * @see Content::getSection
 340          */
 341         public function getSection( $sectionId ) {
 342                 return null;
 343         }
 344
 345         /**
 346          * @since 1.21
 347          *
 348          * @return null
 349          *
 350          * @see Content::replaceSection
 351          */
 352         public function replaceSection( $sectionId, Content $with, $sectionTitle = '' ) {
 353                 return null;
 354         }
 355
 356         /**
 357          * @since 1.21
 358          *
 359          * @return Content $this
 360          *
 361          * @see Content::preSaveTransform
 362          */
 363         public function preSaveTransform( Title $title, User $user, ParserOptions $popts ) {
 364                 return $this;
 365         }
 366
 367         /**
 368          * @since 1.21
 369          *
 370          * @return Content $this
 371          *
 372          * @see Content::addSectionHeader
 373          */
 374         public function addSectionHeader( $header ) {
 375                 return $this;
 376         }
 377
 378         /**
 379          * @since 1.21
 380          *
 381          * @return Content $this
 382          *
 383          * @see Content::preloadTransform
 384          */
 385         public function preloadTransform( Title $title, ParserOptions $popts, $params = array() ) {
 386                 return $this;
 387         }
 388
 389         /**
 390          * @since 1.21
 391          *
 392          * @return Status
 393          *
 394          * @see Content::prepareSave
 395          */
 396         public function prepareSave( WikiPage $page, $flags, $parentRevId, User $user ) {
 397                 if ( $this->isValid() ) {
 398                         return Status::newGood();
 399                 } else {
 400                         return Status::newFatal( "invalid-content-data" );
 401                 }
 402         }
 403
 404         /**
 405          * @since 1.21
 406          *
 407          * @param WikiPage $page
 408          * @param ParserOutput $parserOutput
 409          *
 410          * @return LinksDeletionUpdate[]
 411          *
 412          * @see Content::getDeletionUpdates
 413          */
 414         public function getDeletionUpdates( WikiPage $page, ParserOutput $parserOutput = null ) {
 415                 return array(
 416                         new LinksDeletionUpdate( $page ),
 417                 );
 418         }
 419
 420         /**
 421          * This default implementation always returns false. Subclasses may override
 422          * this to supply matching logic.
 423          *
 424          * @since 1.21
 425          *
 426          * @param MagicWord $word
 427          *
 428          * @return bool Always false.
 429          *
 430          * @see Content::matchMagicWord
 431          */
 432         public function matchMagicWord( MagicWord $word ) {
 433                 return false;
 434         }
 435
 436         /**
 437          * This base implementation calls the hook ConvertContent to enable custom conversions.
 438          * Subclasses may override this to implement conversion for "their" content model.
 439          *
 440          * @param string $toModel
 441          * @param string $lossy
 442          *
 443          * @return Content|bool
 444          *
 445          * @see Content::convert()
 446          */
 447         public function convert( $toModel, $lossy = '' ) {
 448                 if ( $this->getModel() === $toModel ) {
 449                         // nothing to do, shorten out.
 450                         return $this;
 451                 }
 452
 453                 $lossy = ( $lossy === 'lossy' ); // string flag, convert to boolean for convenience
 454                 $result = false;
 455
 456                 Hooks::run( 'ConvertContent', array( $this, $toModel, $lossy, &$result ) );
 457
 458                 return $result;
 459         }
 460
 461         /**
 462          * Returns a ParserOutput object containing information derived from this content.
 463          * Most importantly, unless $generateHtml was false, the return value contains an
 464          * HTML representation of the content.
 465          *
 466          * Subclasses that want to control the parser output may override this, but it is
 467          * preferred to override fillParserOutput() instead.
 468          *
 469          * Subclasses that override getParserOutput() itself should take care to call the
 470          * ContentGetParserOutput hook.
 471          *
 472          * @since 1.24
 473          *
 474          * @param Title $title Context title for parsing
 475          * @param int|null $revId Revision ID (for {{REVISIONID}})
 476          * @param ParserOptions|null $options Parser options
 477          * @param bool $generateHtml Whether or not to generate HTML
 478          *
 479          * @return ParserOutput Containing information derived from this content.
 480          */
 481         public function getParserOutput( Title $title, $revId = null,
 482                 ParserOptions $options = null, $generateHtml = true
 483         ) {
 484                 if ( $options === null ) {
 485                         $options = $this->getContentHandler()->makeParserOptions( 'canonical' );
 486                 }
 487
 488                 $po = new ParserOutput();
 489
 490                 if ( Hooks::run( 'ContentGetParserOutput',
 491                         array( $this, $title, $revId, $options, $generateHtml, &$po ) ) ) {
 492
 493                         // Save and restore the old value, just in case something is reusing
 494                         // the ParserOptions object in some weird way.
 495                         $oldRedir = $options->getRedirectTarget();
 496                         $options->setRedirectTarget( $this->getRedirectTarget() );
 497                         $this->fillParserOutput( $title, $revId, $options, $generateHtml, $po );
 498                         $options->setRedirectTarget( $oldRedir );
 499                 }
 500
 501                 Hooks::run( 'ContentAlterParserOutput', array( $this, $title, $po ) );
 502
 503                 return $po;
 504         }
 505
 506         /**
 507          * Fills the provided ParserOutput with information derived from the content.
 508          * Unless $generateHtml was false, this includes an HTML representation of the content.
 509          *
 510          * This is called by getParserOutput() after consulting the ContentGetParserOutput hook.
 511          * Subclasses are expected to override this method (or getParserOutput(), if need be).
 512          * Subclasses of TextContent should generally override getHtml() instead.
 513          *
 514          * This placeholder implementation always throws an exception.
 515          *
 516          * @since 1.24
 517          *
 518          * @param Title $title Context title for parsing
 519          * @param int|null $revId Revision ID (for {{REVISIONID}})
 520          * @param ParserOptions $options Parser options
 521          * @param bool $generateHtml Whether or not to generate HTML
 522          * @param ParserOutput &$output The output object to fill (reference).
 523          *
 524          * @throws MWException
 525          */
 526         protected function fillParserOutput( Title $title, $revId,
 527                 ParserOptions $options, $generateHtml, ParserOutput &$output
 528         ) {
 529                 // Don't make abstract, so subclasses that override getParserOutput() directly don't fail.
 530                 throw new MWException( 'Subclasses of AbstractContent must override fillParserOutput!' );
 531         }
 532 }