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.
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.
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.
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
26 * @author Daniel Kinzler
30 * Base implementation for content objects.
34 abstract class AbstractContent
implements Content
{
36 * Name of the content model this Content object represents.
37 * Use with CONTENT_MODEL_XXX constants
41 * @var string $model_id
46 * @param string|null $modelId
50 public function __construct( $modelId = null ) {
51 $this->model_id
= $modelId;
57 * @see Content::getModel
60 public function getModel() {
61 return $this->model_id
;
67 * @param string $modelId The model to check
69 * @throws MWException If the provided ID is not the ID of the content model supported by this
72 protected function checkModelID( $modelId ) {
73 if ( $modelId !== $this->model_id
) {
74 throw new MWException(
75 "Bad content model: " .
76 "expected {$this->model_id} " .
85 * @see Content::getContentHandler
86 * @return ContentHandler
88 public function getContentHandler() {
89 return ContentHandler
::getForContent( $this );
95 * @see Content::getDefaultFormat
98 public function getDefaultFormat() {
99 return $this->getContentHandler()->getDefaultFormat();
105 * @see Content::getSupportedFormats
108 public function getSupportedFormats() {
109 return $this->getContentHandler()->getSupportedFormats();
115 * @param string $format
119 * @see Content::isSupportedFormat
121 public function isSupportedFormat( $format ) {
123 return true; // this means "use the default"
126 return $this->getContentHandler()->isSupportedFormat( $format );
132 * @param string $format The serialization format to check.
134 * @throws MWException If the format is not supported by this content handler.
136 protected function checkFormat( $format ) {
137 if ( !$this->isSupportedFormat( $format ) ) {
138 throw new MWException(
139 "Format $format is not supported for content model " .
148 * @param string|null $format
152 * @see Content::serialize
154 public function serialize( $format = null ) {
155 return $this->getContentHandler()->serializeContent( $this, $format );
163 * @see Content::isEmpty
165 public function isEmpty() {
166 return $this->getSize() === 0;
170 * Subclasses may override this to implement (light weight) validation.
174 * @return bool Always true.
176 * @see Content::isValid
178 public function isValid() {
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.
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
196 * @param Content|null $that
200 * @see Content::equals
202 public function equals( Content
$that = null ) {
203 if ( is_null( $that ) ) {
207 if ( $that === $this ) {
211 if ( $that->getModel() !== $this->getModel() ) {
215 // For type safety. Needed for odd cases like MessageContent using CONTENT_MODEL_WIKITEXT
216 if ( get_class( $that ) !== get_class( $this ) ) {
220 return $this->equalsInternal( $that );
224 * Checks whether $that is logically equal to this Content object.
226 * This method can be overwritten by subclasses that need to implement custom
229 * This default implementation checks whether the serializations
230 * of $this and $that are the same: $this->serialize() === $that->serialize()
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().
236 * @note Do not call this method directly, call equals() instead.
238 * @param Content $that
241 protected function equalsInternal( Content
$that ) {
242 return $this->serialize() === $that->serialize();
246 * Returns a list of DataUpdate objects for recording information about this
247 * Content in some secondary data store.
249 * This default implementation returns a LinksUpdate object and calls the
250 * SecondaryDataUpdates hook.
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.
259 * @param Title $title
260 * @param Content|null $old
261 * @param bool $recursive
262 * @param ParserOutput|null $parserOutput
264 * @return DataUpdate[]
266 * @see Content::getSecondaryDataUpdates()
268 public function getSecondaryDataUpdates( Title
$title, Content
$old = null,
269 $recursive = true, ParserOutput
$parserOutput = null
271 if ( $parserOutput === null ) {
272 $parserOutput = $this->getParserOutput( $title, null, null, false );
276 new LinksUpdate( $title, $parserOutput, $recursive )
279 Hooks
::run( 'SecondaryDataUpdates', [ $title, $old, $recursive, $parserOutput, &$updates ] );
287 * @return Title[]|null
289 * @see Content::getRedirectChain
291 public function getRedirectChain() {
292 global $wgMaxRedirects;
293 $title = $this->getRedirectTarget();
294 if ( is_null( $title ) ) {
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();
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
312 $titles[] = $newtitle;
322 * Subclasses that implement redirects should override this.
328 * @see Content::getRedirectTarget
330 public function getRedirectTarget() {
335 * @note Migrated here from Title::newFromRedirectRecurse.
341 * @see Content::getUltimateRedirectTarget
343 public function getUltimateRedirectTarget() {
344 $titles = $this->getRedirectChain();
346 return $titles ?
array_pop( $titles ) : null;
354 * @see Content::isRedirect
356 public function isRedirect() {
357 return $this->getRedirectTarget() !== null;
361 * This default implementation always returns $this.
362 * Subclasses that implement redirects should override this.
366 * @param Title $target
368 * @return Content $this
370 * @see Content::updateRedirect
372 public function updateRedirect( Title
$target ) {
379 * @param string|int $sectionId
382 * @see Content::getSection
384 public function getSection( $sectionId ) {
391 * @param string|int|null|bool $sectionId
392 * @param Content $with
393 * @param string $sectionTitle
396 * @see Content::replaceSection
398 public function replaceSection( $sectionId, Content
$with, $sectionTitle = '' ) {
405 * @param Title $title
407 * @param ParserOptions $popts
408 * @return Content $this
410 * @see Content::preSaveTransform
412 public function preSaveTransform( Title
$title, User
$user, ParserOptions
$popts ) {
419 * @param string $header
420 * @return Content $this
422 * @see Content::addSectionHeader
424 public function addSectionHeader( $header ) {
431 * @param Title $title
432 * @param ParserOptions $popts
433 * @param array $params
434 * @return Content $this
436 * @see Content::preloadTransform
438 public function preloadTransform( Title
$title, ParserOptions
$popts, $params = [] ) {
445 * @param WikiPage $page
447 * @param int $parentRevId
451 * @see Content::prepareSave
453 public function prepareSave( WikiPage
$page, $flags, $parentRevId, User
$user ) {
454 if ( $this->isValid() ) {
455 return Status
::newGood();
457 return Status
::newFatal( "invalid-content-data" );
464 * @param WikiPage $page
465 * @param ParserOutput|null $parserOutput
467 * @return DeferrableUpdate[]
469 * @see Content::getDeletionUpdates
471 public function getDeletionUpdates( WikiPage
$page, ParserOutput
$parserOutput = null ) {
473 new LinksDeletionUpdate( $page ),
478 * This default implementation always returns false. Subclasses may override
479 * this to supply matching logic.
483 * @param MagicWord $word
485 * @return bool Always false.
487 * @see Content::matchMagicWord
489 public function matchMagicWord( MagicWord
$word ) {
494 * This base implementation calls the hook ConvertContent to enable custom conversions.
495 * Subclasses may override this to implement conversion for "their" content model.
497 * @param string $toModel
498 * @param string $lossy
500 * @return Content|bool
502 * @see Content::convert()
504 public function convert( $toModel, $lossy = '' ) {
505 if ( $this->getModel() === $toModel ) {
506 // nothing to do, shorten out.
510 $lossy = ( $lossy === 'lossy' ); // string flag, convert to boolean for convenience
513 Hooks
::run( 'ConvertContent', [ $this, $toModel, $lossy, &$result ] );
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.
523 * Subclasses that want to control the parser output may override this, but it is
524 * preferred to override fillParserOutput() instead.
526 * Subclasses that override getParserOutput() itself should take care to call the
527 * ContentGetParserOutput hook.
531 * @param Title $title Context title for parsing
532 * @param int|null $revId Revision ID (for {{REVISIONID}})
533 * @param ParserOptions|null $options
534 * @param bool $generateHtml Whether or not to generate HTML
536 * @return ParserOutput Containing information derived from this content.
538 public function getParserOutput( Title
$title, $revId = null,
539 ParserOptions
$options = null, $generateHtml = true
541 if ( $options === null ) {
542 $options = ParserOptions
::newCanonical( 'canonical' );
545 $po = new ParserOutput();
546 $options->registerWatcher( [ $po, 'recordOption' ] );
548 if ( Hooks
::run( 'ContentGetParserOutput',
549 [ $this, $title, $revId, $options, $generateHtml, &$po ] )
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 );
559 Hooks
::run( 'ContentAlterParserOutput', [ $this, $title, $po ] );
560 $options->registerWatcher( null );
566 * Fills the provided ParserOutput with information derived from the content.
567 * Unless $generateHtml was false, this includes an HTML representation of the content.
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.
573 * This placeholder implementation always throws an exception.
577 * @param Title $title Context title for parsing
578 * @param int|null $revId Revision ID (for {{REVISIONID}})
579 * @param ParserOptions $options
580 * @param bool $generateHtml Whether or not to generate HTML
581 * @param ParserOutput &$output The output object to fill (reference).
583 * @throws MWException
585 protected function fillParserOutput( Title
$title, $revId,
586 ParserOptions
$options, $generateHtml, ParserOutput
&$output
588 // Don't make abstract, so subclasses that override getParserOutput() directly don't fail.
589 throw new MWException( 'Subclasses of AbstractContent must override fillParserOutput!' );