ContentHandler.php

Go to the documentation of this file.

<?php
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 {
    protected static $enableDeprecationWarnings = false;

    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.25' );

        // 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.25' );

        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;

        $this->mModelName = preg_replace( '/(Content)?Handler$/', '', get_class( $this ) );
        $this->mModelName = preg_replace( '/[_\\\\]/', '', $this->mModelName );
        $this->mModelName = strtolower( $this->mModelName );
    }

    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 = wfGetLangObj( $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_SLAVE );

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

        $this->checkModelID( $cur_content->getModel() );
        $this->checkModelID( $undo_content->getModel() );
        $this->checkModelID( $undoafter_content->getModel() );

        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 deprecated( $func, $version, $component = false ) {
        if ( self::$enableDeprecationWarnings ) {
            wfDeprecated( $func, $version, $component, 3 );
        }
    }

    public static function runLegacyHooks( $event, $args = [],
        $warn = null
    ) {

        if ( $warn === null ) {
            $warn = self::$enableDeprecationWarnings;
        }

        if ( !Hooks::isRegistered( $event ) ) {
            return true; // nothing to do here
        }

        if ( $warn ) {
            // Log information about which handlers are registered for the legacy hook,
            // so we can find and fix them.

            $handlers = Hooks::getHandlers( $event );
            $handlerInfo = [];

            MediaWiki\suppressWarnings();

            foreach ( $handlers as $handler ) {
                if ( is_array( $handler ) ) {
                    if ( is_object( $handler[0] ) ) {
                        $info = get_class( $handler[0] );
                    } else {
                        $info = $handler[0];
                    }

                    if ( isset( $handler[1] ) ) {
                        $info .= '::' . $handler[1];
                    }
                } elseif ( is_object( $handler ) ) {
                    $info = get_class( $handler[0] );
                    $info .= '::on' . $event;
                } else {
                    $info = $handler;
                }

                $handlerInfo[] = $info;
            }

            MediaWiki\restoreWarnings();

            wfWarn( "Using obsolete hook $event via ContentHandler::runLegacyHooks()! Handlers: " .
                implode( ', ', $handlerInfo ), 2 );
        }

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

        // 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 ) {
        /* Default fields:
        /*
         * namespace
         * namespace_text
         * redirect
         * source_text
         * suggest
         * timestamp
         * title
         * text
         * text_bytes
         */
        return [];
    }
}