ContentHandler.php

Go to the documentation of this file.

<?php
 
use MediaWiki\Search\ParserOutputSearchDataExtractor;
 
class MWContentSerializationException extends MWException {
}
 
class MWUnknownContentModelException extends MWException {
    private $modelId;
 
    function __construct( $modelId ) {
        parent::__construct( "The content model '$modelId' is not registered on this wiki.\n" .
            'See https://www.mediawiki.org/wiki/Content_handlers to find out which extensions ' .
            'handle this content model.' );
        $this->modelId = $modelId;
    }
 
    public function getModelId() {
        return $this->modelId;
    }
}
 
abstract class ContentHandler {
    public static function getContentText( Content $content = null ) {
        global $wgContentHandlerTextFallback;
 
        if ( is_null( $content ) ) {
            return '';
        }
 
        if ( $content instanceof TextContent ) {
            return $content->getNativeData();
        }
 
        wfDebugLog( 'ContentHandler', 'Accessing ' . $content->getModel() . ' content as text!' );
 
        if ( $wgContentHandlerTextFallback == 'fail' ) {
            throw new MWException(
                "Attempt to get text from Content with model " .
                $content->getModel()
            );
        }
 
        if ( $wgContentHandlerTextFallback == 'serialize' ) {
            return $content->serialize();
        }
 
        return null;
    }
 
    public static function makeContent( $text, Title $title = null,
        $modelId = null, $format = null ) {
        if ( is_null( $modelId ) ) {
            if ( is_null( $title ) ) {
                throw new MWException( "Must provide a Title object or a content model ID." );
            }
 
            $modelId = $title->getContentModel();
        }
 
        $handler = ContentHandler::getForModelID( $modelId );
 
        return $handler->unserializeContent( $text, $format );
    }
 
    public static function getDefaultModelFor( Title $title ) {
        // NOTE: this method must not rely on $title->getContentModel() directly or indirectly,
        //       because it is used to initialize the mContentModel member.
 
        $ns = $title->getNamespace();
 
        $ext = false;
        $m = null;
        $model = MWNamespace::getNamespaceContentModel( $ns );
 
        // Hook can determine default model
        if ( !Hooks::run( 'ContentHandlerDefaultModelFor', [ $title, &$model ] ) ) {
            if ( !is_null( $model ) ) {
                return $model;
            }
        }
 
        // Could this page contain code based on the title?
        $isCodePage = NS_MEDIAWIKI == $ns && preg_match( '!\.(css|js|json)$!u', $title->getText(), $m );
        if ( $isCodePage ) {
            $ext = $m[1];
        }
 
        // Hook can force JS/CSS
        Hooks::run( 'TitleIsCssOrJsPage', [ $title, &$isCodePage ], '1.21' );
 
        // Is this a user subpage containing code?
        $isCodeSubpage = NS_USER == $ns
            && !$isCodePage
            && preg_match( "/\\/.*\\.(js|css|json)$/", $title->getText(), $m );
        if ( $isCodeSubpage ) {
            $ext = $m[1];
        }
 
        // Is this wikitext, according to $wgNamespaceContentModels or the DefaultModelFor hook?
        $isWikitext = is_null( $model ) || $model == CONTENT_MODEL_WIKITEXT;
        $isWikitext = $isWikitext && !$isCodePage && !$isCodeSubpage;
 
        // Hook can override $isWikitext
        Hooks::run( 'TitleIsWikitextPage', [ $title, &$isWikitext ], '1.21' );
 
        if ( !$isWikitext ) {
            switch ( $ext ) {
                case 'js':
                    return CONTENT_MODEL_JAVASCRIPT;
                case 'css':
                    return CONTENT_MODEL_CSS;
                case 'json':
                    return CONTENT_MODEL_JSON;
                default:
                    return is_null( $model ) ? CONTENT_MODEL_TEXT : $model;
            }
        }
 
        // We established that it must be wikitext
 
        return CONTENT_MODEL_WIKITEXT;
    }
 
    public static function getForTitle( Title $title ) {
        $modelId = $title->getContentModel();
 
        return ContentHandler::getForModelID( $modelId );
    }
 
    public static function getForContent( Content $content ) {
        $modelId = $content->getModel();
 
        return ContentHandler::getForModelID( $modelId );
    }
 
    protected static $handlers;
 
