ContentHandler.php

Go to the documentation of this file.

<?php

use Wikimedia\Assert\Assert;
use MediaWiki\Logger\LoggerFactory;
use MediaWiki\MediaWikiServices;
use MediaWiki\Revision\SlotRenderingProvider;
use MediaWiki\Search\ParserOutputSearchDataExtractor;

abstract class ContentHandler {
    public static function getContentText( Content $content = null ) {
        global $wgContentHandlerTextFallback;

        if ( is_null( $content ) ) {
            return '';
        }

        if ( $content instanceof TextContent ) {
            return $content->getText();
        }

        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 = self::getForModelID( $modelId );

        return $handler->unserializeContent( $text, $format );
    }

    public static function getDefaultModelFor( Title $title ) {
        $slotRoleregistry = MediaWikiServices::getInstance()->getSlotRoleRegistry();
        $mainSlotHandler = $slotRoleregistry->getRoleHandler( 'main' );
        return $mainSlotHandler->getDefaultModel( $title );
    }

    public static function getForTitle( Title $title ) {
        $modelId = $title->getContentModel();

        return self::getForModelID( $modelId );
    }

    public static function getForContent( Content $content ) {
        $modelId = $content->getModel();

        return self::getForModelID( $modelId );
    }

    protected static $handlers;

    public static function getForModelID( $modelId ) {
        global $wgContentHandlers;

        if ( isset( self::$handlers[$modelId] ) ) {
            return self::$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 ) );

        self::$handlers[$modelId] = $handler;

