MediaWiki REL1_39
Content Interface Reference

Base interface for content objects. More...

Inheritance diagram for Content:

Public Member Functions

 addSectionHeader ( $header)
 Returns a new WikitextContent object with the given section heading prepended, if supported.
 
 convert ( $toModel, $lossy='')
 Converts this content object into another content object with the given content model, if that is possible.
 
 copy ()
 Return a copy of this Content object.
 
 equals (Content $that=null)
 Returns true if this Content objects is conceptually equivalent to the given Content object.
 
 getContentHandler ()
 Convenience method that returns the ContentHandler singleton for handling the content model that this Content object uses.
 
 getDefaultFormat ()
 Convenience method that returns the default serialization format for the content model that this Content object uses.
 
 getModel ()
 Returns the ID of the content model used by this Content object.
 
 getNativeData ()
 Returns native representation of the data.
 
 getParserOutput (Title $title, $revId=null, ParserOptions $options=null, $generateHtml=true)
 Parse the Content object and generate a ParserOutput from the result.
 
 getRedirectTarget ()
 Construct the redirect destination from this content and return a Title, or null if this content doesn't represent a redirect.
 
 getSection ( $sectionId)
 Returns the section with the given ID.
 
 getSize ()
 Returns the content's nominal size in "bogo-bytes".
 
 getSupportedFormats ()
 Convenience method that returns the list of serialization formats supported for the content model that this Content object uses.
 
 getTextForSearchIndex ()
 
 getTextForSummary ( $maxLength=250)
 Returns a textual representation of the content suitable for use in edit summaries and log messages.
 
 getWikitextForTransclusion ()
 
 isCountable ( $hasLinks=null)
 Returns true if this content is countable as a "real" wiki page, provided that it's also in a countable location (e.g.
 
 isEmpty ()
 Returns true if this Content object represents empty content.
 
 isRedirect ()
 Returns whether this Content represents a redirect.
 
 isSupportedFormat ( $format)
 Returns true if $format is a supported serialization format for this Content object, false if it isn't.
 
 isValid ()
 Returns whether the content is valid.
 
 matchMagicWord (MagicWord $word)
 Returns true if this Content object matches the given magic word.
 
 preloadTransform (Title $title, ParserOptions $parserOptions, $params=[])
 Returns a Content object with preload transformations applied (or this object if no transformations apply).
 
 prepareSave (WikiPage $page, $flags, $parentRevId, User $user)
 Prepare Content for saving.
 
 preSaveTransform (Title $title, User $user, ParserOptions $parserOptions)
 Returns a Content object with pre-save transformations applied (or this object if no transformations apply).
 
 replaceSection ( $sectionId, Content $with, $sectionTitle='')
 Replaces a section of the content and returns a Content object with the section replaced.
 
 serialize ( $format=null)
 Convenience method for serializing this Content object.
 
 updateRedirect (Title $target)
 If this Content object is a redirect, this method updates the redirect target.
 

Detailed Description

Base interface for content objects.

Stability: unstable
for implementation, extensions should extend AbstractContent instead.

Definition at line 35 of file Content.php.

Member Function Documentation

◆ addSectionHeader()

Content::addSectionHeader ( $header)

Returns a new WikitextContent object with the given section heading prepended, if supported.

The default implementation just returns this Content object unmodified, ignoring the section header.

Since
1.21
Parameters
string$header
Returns
Content

Implemented in AbstractContent, and WikitextContent.

◆ convert()

Content::convert ( $toModel,
$lossy = '' )

Converts this content object into another content object with the given content model, if that is possible.

Parameters
string$toModelThe desired content model, use the CONTENT_MODEL_XXX flags.
string$lossyOptional flag, set to "lossy" to allow lossy conversion. If lossy conversion is not allowed, full round-trip conversion is expected to work without losing information.
Returns
Content|bool A content object with the content model $toModel, or false if that conversion is not supported.

Implemented in AbstractContent, FallbackContent, and TextContent.