    public static function getForModelID( $modelId ) {
        global $wgContentHandlers;
 
        if ( isset( ContentHandler::$handlers[$modelId] ) ) {
            return ContentHandler::$handlers[$modelId];
        }
 
        if ( empty( $wgContentHandlers[$modelId] ) ) {
            $handler = null;
 
            Hooks::run( 'ContentHandlerForModelID', [ $modelId, &$handler ] );
 
            if ( $handler === null ) {
                throw new MWUnknownContentModelException( $modelId );
            }
 
            if ( !( $handler instanceof ContentHandler ) ) {
                throw new MWException( "ContentHandlerForModelID must supply a ContentHandler instance" );
            }
        } else {
            $classOrCallback = $wgContentHandlers[$modelId];
 
            if ( is_callable( $classOrCallback ) ) {
                $handler = call_user_func( $classOrCallback, $modelId );
            } else {
                $handler = new $classOrCallback( $modelId );
            }
 
            if ( !( $handler instanceof ContentHandler ) ) {
                throw new MWException( "$classOrCallback from \$wgContentHandlers is not " .
                    "compatible with ContentHandler" );
            }
        }
 
        wfDebugLog( 'ContentHandler', 'Created handler for ' . $modelId
            . ': ' . get_class( $handler ) );
 
        ContentHandler::$handlers[$modelId] = $handler;
 
        return ContentHandler::$handlers[$modelId];
    }
 
    public static function getLocalizedName( $name, Language $lang = null ) {
        // Messages: content-model-wikitext, content-model-text,
        // content-model-javascript, content-model-css
        $key = "content-model-$name";
 
        $msg = wfMessage( $key );
        if ( $lang ) {
            $msg->inLanguage( $lang );
        }
 
        return $msg->exists() ? $msg->plain() : $name;
    }
 
    public static function getContentModels() {
        global $wgContentHandlers;
 
        return array_keys( $wgContentHandlers );
    }
 
    public static function getAllContentFormats() {
        global $wgContentHandlers;
 
        $formats = [];
 
        foreach ( $wgContentHandlers as $model => $class ) {
            $handler = ContentHandler::getForModelID( $model );
            $formats = array_merge( $formats, $handler->getSupportedFormats() );
        }
 
        $formats = array_unique( $formats );
 
        return $formats;
    }
 
    // ------------------------------------------------------------------------
 
    protected $mModelID;
 
    protected $mSupportedFormats;
 
    public function __construct( $modelId, $formats ) {
        $this->mModelID = $modelId;
        $this->mSupportedFormats = $formats;
    }
 
    abstract public function serializeContent( Content $content, $format = null );
 
    public function exportTransform( $blob, $format = null ) {
        return $blob;
    }
 
    abstract public function unserializeContent( $blob, $format = null );
 
    public function importTransform( $blob, $format = null ) {
        return $blob;
    }
 
    abstract public function makeEmptyContent();
 
    public function makeRedirectContent( Title $destination, $text = '' ) {
        return null;
    }
 
    public function getModelID() {
        return $this->mModelID;
    }
 
    protected function checkModelID( $model_id ) {
        if ( $model_id !== $this->mModelID ) {
            throw new MWException( "Bad content model: " .
                "expected {$this->mModelID} " .
                "but got $model_id." );
        }
    }
 
    public function getSupportedFormats() {
        return $this->mSupportedFormats;
    }
 
    public function getDefaultFormat() {
        return $this->mSupportedFormats[0];
    }
 
    public function isSupportedFormat( $format ) {
        if ( !$format ) {
            return true; // this means "use the default"
        }
 
        return in_array( $format, $this->mSupportedFormats );
    }
 
    protected function checkFormat( $format ) {
        if ( !$this->isSupportedFormat( $format ) ) {
            throw new MWException(
                "Format $format is not supported for content model "
                . $this->getModelID()
            );
        }
    }
 
    public function getActionOverrides() {
        return [];
    }
 
    public function createDifferenceEngine( IContextSource $context, $old = 0, $new = 0,
        $rcid = 0, // FIXME: Deprecated, no longer used
        $refreshCache = false, $unhide = false ) {
 
        // hook: get difference engine
        $differenceEngine = null;
        if ( !Hooks::run( 'GetDifferenceEngine',
            [ $context, $old, $new, $refreshCache, $unhide, &$differenceEngine ]
        ) ) {
            return $differenceEngine;
        }
        $diffEngineClass = $this->getDiffEngineClass();
        return new $diffEngineClass( $context, $old, $new, $rcid, $refreshCache, $unhide );
    }
 
