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          * @see Content::getModel
  56          *
  57          * @since 1.21
  58          */
  59         public function getModel() {
  60                 return $this->model_id;
  61         }
  62
  63         /**
  64          * Throws an MWException if $model_id is not the id of the content model
  65          * supported by this Content object.
  66          *
  67          * @since 1.21
  68          *
  69          * @param string $modelId The model to check
  70          *
  71          * @throws MWException
  72          */
  73         protected function checkModelID( $modelId ) {
  74                 if ( $modelId !== $this->model_id ) {
  75                         throw new MWException(
  76                                 "Bad content model: " .
  77                                 "expected {$this->model_id} " .
  78                                 "but got $modelId."
  79                         );
  80                 }
  81         }
  82
  83         /**
  84          * @see Content::getContentHandler
  85          *
  86          * @since 1.21
  87          */
  88         public function getContentHandler() {
  89                 return ContentHandler::getForContent( $this );
  90         }
  91
  92         /**
  93          * @see Content::getDefaultFormat
  94          *
  95          * @since 1.21
  96          */
  97         public function getDefaultFormat() {
  98                 return $this->getContentHandler()->getDefaultFormat();
  99         }
 100
 101         /**
 102          * @see Content::getSupportedFormats
 103          *
 104          * @since 1.21
 105          */
 106         public function getSupportedFormats() {
 107                 return $this->getContentHandler()->getSupportedFormats();
 108         }
 109
 110         /**
 111          * @see Content::isSupportedFormat
 112          *
 113          * @param string $format
 114          *
 115          * @since 1.21
 116          *
 117          * @return boolean
 118          */
 119         public function isSupportedFormat( $format ) {
 120                 if ( !$format ) {
 121                         return true; // this means "use the default"
 122                 }
 123
 124                 return $this->getContentHandler()->isSupportedFormat( $format );
 125         }
 126
 127         /**
 128          * Throws an MWException if $this->isSupportedFormat( $format ) does not
 129          * return true.
 130          *
 131          * @since 1.21
 132          *
 133          * @param string $format
 134          * @throws MWException
 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          * @see Content::serialize
 147          *
 148          * @param string|null $format
 149          *
 150          * @since 1.21
 151          *
 152          * @return string
 153          */
 154         public function serialize( $format = null ) {
 155                 return $this->getContentHandler()->serializeContent( $this, $format );
 156         }
 157
 158         /**
 159          * @see Content::isEmpty
 160          *
 161          * @since 1.21
 162          *
 163          * @return boolean
 164          */
 165         public function isEmpty() {
 166                 return $this->getSize() === 0;
 167         }
 168
 169         /**
 170          * @see Content::isValid
 171          *
 172          * @since 1.21
 173          *
 174          * @return boolean
 175          */
 176         public function isValid() {
 177                 return true;
 178         }
 179
 180         /**
 181          * @see Content::equals
 182          *
 183          * @since 1.21
 184          *
 185          * @param Content|null $that
 186          *
 187          * @return boolean
 188          */
 189         public function equals( Content $that = null ) {
 190                 if ( is_null( $that ) ) {
 191                         return false;
 192                 }
 193
 194                 if ( $that === $this ) {
 195                         return true;
 196                 }
 197
 198                 if ( $that->getModel() !== $this->getModel() ) {
 199                         return false;
 200                 }
 201
 202                 return $this->getNativeData() === $that->getNativeData();
 203         }
 204
 205         /**
 206          * Returns a list of DataUpdate objects for recording information about this
 207          * Content in some secondary data store.
 208          *
 209          * This default implementation calls
 210          * $this->getParserOutput( $content, $title, null, null, false ),
 211          * and then calls getSecondaryDataUpdates( $title, $recursive ) on the
 212          * resulting ParserOutput object.
 213          *
 214          * Subclasses may override this to determine the secondary data updates more
 215          * efficiently, preferably without the need to generate a parser output object.
 216          *
 217          * @see Content::getSecondaryDataUpdates()
 218          *
 219          * @param $title Title The context for determining the necessary updates
 220          * @param $old Content|null An optional Content object representing the
 221          *    previous content, i.e. the content being replaced by this Content
 222          *    object.
 223          * @param $recursive boolean Whether to include recursive updates (default:
 224          *    false).
 225          * @param $parserOutput ParserOutput|null Optional ParserOutput object.
 226          *    Provide if you have one handy, to avoid re-parsing of the content.
 227          *
 228          * @return Array. A list of DataUpdate objects for putting information
 229          *    about this content object somewhere.
 230          *
 231          * @since 1.21
 232          */
 233         public function getSecondaryDataUpdates( Title $title,
 234                 Content $old = null,
 235                 $recursive = true, ParserOutput $parserOutput = null
 236         ) {
 237                 if ( $parserOutput === null ) {
 238                         $parserOutput = $this->getParserOutput( $title, null, null, false );
 239                 }
 240
 241                 return $parserOutput->getSecondaryDataUpdates( $title, $recursive );
 242         }
 243
 244         /**
 245          * @see Content::getRedirectChain
 246          *
 247          * @since 1.21
 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          * @see Content::getRedirectTarget
 281          *
 282          * @since 1.21
 283          */
 284         public function getRedirectTarget() {
 285                 return null;
 286         }
 287
 288         /**
 289          * @see Content::getUltimateRedirectTarget
 290          * @note: migrated here from Title::newFromRedirectRecurse
 291          *
 292          * @since 1.21
 293          */
 294         public function getUltimateRedirectTarget() {
 295                 $titles = $this->getRedirectChain();
 296
 297                 return $titles ? array_pop( $titles ) : null;
 298         }
 299
 300         /**
 301          * @see Content::isRedirect
 302          *
 303          * @since 1.21
 304          *
 305          * @return bool
 306          */
 307         public function isRedirect() {
 308                 return $this->getRedirectTarget() !== null;
 309         }
 310
 311         /**
 312          * @see Content::updateRedirect
 313          *
 314          * This default implementation always returns $this.
 315          *
 316          * @param Title $target
 317          *
 318          * @since 1.21
 319          *
 320          * @return Content $this
 321          */
 322         public function updateRedirect( Title $target ) {
 323                 return $this;
 324         }
 325
 326         /**
 327          * @see Content::getSection
 328          *
 329          * @since 1.21
 330          */
 331         public function getSection( $sectionId ) {
 332                 return null;
 333         }
 334
 335         /**
 336          * @see Content::replaceSection
 337          *
 338          * @since 1.21
 339          */
 340         public function replaceSection( $section, Content $with, $sectionTitle = '' ) {
 341                 return null;
 342         }
 343
 344         /**
 345          * @see Content::preSaveTransform
 346          *
 347          * @since 1.21
 348          */
 349         public function preSaveTransform( Title $title, User $user, ParserOptions $popts ) {
 350                 return $this;
 351         }
 352
 353         /**
 354          * @see Content::addSectionHeader
 355          *
 356          * @since 1.21
 357          */
 358         public function addSectionHeader( $header ) {
 359                 return $this;
 360         }
 361
 362         /**
 363          * @see Content::preloadTransform
 364          *
 365          * @since 1.21
 366          */
 367         public function preloadTransform( Title $title, ParserOptions $popts ) {
 368                 return $this;
 369         }
 370
 371         /**
 372          * @see Content::prepareSave
 373          *
 374          * @since 1.21
 375          */
 376         public function prepareSave( WikiPage $page, $flags, $baseRevId, User $user ) {
 377                 if ( $this->isValid() ) {
 378                         return Status::newGood();
 379                 } else {
 380                         return Status::newFatal( "invalid-content-data" );
 381                 }
 382         }
 383
 384         /**
 385          * @see Content::getDeletionUpdates
 386          *
 387          * @since 1.21
 388          *
 389          * @param $page WikiPage the deleted page
 390          * @param $parserOutput null|ParserOutput optional parser output object
 391          *    for efficient access to meta-information about the content object.
 392          *    Provide if you have one handy.
 393          *
 394          * @return array A list of DataUpdate instances that will clean up the
 395          *    database after deletion.
 396          */
 397         public function getDeletionUpdates( WikiPage $page,
 398                 ParserOutput $parserOutput = null
 399         ) {
 400                 return array(
 401                         new LinksDeletionUpdate( $page ),
 402                 );
 403         }
 404
 405         /**
 406          * This default implementation always returns false. Subclasses may override
 407          * this to supply matching logic.
 408          *
 409          * @see Content::matchMagicWord
 410          *
 411          * @since 1.21
 412          *
 413          * @param MagicWord $word
 414          *
 415          * @return bool
 416          */
 417         public function matchMagicWord( MagicWord $word ) {
 418                 return false;
 419         }
 420
 421         /**
 422          * @see Content::convert()
 423          *
 424          * This base implementation calls the hook ConvertContent to enable custom conversions.
 425          * Subclasses may override this to implement conversion for "their" content model.
 426          *
 427          * @param string $toModel the desired content model, use the CONTENT_MODEL_XXX flags.
 428          * @param string $lossy flag, set to "lossy" to allow lossy conversion. If lossy conversion is
 429          * not allowed, full round-trip conversion is expected to work without losing information.
 430          *
 431          * @return Content|bool A content object with the content model $toModel, or false if
 432          * that conversion is not supported.
 433          */
 434         public function convert( $toModel, $lossy = '' ) {
 435                 if ( $this->getModel() === $toModel ) {
 436                         //nothing to do, shorten out.
 437                         return $this;
 438                 }
 439
 440                 $lossy = ( $lossy === 'lossy' ); // string flag, convert to boolean for convenience
 441                 $result = false;
 442
 443                 wfRunHooks( 'ConvertContent', array( $this, $toModel, $lossy, &$result ) );
 444
 445                 return $result;
 446         }
 447 }