◆ copy()

Content::copy ( )

Return a copy of this Content object.

The following must be true for the object returned:

if $copy = $original->copy()

  • get_class($original) === get_class($copy)
  • $original->getModel() === $copy->getModel()
  • $original->equals( $copy )

If and only if the Content object is immutable, the copy() method can and should return $this. That is, $copy === $original may be true, but only for immutable content objects.

Since
1.21
Returns
Content A copy of this object

Implemented in FallbackContent, MessageContent, and TextContent.

◆ equals()

Content::equals ( Content $that = null)

Returns true if this Content objects is conceptually equivalent to the given Content object.

Contract:

  • Will return false if $that is null.
  • Will return true if $that === $this.
  • Will return false if $that->getModel() !== $this->getModel().
  • Will return false if get_class( $that ) !== get_class( $this )
  • Should return false if $that->getModel() == $this->getModel() and $that is not semantically equivalent to $this, according to the data model defined by $this->getModel().

Implementations should be careful to make equals() transitive and reflexive:

  • $a->equals( $b ) <=> $b->equals( $a )
  • $a->equals( $b ) && $b->equals( $c ) ==> $a->equals( $c )
Since
1.21
Parameters
Content | null$thatThe Content object to compare to.
Returns
bool True if this Content object is equal to $that, false otherwise.

Implemented in AbstractContent.

Referenced by ContentHandler\getUndoContent().

◆ getContentHandler()

Content::getContentHandler ( )

Convenience method that returns the ContentHandler singleton for handling the content model that this Content object uses.

Shorthand for ContentHandler::getForContent( $this )

Since
1.21
Returns
ContentHandler

Implemented in AbstractContent.

Referenced by DifferenceEngine\generateContentDiffBody().

◆ getDefaultFormat()

Content::getDefaultFormat ( )

Convenience method that returns the default serialization format for the content model that this Content object uses.

Shorthand for $this->getContentHandler()->getDefaultFormat()

Since
1.21
Returns
string

Implemented in AbstractContent.

Referenced by WikiRevision\setContent().

◆ getModel()

Content::getModel ( )

Returns the ID of the content model used by this Content object.

Corresponds to the CONTENT_MODEL_XXX constants.

Since
1.21
Returns
string The model id

Implemented in AbstractContent.

Referenced by TextContent\diff(), ContentHandler\getUndoContent(), TextContentHandler\merge3(), WikitextContent\replaceSection(), and WikiRevision\setContent().

◆ getNativeData()

Content::getNativeData ( )

Returns native representation of the data.

Interpretation depends on the data model used, as given by getDataModel().

Since
1.21
Deprecated
since 1.33 use getText() for TextContent instances. For other content models, use specialized getters.
Returns
mixed The native representation of the content. Could be a string, a nested array structure, an object, a binary blob... anything, really.
Note
Caller must be aware of content model!

Implemented in AbstractContent, FallbackContent, MessageContent, and TextContent.

◆ getParserOutput()

Content::getParserOutput ( Title $title,
$revId = null,
ParserOptions $options = null,
$generateHtml = true )

Parse the Content object and generate a ParserOutput from the result.

$result->getText() can be used to obtain the generated HTML. If no HTML is needed, $generateHtml can be set to false; in that case, $result->getText() may return null.

Note
To control which options are used in the cache key for the generated parser output, implementations of this method may call ParserOutput::recordOption() on the output object.
Deprecated
since 1.38. Hard-deprecated since 1.38. Use ContentRenderer::getParserOutput and override ContentHandler::fillParserOutput.
Parameters
Title$titleThe page title to use as a context for rendering.
int | null$revIdID of the revision being rendered. See Parser::parse() for the ramifications. (default: null)
ParserOptions | null$optionsAny parser options.
bool$generateHtmlWhether to generate HTML (default: true). If false, the result of calling getText() on the ParserOutput object returned by this method is undefined.
Since
1.21
Returns
ParserOutput

Implemented in AbstractContent.