    public function getPageLanguage( Title $title, Content $content = null ) {
        global $wgContLang, $wgLang;
        $pageLang = $wgContLang;
 
        if ( $title->getNamespace() == NS_MEDIAWIKI ) {
            // Parse mediawiki messages with correct target language
            list( /* $unused */, $lang ) = MessageCache::singleton()->figureMessage( $title->getText() );
            $pageLang = Language::factory( $lang );
        }
 
        Hooks::run( 'PageContentLanguage', [ $title, &$pageLang, $wgLang ] );
 
        return wfGetLangObj( $pageLang );
    }
 
    public function getPageViewLanguage( Title $title, Content $content = null ) {
        $pageLang = $this->getPageLanguage( $title, $content );
 
        if ( $title->getNamespace() !== NS_MEDIAWIKI ) {
            // If the user chooses a variant, the content is actually
            // in a language whose code is the variant code.
            $variant = $pageLang->getPreferredVariant();
            if ( $pageLang->getCode() !== $variant ) {
                $pageLang = Language::factory( $variant );
            }
        }
 
        return $pageLang;
    }
 
    public function canBeUsedOn( Title $title ) {
        $ok = true;
 
        Hooks::run( 'ContentModelCanBeUsedOn', [ $this->getModelID(), $title, &$ok ] );
 
        return $ok;
    }
 
    protected function getDiffEngineClass() {
        return DifferenceEngine::class;
    }
 
    public function merge3( Content $oldContent, Content $myContent, Content $yourContent ) {
        return false;
    }
 
    public function getAutosummary( Content $oldContent = null, Content $newContent = null,
        $flags ) {
        // Decide what kind of auto-summary is needed.
 
        // Redirect auto-summaries
 
        $ot = !is_null( $oldContent ) ? $oldContent->getRedirectTarget() : null;
        $rt = !is_null( $newContent ) ? $newContent->getRedirectTarget() : null;
 
        if ( is_object( $rt ) ) {
            if ( !is_object( $ot )
                || !$rt->equals( $ot )
                || $ot->getFragment() != $rt->getFragment()
            ) {
                $truncatedtext = $newContent->getTextForSummary(
                    250
                    - strlen( wfMessage( 'autoredircomment' )->inContentLanguage()->text() )
                    - strlen( $rt->getFullText() ) );
 
                return wfMessage( 'autoredircomment', $rt->getFullText() )
                    ->rawParams( $truncatedtext )->inContentLanguage()->text();
            }
        }
 
        // 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.
 
            $truncatedtext = $newContent->getTextForSummary(
                200 - strlen( wfMessage( 'autosumm-new' )->inContentLanguage()->text() ) );
 
            return wfMessage( 'autosumm-new' )->rawParams( $truncatedtext )
                ->inContentLanguage()->text();
        }
 
        // Blanking auto-summaries
        if ( !empty( $oldContent ) && $oldContent->getSize() > 0 && $newContent->getSize() == 0 ) {
            return wfMessage( 'autosumm-blank' )->inContentLanguage()->text();
        } elseif ( !empty( $oldContent )
            && $oldContent->getSize() > 10 * $newContent->getSize()
            && $newContent->getSize() < 500
        ) {
            // Removing more than 90% of the article
 
            $truncatedtext = $newContent->getTextForSummary(
                200 - strlen( wfMessage( 'autosumm-replace' )->inContentLanguage()->text() ) );
 
            return wfMessage( 'autosumm-replace' )->rawParams( $truncatedtext )
                ->inContentLanguage()->text();
        }
 
        // New blank article auto-summary
        if ( $flags & EDIT_NEW && $newContent->isEmpty() ) {
            return wfMessage( 'autosumm-newblank' )->inContentLanguage()->text();
        }
 
