<?php
-
/**
* A content object represents page content, e.g. the text to show on a page.
* Content objects have no knowledge about how they relate to Wiki pages.
public abstract function getTextForSummary( $maxlength = 250 );
/**
- * Returns native represenation of the data. Interpretation depends on the data model used,
+ * Returns native representation of the data. Interpretation depends on the data model used,
* as given by getDataModel().
*
* @since WD.1
* supported by this Content object.
*
* @param int $model_id the model to check
+ *
+ * @throws MWException
*/
protected function checkModelID( $model_id ) {
if ( $model_id !== $this->model_id ) {
}
/**
- * Conveniance method that returns the ContentHandler singleton for handling the content
+ * Convenience method that returns the ContentHandler singleton for handling the content
* model this Content object uses.
*
* Shorthand for ContentHandler::getForContent( $this )
}
/**
- * Conveniance method that returns the default serialization format for the content model
+ * Convenience method that returns the default serialization format for the content model
* model this Content object uses.
*
* Shorthand for $this->getContentHandler()->getDefaultFormat()
}
/**
- * Conveniance method that returns the list of serialization formats supported
+ * Convenience method that returns the list of serialization formats supported
* for the content model model this Content object uses.
*
* Shorthand for $this->getContentHandler()->getSupportedFormats()
}
/**
- * Conveniance method for serializing this Content object.
+ * Convenience method for serializing this Content object.
*
* Shorthand for $this->getContentHandler()->serializeContent( $this, $format )
*
*
* Will returns false if $that is null.
* Will return true if $that === $this.
- * Will return false if $that->getModleName() != $this->getModel().
+ * Will return false if $that->getModelName() != $this->getModel().
* Will return false if $that->getNativeData() is not equal to $this->getNativeData(),
* where the meaning of "equal" depends on the actual data model.
*
* Implementations should be careful to make equals() transitive and reflexive:
*
- * * $a->equals( $b ) <=> $b->equals( $b )
+ * * $a->equals( $b ) <=> $b->equals( $a )
* * $a->equals( $b ) && $b->equals( $c ) ==> $a->equals( $c )
*
* @since WD.1
* * $original->getModel() === $copy->getModel()
* * $original->equals( $copy )
*
- * If and only if the Content object is imutable, the copy() method can and should
- * return $this. That is, $copy === $original may be true, but only for imutable content
+ * 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 WD.1
*
* @return ParserOutput
*/
- public abstract function getParserOutput( Title $title, $revId = null, ParserOptions $options = null, $generateHtml = true );
+ public abstract function getParserOutput( Title $title, $revId = null, ParserOptions $options = null, $generateHtml = true ); #TODO: move to ContentHandler; #TODO: rename to getRenderOutput()
+ #TODO: make RenderOutput and RenderOptions base classes
/**
* Returns a list of DataUpdate objects for recording information about this Content in some secondary
* data store. If the optional second argument, $old, is given, the updates may model only the changes that
- * need to be made to replace information about the old content with infomration about the new content.
+ * need to be made to replace information about the old content with information about the new content.
*
* This default implementation calls $this->getParserOutput( $title, null, null, false ), and then
* calls getSecondaryDataUpdates( $title, $recursive ) on the resulting ParserOutput object.
}
/**
- * Construct the redirect destination from this content and return an
- * array of Titles, or null if this content doesn't represent a redirect.
+ * Construct the redirect destination from this content and return a Title,
+ * or null if this content doesn't represent a redirect.
* This will only return the immediate redirect target, useful for
* the redirect table and other checks that don't need full recursion.
*
* @since WD.1
*
* @param String $sectionId the section's id, given as a numeric string. The id "0" retrieves the section before
- * the first heading, "1" the text between the first heading (inluded) and the second heading (excluded), etc.
+ * the first heading, "1" the text between the first heading (included) and the second heading (excluded), etc.
* @return Content|Boolean|null the section, or false if no such section exist, or null if sections are not supported
*/
public function getSection( $sectionId ) {
/**
* Content object implementation for representing flat text.
*
- * TextContent instances are imutable
+ * TextContent instances are immutable
*
* @since WD.1
*/
}
public function copy() {
- return $this; #NOTE: this is ok since TextContent are imutable.
+ return $this; #NOTE: this is ok since TextContent are immutable.
}
public function getTextForSummary( $maxlength = 250 ) {
/**
* Returns a generic ParserOutput object, wrapping the HTML returned by getHtml().
*
+ * @param Title $title context title for parsing
+ * @param int|null $revId revision id (the parser wants that for some reason)
+ * @param ParserOptions|null $options parser options
+ * @param bool $generateHtml whether or not to generate HTML
+ *
* @return ParserOutput representing the HTML form of the text
*/
public function getParserOutput( Title $title, $revId = null, ParserOptions $options = null, $generateHtml = true ) {
return $po;
}
+ /**
+ * Generates an HTML version of the content, for display.
+ * Used by getParserOutput() to construct a ParserOutput object
+ *
+ * @return String
+ */
protected abstract function getHtml( );
/**
$ota = explode( "\n", $wgContLang->segmentForDiff( $otext ) );
$nta = explode( "\n", $wgContLang->segmentForDiff( $ntext ) );
- $diffs = new Diff( $ota, $nta );
+ $diff = new Diff( $ota, $nta );
return $diff;
}
/**
* Returns a ParserOutput object resulting from parsing the content's text using $wgParser.
*
- * @since WikiData1
+ * @since WD.1
*
- * @param IContextSource|null $context
- * @param null $revId
+ * @param \Title $title
+ * @param null $revId
* @param null|ParserOptions $options
- * @param bool $generateHtml
+ * @param bool $generateHtml
*
+ * @internal param \IContextSource|null $context
* @return ParserOutput representing the HTML form of the text
*/
public function getParserOutput( Title $title, $revId = null, ParserOptions $options = null, $generateHtml = true ) {
/**
* Returns the section with the given id.
*
- * @param String $sectionId the section's id
+ * @param String $section
+ *
+ * @internal param String $sectionId the section's id
* @return Content|false|null the section, or false if no such section exist, or null if sections are not supported
*/
public function getSection( $section ) {
/**
* Replaces a section in the wikitext
*
- * @param $section empty/null/false or a section number (0, 1, 2, T1, T2...), or "new"
- * @param $with Content: new content of the section
+ * @param $section empty/null/false or a section number (0, 1, 2, T1, T2...), or "new"
+ * @param $with Content: new content of the section
* @param $sectionTitle String: new section's subject, only if $section is 'new'
+ *
+ * @throws MWException
* @return Content Complete article content, or null if error
*/
public function replaceSection( $section, Content $with, $sectionTitle = '' ) {
* @param ParserOptions $popts
* @return Content
*/
- public function preSaveTransform( Title $title, User $user, ParserOptions $popts ) {
+ public function preSaveTransform( Title $title, User $user, ParserOptions $popts ) { #FIXME: also needed for JS/CSS!
global $wgParser, $wgConteLang;
$text = $this->getNativeData();
/**
* Returns true if this content is not a redirect, and this content's text is countable according to
- * the criteria defiend by $wgArticleCountMethod.
+ * the criteria defined by $wgArticleCountMethod.
*
- * @param Bool $hasLinks if it is known whether this content contains links, provide this information here,
- * to avoid redundant parsing to find out.
- * @param IContextSource $context context for parsing if necessary
+ * @param Bool $hasLinks if it is known whether this content contains links, provide this information here,
+ * to avoid redundant parsing to find out.
+ * @param null|\Title $title
+ *
+ * @internal param \IContextSource $context context for parsing if necessary
*
* @return bool true if the content is countable
*/
/**
* Returns the message as rendered HTML, using the options supplied to the constructor plus "parse".
+ * @return String the message text, parsed
*/
protected function getHtml( ) {
$opt = array_merge( $this->mOptions, array('parse') );
/**
* Returns the message as raw text, using the options supplied to the constructor minus "parse" and "parseinline".
+ *
+ * @return String the message text, unparsed.
*/
public function getNativeData( ) {
$opt = array_diff( $this->mOptions, array('parse', 'parseinline') );
<?php
+/**
+ * Exception representing a failure to serialize or unserialize a content object.
+ */
class MWContentSerializationException extends MWException {
}
-
/**
* A content handler knows how do deal with a specific type of content on a wiki page.
* Content is stored in the database in a serialized form (using a serialization format aka mime type)
- * and is be unserialized into it's native PHP represenation (the content model), which is wrappe in
+ * and is be unserialized into it's native PHP representation (the content model), which is wrapped in
* an instance of the appropriate subclass of Content.
*
* ContentHandler instances are stateless singletons that serve, among other things, as a factory for
* Content objects. Generally, there is one subclass of ContentHandler and one subclass of Content
* for every type of content model.
*
- * Some content types have a flat model, that is, their native represenation is the
+ * Some content types have a flat model, that is, their native representation is the
* same as their serialized form. Examples would be JavaScript and CSS code. As of now,
* this also applies to wikitext (mediawiki's default content type), but wikitext
* content may be represented by a DOM or AST structure in the future.
abstract class ContentHandler {
/**
- * Conveniance function for getting flat text from a Content object. This should only
+ * Convenience function for getting flat text from a Content object. This should only
* be used in the context of backwards compatibility with code that is not yet able
* to handle Content objects!
*
*
* If $content is an instance of TextContent, this method returns the flat text as returned by $content->getNativeData().
*
- * If $content is not a TextContent object, the bahaviour of this method depends on the global $wgContentHandlerTextFallback:
+ * If $content is not a TextContent object, the behavior of this method depends on the global $wgContentHandlerTextFallback:
* * If $wgContentHandlerTextFallback is 'fail' and $content is not a TextContent object, an MWException is thrown.
* * If $wgContentHandlerTextFallback is 'serialize' and $content is not a TextContent object, $content->serialize()
* is called to get a string form of the content.
}
/**
- * Conveniance function for creating a Content object from a given textual representation.
+ * Convenience function for creating a Content object from a given textual representation.
*
* $text will be deserialized into a Content object of the model specified by $modelId (or,
* if that is not given, $title->getContentModel()) using the given format.
* @since WD.1
*
* @static
- * @param string $text the textual represenation, will be unserialized to create the Content object
+ * @param string $text the textual representation, will be unserialized to create the Content object
* @param Title $title the title of the page this text belongs to, required as a context for deserialization
* @param null|String $modelId the model to deserialize to. If not provided, $title->getContentModel() is used.
* @param null|String $format the format to use for deserialization. If not given, the model's default format is used.
global $wgNamespaceContentModels;
// NOTE: this method must not rely on $title->getContentModel() directly or indirectly,
- // because it is used to initialized the mContentModel memebr.
+ // because it is used to initialized the mContentModel member.
$ns = $title->getNamespace();
* instantiated and the class name is replaced by te resulting singleton in $wgContentHandlers.
*
* If no ContentHandler is defined for the desired $modelId, the ContentHandler may be provided by the
- * a ContentHandlerForModelID hook. if no Contenthandler can be determined, an MWException is raised.
+ * a ContentHandlerForModelID hook. if no ContentHandler can be determined, an MWException is raised.
*
* @since WD.1
*
* or null of no mime type is known.
*
* Model names are localized using system messages. Message keys
- * have the form conent-model-$id.
+ * have the form content-model-$id.
*
* @static
* @param int $id the content model id, as given by a CONTENT_MODEL_XXX constant
* @since WD.1
*
* @param int $model_id the model to check
+ *
+ * @throws MWException
*/
protected function checkModelID( $model_id ) {
if ( $model_id !== $this->mModelID ) {
*
* @since WD.1
*
- * @return String the name of the default serialiozation format as a MIME type
+ * @return String the name of the default serialization format as a MIME type
*/
public function getDefaultFormat() {
return $this->mSupportedFormats[0];
* for checking whether a format provided as a parameter is actually supported.
*
* @param String $format the serialization format to check
+ *
+ * @throws MWException
*/
protected function checkFormat( $format ) {
if ( !$this->isSupportedFormat( $format ) ) {
*
* @since WD.1
*
+ * @param \Content $content
+ *
* @return boolean
*/
public function isConsistentWithDatabase( Content $content ) {
}
/**
- * Factory
+ * Factory creating an appropriate DifferenceEngine for this content model.
+ *
* @since WD.1
*
- * @param $context IContextSource context to use, anything else will be ignored
- * @param $old Integer old ID we want to show and diff with.
- * @param $new String either 'prev' or 'next'.
- * @param $rcid Integer ??? FIXME (default 0)
- * @param $refreshCache boolean If set, refreshes the diff cache
- * @param $unhide boolean If set, allow viewing deleted revs
+ * @param $context IContextSource context to use, anything else will be ignored
+ * @param $old Integer old ID we want to show and diff with.
+ * @param int|String $new String either 'prev' or 'next'.
+ * @param $rcid Integer ??? FIXME (default 0)
+ * @param $refreshCache boolean If set, refreshes the diff cache
+ * @param $unhide boolean If set, allow viewing deleted revs
*
* @return DifferenceEngine
*/
*
* @since WD.1
*
- * @param $oldContent String
- * @param $myContent String
- * @param $yourContent String
+ * @param Content|String $oldContent String
+ * @param Content|String $myContent String
+ * @param Content|String $yourContent String
+ *
* @return Content|Bool
*/
public function merge3( Content $oldContent, Content $myContent, Content $yourContent ) {
}
/**
- * Return an applicable autosummary if one exists for the given edit.
+ * Return an applicable auto-summary if one exists for the given edit.
*
* @since WD.1
*
* @param $oldContent Content|null: the previous text of the page.
* @param $newContent Content|null: The submitted text of the page.
- * @param $flags Int bitmask: a bitmask of flags submitted for the edit.
+ * @param $flags Int bit mask: a bit mask of flags submitted for the edit.
*
- * @return string An appropriate autosummary, or an empty string.
+ * @return string An appropriate auto-summary, or an empty string.
*/
public function getAutosummary( Content $oldContent = null, Content $newContent = null, $flags ) {
global $wgContLang;
- // Decide what kind of autosummary is needed.
+ // Decide what kind of auto-summary is needed.
- // Redirect autosummaries
+ // Redirect auto-summaries
/**
* @var $ot Title
return wfMsgForContent( 'autoredircomment', $rt->getFullText(), $truncatedtext );
}
- // New page autosummaries
+ // New page auto-summaries
if ( $flags & EDIT_NEW && $newContent->getSize() > 0 ) {
// If they're making a new article, give its text, truncated, in the summary.
return wfMsgForContent( 'autosumm-new', $truncatedtext );
}
- // Blanking autosummaries
+ // Blanking auto-summaries
if ( !empty( $oldContent ) && $oldContent->getSize() > 0 && $newContent->getSize() == 0 ) {
return wfMsgForContent( 'autosumm-blank' );
} elseif ( !empty( $oldContent ) && $oldContent->getSize() > 10 * $newContent->getSize() && $newContent->getSize() < 500 ) {
return wfMsgForContent( 'autosumm-replace', $truncatedtext );
}
- // If we reach this point, there's no applicable autosummary for our case, so our
- // autosummary is empty.
+ // If we reach this point, there's no applicable auto-summary for our case, so our
+ // auto-summary is empty.
return '';
}
*
* This text-based implementation uses wfMerge().
*
- * @param $oldContent String
- * @param $myContent String
- * @param $yourContent String
+ * @param \Content|String $oldContent String
+ * @param \Content|String $myContent String
+ * @param \Content|String $yourContent String
+ *
* @return Content|Bool
*/
public function merge3( Content $oldContent, Content $myContent, Content $yourContent ) {
dépôts / lhc / web / wiklou.git / commitdiff