◆ getRedirectTarget()

Content::getRedirectTarget ( )

Construct the redirect destination from this content and return a Title, or null if this content doesn't represent a redirect.

Since
1.21
Returns
Title|null

Implemented in AbstractContent, CssContent, JavaScriptContent, and WikitextContent.

◆ getSection()

Content::getSection ( $sectionId)

Returns the section with the given ID.

Since
1.21
Parameters
string | int$sectionIdSection identifier as a number or string (e.g. 0, 1 or 'T-1'). The ID "0" retrieves the section before the first heading, "1" the text between the first heading (included) and the second heading (excluded), etc.
Returns
Content|bool|null The section, or false if no such section exist, or null if sections are not supported.

Implemented in AbstractContent, and WikitextContent.

Referenced by EditPage\getContentObject().

◆ getSize()

Content::getSize ( )

Returns the content's nominal size in "bogo-bytes".

Returns
int

Implemented in FallbackContent, MessageContent, and TextContent.

◆ getSupportedFormats()

Content::getSupportedFormats ( )

Convenience method that returns the list of serialization formats supported for the content model that this Content object uses.

Shorthand for $this->getContentHandler()->getSupportedFormats()

Since
1.21
Returns
string[] List of supported serialization formats

Implemented in AbstractContent.

◆ getTextForSearchIndex()

Content::getTextForSearchIndex ( )
Since
1.21
Returns
string A string representing the content in a way useful for building a full text search index. If no useful representation exists, this method returns an empty string.
Todo

Test that this actually works

Make sure this also works with LuceneSearch / WikiSearch

Implemented in FallbackContent, MessageContent, and TextContent.

◆ getTextForSummary()

Content::getTextForSummary ( $maxLength = 250)

Returns a textual representation of the content suitable for use in edit summaries and log messages.

Since
1.21
Parameters
int$maxLengthMaximum length of the summary text, in bytes. Usually implemented using Language::truncateForDatabase().
Returns
string The summary text.

Implemented in FallbackContent, MessageContent, TextContent, and WikitextContent.

◆ getWikitextForTransclusion()

Content::getWikitextForTransclusion ( )
Since
1.21
Returns
string|bool The wikitext to include when another page includes this content, or false if the content is not includable in a wikitext page.
Todo

Allow native handling, bypassing wikitext representation, like for includable special pages.

Allow transclusion into other content models than Wikitext!

Used in WikiPage and MessageCache to get message text. Not so nice. What should we use instead?!

Implemented in FallbackContent, MessageContent, and TextContent.

◆ isCountable()

Content::isCountable ( $hasLinks = null)

Returns true if this content is countable as a "real" wiki page, provided that it's also in a countable location (e.g.

a current revision in the main namespace).

See also
SlotRoleHandler::supportsArticleCount
Since
1.21
Parameters
bool | null$hasLinksIf it is known whether this content contains links, provide this information here, to avoid redundant parsing to find out.
Returns
bool

Implemented in FallbackContent, MessageContent, and TextContent.

◆ isEmpty()

Content::isEmpty ( )

Returns true if this Content object represents empty content.

Since
1.21
Returns
bool Whether this Content object is empty

Implemented in AbstractContent.

◆ isRedirect()

Content::isRedirect ( )

Returns whether this Content represents a redirect.

Shorthand for getRedirectTarget() !== null.

See also
SlotRoleHandler::supportsRedirects
Since
1.21
Returns
bool

Implemented in AbstractContent.

◆ isSupportedFormat()

Content::isSupportedFormat ( $format)

Returns true if $format is a supported serialization format for this Content object, false if it isn't.

Note that this should always return true if $format is null, because null stands for the default serialization.

Shorthand for $this->getContentHandler()->isSupportedFormat( $format )

Since
1.21
Parameters
string$formatThe serialization format to check.
Returns
bool Whether the format is supported

Implemented in AbstractContent.

◆ isValid()

Content::isValid ( )

Returns whether the content is valid.