        return self::$handlers[$modelId];
    }

    public static function cleanupHandlersCache() {
        self::$handlers = [];
    }

    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;

        $models = array_keys( $wgContentHandlers );
        Hooks::run( 'GetContentModels', [ &$models ] );
        return $models;
    }

    public static function getAllContentFormats() {
        global $wgContentHandlers;

        $formats = [];

        foreach ( $wgContentHandlers as $model => $class ) {
            $handler = self::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
    ) {
        $diffEngineClass = $this->getDiffEngineClass();
        $differenceEngine = new $diffEngineClass( $context, $old, $new, $rcid, $refreshCache, $unhide );
        Hooks::run( 'GetDifferenceEngine', [ $context, $old, $new, $refreshCache, $unhide,
            &$differenceEngine ] );
        return $differenceEngine;
    }

    final public function getSlotDiffRenderer( IContextSource $context ) {
        $slotDiffRenderer = $this->getSlotDiffRendererInternal( $context );
        if ( get_class( $slotDiffRenderer ) === TextSlotDiffRenderer::class ) {
            //  To keep B/C, when SlotDiffRenderer is not overridden for a given content type
            // but DifferenceEngine is, use that instead.
            $differenceEngine = $this->createDifferenceEngine( $context );
            if ( get_class( $differenceEngine ) !== DifferenceEngine::class ) {
                // TODO turn this into a deprecation warning in a later release
                LoggerFactory::getInstance( 'diff' )->info(
                    'Falling back to DifferenceEngineSlotDiffRenderer', [
                        'modelID' => $this->getModelID(),
                        'DifferenceEngine' => get_class( $differenceEngine ),
                    ] );
                $slotDiffRenderer = new DifferenceEngineSlotDiffRenderer( $differenceEngine );
            }
        }
        Hooks::run( 'GetSlotDiffRenderer', [ $this, &$slotDiffRenderer, $context ] );
        return $slotDiffRenderer;
    }

    protected function getSlotDiffRendererInternal( IContextSource $context ) {
        $contentLanguage = MediaWikiServices::getInstance()->getContentLanguage();
        $statsdDataFactory = MediaWikiServices::getInstance()->getStatsdDataFactory();
        $slotDiffRenderer = new TextSlotDiffRenderer();
        $slotDiffRenderer->setStatsdDataFactory( $statsdDataFactory );
        // XXX using the page language would be better, but it's unclear how that should be injected
        $slotDiffRenderer->setLanguage( $contentLanguage );

        $engine = DifferenceEngine::getEngine();
        if ( $engine === false ) {
            $slotDiffRenderer->setEngine( TextSlotDiffRenderer::ENGINE_PHP );
        } elseif ( $engine === 'wikidiff2' ) {
            $slotDiffRenderer->setEngine( TextSlotDiffRenderer::ENGINE_WIKIDIFF2 );
        } else {
            $slotDiffRenderer->setEngine( TextSlotDiffRenderer::ENGINE_EXTERNAL, $engine );
        }

        return $slotDiffRenderer;
    }

    public function getPageLanguage( Title $title, Content $content = null ) {
        global $wgLang;
        $pageLang = MediaWikiServices::getInstance()->getContentLanguage();

        if ( $title->inNamespace( NS_MEDIAWIKI ) ) {
            // Parse mediawiki messages with correct target language
            list( /* $unused */, $lang ) = MessageCache::singleton()->figureMessage( $title->getText() );
            $pageLang = Language::factory( $lang );
        }

        // Simplify hook handlers by only passing objects of one type, in case nothing
        // else has unstubbed the StubUserLang object by now.
        StubObject::unstub( $wgLang );

        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;
    }

    private function getChangeType(
        Content $oldContent = null,
        Content $newContent = null,
        $flags = 0
    ) {
        $oldTarget = $oldContent !== null ? $oldContent->getRedirectTarget() : null;
        $newTarget = $newContent !== null ? $newContent->getRedirectTarget() : null;

        // We check for the type of change in the given edit, and return string key accordingly

        // Blanking of a page
        if ( $oldContent && $oldContent->getSize() > 0 &&
            $newContent && $newContent->getSize() === 0
        ) {
            return 'blank';
        }

        // Redirects
        if ( $newTarget ) {
            if ( !$oldTarget ) {
                // New redirect page (by creating new page or by changing content page)
                return 'new-redirect';
            } elseif ( !$newTarget->equals( $oldTarget ) ||
                $oldTarget->getFragment() !== $newTarget->getFragment()
            ) {
                // Redirect target changed
                return 'changed-redirect-target';
            }
        } elseif ( $oldTarget ) {
            // Changing an existing redirect into a non-redirect
            return 'removed-redirect';
        }

        // New page created
        if ( $flags & EDIT_NEW && $newContent ) {
            if ( $newContent->getSize() === 0 ) {
                // New blank page
                return 'newblank';
            } else {
                return 'newpage';
            }
        }

        // Removing more than 90% of the page
        if ( $oldContent && $newContent && $oldContent->getSize() > 10 * $newContent->getSize() ) {
            return 'replace';
        }

        // Content model changed
        if ( $oldContent && $newContent && $oldContent->getModel() !== $newContent->getModel() ) {
            return 'contentmodelchange';
        }

        return null;
    }

    public function getAutosummary(
        Content $oldContent = null,
        Content $newContent = null,
        $flags = 0
    ) {
        $changeType = $this->getChangeType( $oldContent, $newContent, $flags );

        // There's no applicable auto-summary for our case, so our auto-summary is empty.
        if ( !$changeType ) {
            return '';
        }

        // Decide what kind of auto-summary is needed.
        switch ( $changeType ) {
            case 'new-redirect':
                $newTarget = $newContent->getRedirectTarget();
                $truncatedtext = $newContent->getTextForSummary(
                    250
                    - strlen( wfMessage( 'autoredircomment' )->inContentLanguage()->text() )
                    - strlen( $newTarget->getFullText() )
                );

                return wfMessage( 'autoredircomment', $newTarget->getFullText() )
                    ->plaintextParams( $truncatedtext )->inContentLanguage()->text();
            case 'changed-redirect-target':
                $oldTarget = $oldContent->getRedirectTarget();
                $newTarget = $newContent->getRedirectTarget();

                $truncatedtext = $newContent->getTextForSummary(
                    250
                    - strlen( wfMessage( 'autosumm-changed-redirect-target' )
                        ->inContentLanguage()->text() )
                    - strlen( $oldTarget->getFullText() )
                    - strlen( $newTarget->getFullText() )
                );

                return wfMessage( 'autosumm-changed-redirect-target',
                        $oldTarget->getFullText(),
                        $newTarget->getFullText() )
                    ->rawParams( $truncatedtext )->inContentLanguage()->text();
            case 'removed-redirect':
                $oldTarget = $oldContent->getRedirectTarget();
                $truncatedtext = $newContent->getTextForSummary(
                    250
                    - strlen( wfMessage( 'autosumm-removed-redirect' )
                        ->inContentLanguage()->text() )
                    - strlen( $oldTarget->getFullText() ) );

                return wfMessage( 'autosumm-removed-redirect', $oldTarget->getFullText() )
                    ->rawParams( $truncatedtext )->inContentLanguage()->text();
            case 'newpage':
                // 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();
            case 'blank':
                return wfMessage( 'autosumm-blank' )->inContentLanguage()->text();
            case 'replace':
                $truncatedtext = $newContent->getTextForSummary(
                    200 - strlen( wfMessage( 'autosumm-replace' )->inContentLanguage()->text() ) );

                return wfMessage( 'autosumm-replace' )->rawParams( $truncatedtext )
                    ->inContentLanguage()->text();
            case 'newblank':
                return wfMessage( 'autosumm-newblank' )->inContentLanguage()->text();
            default:
                return '';
        }
    }

    public function getChangeTag(
        Content $oldContent = null,
        Content $newContent = null,
        $flags = 0
    ) {
        $changeType = $this->getChangeType( $oldContent, $newContent, $flags );

        // There's no applicable tag for this change.
        if ( !$changeType ) {
            return null;
        }

        // Core tags use the same keys as ones returned from $this->getChangeType()
        // but prefixed with pseudo namespace 'mw-', so we add the prefix before checking
        // if this type of change should be tagged
        $tag = 'mw-' . $changeType;

        // Not all change types are tagged, so we check against the list of defined tags.
        if ( in_array( $tag, ChangeTags::getSoftwareTags() ) ) {
            return $tag;
        }

        return null;
    }

    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
        $revQuery = Revision::getQueryInfo();
        $res = $dbr->select(
            $revQuery['tables'],
            [ 'rev_user_text' => $revQuery['fields']['rev_user_text'] ],
            [
                'rev_page' => $title->getArticleID(),
                $dbr->bitAnd( 'rev_deleted', Revision::DELETED_USER ) . ' = 0'
            ],
            __METHOD__,
            [ 'LIMIT' => 20 ],
            $revQuery['joins']
        );

        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 ) { // T24999
                    $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( $current, $undo, $undoafter, $undoIsLatest = false ) {
        Assert::parameterType( Revision::class . '|' . Content::class, $current, '$current' );
        if ( $current instanceof Content ) {
            Assert::parameter( $undo instanceof Content, '$undo',
                'Must be Content when $current is Content' );
            Assert::parameter( $undoafter instanceof Content, '$undoafter',
                'Must be Content when $current is Content' );
            $cur_content = $current;
            $undo_content = $undo;
            $undoafter_content = $undoafter;
        } else {
            Assert::parameter( $undo instanceof Revision, '$undo',
                'Must be Revision when $current is Revision' );
            Assert::parameter( $undoafter instanceof Revision, '$undoafter',
                'Must be Revision when $current is Revision' );

            $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
            }

            $undoIsLatest = $current->getId() === $undo->getId();
        }

        try {
            $this->checkModelID( $cur_content->getModel() );
            $this->checkModelID( $undo_content->getModel() );
            if ( !$undoIsLatest ) {
                // 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 ) {
        wfDeprecated( __METHOD__, '1.32' );
        return ParserOptions::newCanonical( $context );
    }

    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 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 );

        $fields['content_model'] = $engine->makeSearchFieldMapping(
            'content_model',
            SearchIndexField::INDEX_TYPE_KEYWORD
        );

        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();
            $fieldData['content_model'] = $content->getModel();
        }

        Hooks::run( 'SearchDataForIndex', [ &$fieldData, $this, $page, $output, $engine ] );
        return $fieldData;
    }

    public function getParserOutputForIndexing( WikiPage $page, ParserCache $cache = null ) {
        // TODO: MCR: ContentHandler should be called per slot, not for the whole page.
        // See T190066.
        $parserOptions = $page->makeParserOptions( 'canonical' );
        if ( $cache ) {
            $parserOutput = $cache->get( $page, $parserOptions );
        }

        if ( empty( $parserOutput ) ) {
            $renderer = MediaWikiServices::getInstance()->getRevisionRenderer();
            $parserOutput =
                $renderer->getRenderedRevision(
                    $page->getRevision()->getRevisionRecord(),
                    $parserOptions
                )->getRevisionParserOutput();
            if ( $cache ) {
                $cache->save( $parserOutput, $page, $parserOptions );
            }
        }
        return $parserOutput;
    }

    public function getSecondaryDataUpdates(
        Title $title,
        Content $content,
        $role,
        SlotRenderingProvider $slotOutput
    ) {
        return [];
    }

    public function getDeletionUpdates( Title $title, $role ) {
        return [];
    }

}