        // If we reach this point, there's no applicable auto-summary for our
        // case, so our auto-summary is empty.
        return '';
    }
 
    public function getAutoDeleteReason( Title $title, &$hasHistory ) {
        $dbr = wfGetDB( DB_REPLICA );
 
        // Get the last revision
        $rev = Revision::newFromTitle( $title );
 
        if ( is_null( $rev ) ) {
            return false;
        }
 
        // Get the article's contents
        $content = $rev->getContent();
        $blank = false;
 
        // If the page is blank, use the text from the previous revision,
        // which can only be blank if there's a move/import/protect dummy
        // revision involved
        if ( !$content || $content->isEmpty() ) {
            $prev = $rev->getPrevious();
 
            if ( $prev ) {
                $rev = $prev;
                $content = $rev->getContent();
                $blank = true;
            }
        }
 
        $this->checkModelID( $rev->getContentModel() );
 
        // Find out if there was only one contributor
        // Only scan the last 20 revisions
        $res = $dbr->select( 'revision', 'rev_user_text',
            [
                'rev_page' => $title->getArticleID(),
                $dbr->bitAnd( 'rev_deleted', Revision::DELETED_USER ) . ' = 0'
            ],
            __METHOD__,
            [ 'LIMIT' => 20 ]
        );
 
        if ( $res === false ) {
            // This page has no revisions, which is very weird
            return false;
        }
 
        $hasHistory = ( $res->numRows() > 1 );
        $row = $dbr->fetchObject( $res );
 
        if ( $row ) { // $row is false if the only contributor is hidden
            $onlyAuthor = $row->rev_user_text;
            // Try to find a second contributor
            foreach ( $res as $row ) {
                if ( $row->rev_user_text != $onlyAuthor ) { // Bug 22999
                    $onlyAuthor = false;
                    break;
                }
            }
        } else {
            $onlyAuthor = false;
        }
 
        // Generate the summary with a '$1' placeholder
        if ( $blank ) {
            // The current revision is blank and the one before is also
            // blank. It's just not our lucky day
            $reason = wfMessage( 'exbeforeblank', '$1' )->inContentLanguage()->text();
        } else {
            if ( $onlyAuthor ) {
                $reason = wfMessage(
                    'excontentauthor',
                    '$1',
                    $onlyAuthor
                )->inContentLanguage()->text();
            } else {
                $reason = wfMessage( 'excontent', '$1' )->inContentLanguage()->text();
            }
        }
 
        if ( $reason == '-' ) {
            // Allow these UI messages to be blanked out cleanly
            return '';
        }
 
        // Max content length = max comment length - length of the comment (excl. $1)
        $text = $content ? $content->getTextForSummary( 255 - ( strlen( $reason ) - 2 ) ) : '';
 
        // Now replace the '$1' placeholder
        $reason = str_replace( '$1', $text, $reason );
 
        return $reason;
    }
 
    public function getUndoContent( Revision $current, Revision $undo, Revision $undoafter ) {
        $cur_content = $current->getContent();
 
        if ( empty( $cur_content ) ) {
            return false; // no page
        }
 
        $undo_content = $undo->getContent();
        $undoafter_content = $undoafter->getContent();
 
        if ( !$undo_content || !$undoafter_content ) {
            return false; // no content to undo
        }
 
        try {
            $this->checkModelID( $cur_content->getModel() );
            $this->checkModelID( $undo_content->getModel() );
            if ( $current->getId() !== $undo->getId() ) {
                // If we are undoing the most recent revision,
                // its ok to revert content model changes. However
                // if we are undoing a revision in the middle, then
                // doing that will be confusing.
                $this->checkModelID( $undoafter_content->getModel() );
            }
        } catch ( MWException $e ) {
            // If the revisions have different content models
            // just return false
            return false;
        }
 
        if ( $cur_content->equals( $undo_content ) ) {
            // No use doing a merge if it's just a straight revert.
            return $undoafter_content;
        }
 
        $undone_content = $this->merge3( $undo_content, $undoafter_content, $cur_content );
 
        return $undone_content;
    }
 
    public function makeParserOptions( $context ) {
        global $wgContLang, $wgEnableParserLimitReporting;
 
        if ( $context instanceof IContextSource ) {
            $options = ParserOptions::newFromContext( $context );
        } elseif ( $context instanceof User ) { // settings per user (even anons)
            $options = ParserOptions::newFromUser( $context );
        } elseif ( $context === 'canonical' ) { // canonical settings
            $options = ParserOptions::newFromUserAndLang( new User, $wgContLang );
        } else {
            throw new MWException( "Bad context for parser options: $context" );
        }
 
        $options->enableLimitReport( $wgEnableParserLimitReporting ); // show inclusion/loop reports
        $options->setTidy( true ); // fix bad HTML
 
        return $options;
    }
 
    public function isParserCacheSupported() {
        return false;
    }
 
    public function supportsSections() {
        return false;
    }
 
    public function supportsCategories() {
        return true;
    }
 
    public function supportsRedirects() {
        return false;
    }
 
    public function supportsDirectEditing() {
        return false;
    }
 
    public function supportsDirectApiEditing() {
        return $this->supportsDirectEditing();
    }
 
    public static function runLegacyHooks( $event, $args = [],
        $deprecatedVersion = null
    ) {
 
        if ( !Hooks::isRegistered( $event ) ) {
            return true; // nothing to do here
        }
 
        // convert Content objects to text
        $contentObjects = [];
        $contentTexts = [];
 
        foreach ( $args as $k => $v ) {
            if ( $v instanceof Content ) {
                /* @var Content $v */
 
                $contentObjects[$k] = $v;
 
                $v = $v->serialize();
                $contentTexts[$k] = $v;
                $args[$k] = $v;
            }
        }
 
        // call the hook functions
        $ok = Hooks::run( $event, $args, $deprecatedVersion );
 
        // see if the hook changed the text
        foreach ( $contentTexts as $k => $orig ) {
            /* @var Content $content */
 
            $modified = $args[$k];
            $content = $contentObjects[$k];
 
            if ( $modified !== $orig ) {
                // text was changed, create updated Content object
                $content = $content->getContentHandler()->unserializeContent( $modified );
            }
 
            $args[$k] = $content;
        }
 
        return $ok;
    }
 
    public function getFieldsForSearchIndex( SearchEngine $engine ) {
        $fields['category'] = $engine->makeSearchFieldMapping(
            'category',
            SearchIndexField::INDEX_TYPE_TEXT
        );
 
        $fields['category']->setFlag( SearchIndexField::FLAG_CASEFOLD );
 
        $fields['external_link'] = $engine->makeSearchFieldMapping(
            'external_link',
            SearchIndexField::INDEX_TYPE_KEYWORD
        );
 
        $fields['outgoing_link'] = $engine->makeSearchFieldMapping(
            'outgoing_link',
            SearchIndexField::INDEX_TYPE_KEYWORD
        );
 
        $fields['template'] = $engine->makeSearchFieldMapping(
            'template',
            SearchIndexField::INDEX_TYPE_KEYWORD
        );
 
        $fields['template']->setFlag( SearchIndexField::FLAG_CASEFOLD );
 
        return $fields;
    }
 
    protected function addSearchField( &$fields, SearchEngine $engine, $name, $type ) {
        $fields[$name] = $engine->makeSearchFieldMapping( $name, $type );
        return $fields;
    }
 
    public function getDataForSearchIndex( WikiPage $page, ParserOutput $output,
                                           SearchEngine $engine ) {
        $fieldData = [];
        $content = $page->getContent();
 
        if ( $content ) {
            $searchDataExtractor = new ParserOutputSearchDataExtractor();
 
            $fieldData['category'] = $searchDataExtractor->getCategories( $output );
            $fieldData['external_link'] = $searchDataExtractor->getExternalLinks( $output );
            $fieldData['outgoing_link'] = $searchDataExtractor->getOutgoingLinks( $output );
            $fieldData['template'] = $searchDataExtractor->getTemplates( $output );
 
            $text = $content->getTextForSearchIndex();
 
            $fieldData['text'] = $text;
            $fieldData['source_text'] = $text;
            $fieldData['text_bytes'] = $content->getSize();
        }
 
        Hooks::run( 'SearchDataForIndex', [ &$fieldData, $this, $page, $output, $engine ] );
        return $fieldData;
    }
 
    public function getParserOutputForIndexing( WikiPage $page, ParserCache $cache = null ) {
        $parserOptions = $page->makeParserOptions( 'canonical' );
        $revId = $page->getRevision()->getId();
        if ( $cache ) {
            $parserOutput = $cache->get( $page, $parserOptions );
        }
        if ( empty( $parserOutput ) ) {
            $parserOutput =
                $page->getContent()->getParserOutput( $page->getTitle(), $revId, $parserOptions );
            if ( $cache ) {
                $cache->save( $parserOutput, $page, $parserOptions );
            }
        }
        return $parserOutput;
    }
 
}