This is intended for local validity checks, not considering global consistency.

Content needs to be valid before it can be saved.

This default implementation always returns true.

Since
1.21
Returns
bool

Implemented in AbstractContent, and JsonContent.

◆ matchMagicWord()

Content::matchMagicWord ( MagicWord $word)

Returns true if this Content object matches the given magic word.

Since
1.21
Parameters
MagicWord$wordThe magic word to match
Returns
bool Whether this Content object matches the given magic word.

Implemented in AbstractContent, and WikitextContent.

◆ preloadTransform()

Content::preloadTransform ( Title $title,
ParserOptions $parserOptions,
$params = [] )

Returns a Content object with preload transformations applied (or this object if no transformations apply).

Since
1.21
Deprecated
since 1.37. Hard-deprecated since 1.37. Use ContentTransformer::preloadTransform and override ContentHandler::preloadTransform.
Parameters
Title$title
ParserOptions$parserOptions
array$params
Returns
Content

Implemented in AbstractContent.

◆ prepareSave()

Content::prepareSave ( WikiPage $page,
$flags,
$parentRevId,
User $user )

Prepare Content for saving.

Called before Content is saved by WikiPage::doUserEditContent() and in similar places.

This may be used to check the content's consistency with global state. This function should NOT write any information to the database.

Note that this method will usually be called inside the same transaction bracket that will be used to save the new revision.

Note that this method is called before any update to the page table is performed. This means that $page may not yet know a page ID.

Since
1.21
Deprecated
since 1.38. Hard-deprecated since 1.38. Use ContentHandler::validateSave instead.
Parameters
WikiPage$pageThe page to be saved.
int$flagsBitfield for use with EDIT_XXX constants, see WikiPage::doUserEditContent()
int$parentRevIdThe ID of the current revision
User$user
Returns
Status A status object indicating whether the content was successfully prepared for saving. If the returned status indicates an error, a rollback will be performed and the transaction aborted.
See also
WikiPage::doUserEditContent()

Implemented in AbstractContent.

◆ preSaveTransform()

Content::preSaveTransform ( Title $title,
User $user,
ParserOptions $parserOptions )

Returns a Content object with pre-save transformations applied (or this object if no transformations apply).

Since
1.21
Deprecated
since 1.37. Hard-deprecated since 1.37. Use ContentTransformer::preSaveTransform and override ContentHandler::preSaveTransform.
Parameters
Title$title
User$user
ParserOptions$parserOptions
Returns
Content

Implemented in AbstractContent.

◆ replaceSection()

Content::replaceSection ( $sectionId,
Content $with,
$sectionTitle = '' )

Replaces a section of the content and returns a Content object with the section replaced.

Since
1.21
Parameters
string | int | null | bool$sectionIdSection identifier as a number or string (e.g. 0, 1 or 'T-1'), null/false or an empty string for the whole page or 'new' for a new section.
Content$withNew content of the section
string$sectionTitleNew section's subject, only if $section is 'new'
Returns
Content|null New content of the entire page, or null if error

Implemented in AbstractContent, and WikitextContent.

◆ serialize()

Content::serialize ( $format = null)

Convenience method for serializing this Content object.

Shorthand for $this->getContentHandler()->serializeContent( $this, $format )

Since
1.21
Parameters
string | null$formatThe desired serialization format, or null for the default format.
Returns
string Serialized form of this Content object.

Implemented in AbstractContent, and FallbackContent.

Referenced by AbstractContent\equalsInternal(), and WikiRevision\setContent().

◆ updateRedirect()

Content::updateRedirect ( Title $target)

If this Content object is a redirect, this method updates the redirect target.

Otherwise, it does nothing.

Since
1.21
Parameters
Title$targetThe new redirect target
Returns
Content A new Content object with the updated redirect (or $this if this Content object isn't a redirect)

Implemented in AbstractContent, CssContent, JavaScriptContent, and WikitextContent.


The documentation for this interface was generated from the following file: