ResourceLoaderModule.php

Go to the documentation of this file.

<?php
use Psr\Log\LoggerAwareInterface;
use Psr\Log\LoggerInterface;
use Psr\Log\NullLogger;
use Wikimedia\ScopedCallback;

abstract class ResourceLoaderModule implements LoggerAwareInterface {
    # Type of resource
    const TYPE_SCRIPTS = 'scripts';
    const TYPE_STYLES = 'styles';
    const TYPE_COMBINED = 'combined';

    # Desired load type
    // Module only has styles (loaded via <style> or <link rel=stylesheet>)
    const LOAD_STYLES = 'styles';
    // Module may have other resources (loaded via mw.loader from a script)
    const LOAD_GENERAL = 'general';

    # sitewide core module like a skin file or jQuery component
    const ORIGIN_CORE_SITEWIDE = 1;

    # per-user module generated by the software
    const ORIGIN_CORE_INDIVIDUAL = 2;

    # sitewide module generated from user-editable files, like MediaWiki:Common.js, or
    # modules accessible to multiple users, such as those generated by the Gadgets extension.
    const ORIGIN_USER_SITEWIDE = 3;

    # per-user module generated from user-editable files, like User:Me/vector.js
    const ORIGIN_USER_INDIVIDUAL = 4;

    # an access constant; make sure this is kept as the largest number in this group
    const ORIGIN_ALL = 10;

    # script and style modules form a hierarchy of trustworthiness, with core modules like
    # skins and jQuery as most trustworthy, and user scripts as least trustworthy.  We can
    # limit the types of scripts and styles we allow to load on, say, sensitive special
    # pages like Special:UserLogin and Special:Preferences
    protected $origin = self::ORIGIN_CORE_SITEWIDE;

    /* Protected Members */

    protected $name = null;
    protected $targets = [ 'desktop' ];

    // In-object cache for file dependencies
    protected $fileDeps = [];
    // In-object cache for message blob (keyed by language)
    protected $msgBlobs = [];
    // In-object cache for version hash
    protected $versionHash = [];
    // In-object cache for module content
    protected $contents = [];

    protected $config;

    protected $deprecated = false;

    protected $logger;

    /* Methods */

    public function getName() {
        return $this->name;
    }

    public function setName( $name ) {
        $this->name = $name;
    }

    public function getOrigin() {
        return $this->origin;
    }

    public function getFlip( $context ) {
        global $wgContLang;

        return $wgContLang->getDir() !== $context->getDirection();
    }

    protected function getDeprecationInformation() {
        $deprecationInfo = $this->deprecated;
        if ( $deprecationInfo ) {
            $name = $this->getName();
            $warning = 'This page is using the deprecated ResourceLoader module "' . $name . '".';
            if ( !is_bool( $deprecationInfo ) && isset( $deprecationInfo['message'] ) ) {
                $warning .= "\n" . $deprecationInfo['message'];
            }
            return Xml::encodeJsCall(
                'mw.log.warn',
                [ $warning ]
            );
        } else {
            return '';
        }
    }

    public function getScript( ResourceLoaderContext $context ) {
        // Stub, override expected
        return '';
    }

    public function getTemplates() {
        // Stub, override expected.
        return [];
    }

    public function getConfig() {
        if ( $this->config === null ) {
            // Ugh, fall back to default
            $this->config = ConfigFactory::getDefaultInstance()->makeConfig( 'main' );
        }

        return $this->config;
    }

    public function setConfig( Config $config ) {
        $this->config = $config;
    }

    public function setLogger( LoggerInterface $logger ) {
        $this->logger = $logger;
    }

    protected function getLogger() {
        if ( !$this->logger ) {
            $this->logger = new NullLogger();
        }
        return $this->logger;
    }

    public function getScriptURLsForDebug( ResourceLoaderContext $context ) {
        $resourceLoader = $context->getResourceLoader();
        $derivative = new DerivativeResourceLoaderContext( $context );
        $derivative->setModules( [ $this->getName() ] );
        $derivative->setOnly( 'scripts' );
        $derivative->setDebug( true );

        $url = $resourceLoader->createLoaderURL(
            $this->getSource(),
            $derivative
        );

        return [ $url ];
    }

    public function supportsURLLoading() {
        return true;
    }

    public function getStyles( ResourceLoaderContext $context ) {
        // Stub, override expected
        return [];
    }

    public function getStyleURLsForDebug( ResourceLoaderContext $context ) {
        $resourceLoader = $context->getResourceLoader();
        $derivative = new DerivativeResourceLoaderContext( $context );
        $derivative->setModules( [ $this->getName() ] );
        $derivative->setOnly( 'styles' );
        $derivative->setDebug( true );

        $url = $resourceLoader->createLoaderURL(
            $this->getSource(),
            $derivative
        );

        return [ 'all' => [ $url ] ];
    }

    public function getMessages() {
        // Stub, override expected
        return [];
    }

    public function getGroup() {
        // Stub, override expected
        return null;
    }

    public function getSource() {
        // Stub, override expected
        return 'local';
    }

    public function getPosition() {
        return 'bottom';
    }

    public function isRaw() {
        return false;
    }

    public function getDependencies( ResourceLoaderContext $context = null ) {
        // Stub, override expected
        return [];
    }

    public function getTargets() {
        return $this->targets;
    }

    public function getType() {
        return self::LOAD_GENERAL;
    }

    public function getSkipFunction() {
        return null;
    }

    protected function getFileDependencies( ResourceLoaderContext $context ) {
        $vary = $context->getSkin() . '|' . $context->getLanguage();

        // Try in-object cache first
        if ( !isset( $this->fileDeps[$vary] ) ) {
            $dbr = wfGetDB( DB_REPLICA );
            $deps = $dbr->selectField( 'module_deps',
                'md_deps',
                [
                    'md_module' => $this->getName(),
                    'md_skin' => $vary,
                ],
                __METHOD__
            );

            if ( !is_null( $deps ) ) {
                $this->fileDeps[$vary] = self::expandRelativePaths(
                    (array)FormatJson::decode( $deps, true )
                );
            } else {
                $this->fileDeps[$vary] = [];
            }
        }
        return $this->fileDeps[$vary];
    }

    public function setFileDependencies( ResourceLoaderContext $context, $files ) {
        $vary = $context->getSkin() . '|' . $context->getLanguage();
        $this->fileDeps[$vary] = $files;
    }

    protected function saveFileDependencies( ResourceLoaderContext $context, $localFileRefs ) {
        // Normalise array
        $localFileRefs = array_values( array_unique( $localFileRefs ) );
        sort( $localFileRefs );

        try {
            // If the list has been modified since last time we cached it, update the cache
            if ( $localFileRefs !== $this->getFileDependencies( $context ) ) {
                $cache = ObjectCache::getLocalClusterInstance();
                $key = $cache->makeKey( __METHOD__, $this->getName() );
                $scopeLock = $cache->getScopedLock( $key, 0 );
                if ( !$scopeLock ) {
                    return; // T124649; avoid write slams
                }

                $vary = $context->getSkin() . '|' . $context->getLanguage();
                $dbw = wfGetDB( DB_MASTER );
                $dbw->replace( 'module_deps',
                    [ [ 'md_module', 'md_skin' ] ],
                    [
                        'md_module' => $this->getName(),
                        'md_skin' => $vary,
                        // Use relative paths to avoid ghost entries when $IP changes (T111481)
                        'md_deps' => FormatJson::encode( self::getRelativePaths( $localFileRefs ) ),
                    ]
                );

                if ( $dbw->trxLevel() ) {
                    $dbw->onTransactionResolution(
                        function () use ( &$scopeLock ) {
                            ScopedCallback::consume( $scopeLock ); // release after commit
                        },
                        __METHOD__
                    );
                }
            }
        } catch ( Exception $e ) {
            wfDebugLog( 'resourceloader', __METHOD__ . ": failed to update DB: $e" );
        }
    }

    public static function getRelativePaths( array $filePaths ) {
        global $IP;
        return array_map( function ( $path ) use ( $IP ) {
            return RelPath\getRelativePath( $path, $IP );
        }, $filePaths );
    }

    public static function expandRelativePaths( array $filePaths ) {
        global $IP;
        return array_map( function ( $path ) use ( $IP ) {
            return RelPath\joinPath( $IP, $path );
        }, $filePaths );
    }

    protected function getMessageBlob( ResourceLoaderContext $context ) {
        if ( !$this->getMessages() ) {
            // Don't bother consulting MessageBlobStore
            return null;
        }
        // Message blobs may only vary language, not by context keys
        $lang = $context->getLanguage();
        if ( !isset( $this->msgBlobs[$lang] ) ) {
            $this->getLogger()->warning( 'Message blob for {module} should have been preloaded', [
                'module' => $this->getName(),
            ] );
            $store = $context->getResourceLoader()->getMessageBlobStore();
            $this->msgBlobs[$lang] = $store->getBlob( $this, $lang );
        }
        return $this->msgBlobs[$lang];
    }

    public function setMessageBlob( $blob, $lang ) {
        $this->msgBlobs[$lang] = $blob;
    }

    protected function getLessVars( ResourceLoaderContext $context ) {
        return [];
    }

    public function getModuleContent( ResourceLoaderContext $context ) {
        $contextHash = $context->getHash();
        // Cache this expensive operation. This calls builds the scripts, styles, and messages
        // content which typically involves filesystem and/or database access.
        if ( !array_key_exists( $contextHash, $this->contents ) ) {
            $this->contents[$contextHash] = $this->buildContent( $context );
        }
        return $this->contents[$contextHash];
    }

    final protected function buildContent( ResourceLoaderContext $context ) {
        $rl = $context->getResourceLoader();
        $stats = RequestContext::getMain()->getStats();
        $statStart = microtime( true );

        // Only include properties that are relevant to this context (e.g. only=scripts)
        // and that are non-empty (e.g. don't include "templates" for modules without
        // templates). This helps prevent invalidating cache for all modules when new
        // optional properties are introduced.
        $content = [];

        // Scripts
        if ( $context->shouldIncludeScripts() ) {
            // If we are in debug mode, we'll want to return an array of URLs if possible
            // However, we can't do this if the module doesn't support it
            // We also can't do this if there is an only= parameter, because we have to give
            // the module a way to return a load.php URL without causing an infinite loop
            if ( $context->getDebug() && !$context->getOnly() && $this->supportsURLLoading() ) {
                $scripts = $this->getScriptURLsForDebug( $context );
            } else {
                $scripts = $this->getScript( $context );
                // rtrim() because there are usually a few line breaks
                // after the last ';'. A new line at EOF, a new line
                // added by ResourceLoaderFileModule::readScriptFiles, etc.
                if ( is_string( $scripts )
                    && strlen( $scripts )
                    && substr( rtrim( $scripts ), -1 ) !== ';'
                ) {
                    // Append semicolon to prevent weird bugs caused by files not
                    // terminating their statements right (bug 27054)
                    $scripts .= ";\n";
                }
            }
            $content['scripts'] = $scripts;
        }

        // Styles
        if ( $context->shouldIncludeStyles() ) {
            $styles = [];
            // Don't create empty stylesheets like [ '' => '' ] for modules
            // that don't *have* any stylesheets (bug 38024).
            $stylePairs = $this->getStyles( $context );
            if ( count( $stylePairs ) ) {
                // If we are in debug mode without &only= set, we'll want to return an array of URLs
                // See comment near shouldIncludeScripts() for more details
                if ( $context->getDebug() && !$context->getOnly() && $this->supportsURLLoading() ) {
                    $styles = [
                        'url' => $this->getStyleURLsForDebug( $context )
                    ];
                } else {
                    // Minify CSS before embedding in mw.loader.implement call
                    // (unless in debug mode)
                    if ( !$context->getDebug() ) {
                        foreach ( $stylePairs as $media => $style ) {
                            // Can be either a string or an array of strings.
                            if ( is_array( $style ) ) {
                                $stylePairs[$media] = [];
                                foreach ( $style as $cssText ) {
                                    if ( is_string( $cssText ) ) {
                                        $stylePairs[$media][] =
                                            ResourceLoader::filter( 'minify-css', $cssText );
                                    }
                                }
                            } elseif ( is_string( $style ) ) {
                                $stylePairs[$media] = ResourceLoader::filter( 'minify-css', $style );
                            }
                        }
                    }
                    // Wrap styles into @media groups as needed and flatten into a numerical array
                    $styles = [
                        'css' => $rl->makeCombinedStyles( $stylePairs )
                    ];
                }
            }
            $content['styles'] = $styles;
        }

        // Messages
        $blob = $this->getMessageBlob( $context );
        if ( $blob ) {
            $content['messagesBlob'] = $blob;
        }

        $templates = $this->getTemplates();
        if ( $templates ) {
            $content['templates'] = $templates;
        }

        $statTiming = microtime( true ) - $statStart;
        $statName = strtr( $this->getName(), '.', '_' );
        $stats->timing( "resourceloader_build.all", 1000 * $statTiming );
        $stats->timing( "resourceloader_build.$statName", 1000 * $statTiming );

        return $content;
    }

    public function getVersionHash( ResourceLoaderContext $context ) {
        // The startup module produces a manifest with versions representing the entire module.
        // Typically, the request for the startup module itself has only=scripts. That must apply
        // only to the startup module content, and not to the module version computed here.
        $context = new DerivativeResourceLoaderContext( $context );
        $context->setModules( [] );
        // Version hash must cover all resources, regardless of startup request itself.
        $context->setOnly( null );
        // Compute version hash based on content, not debug urls.
        $context->setDebug( false );

        // Cache this somewhat expensive operation. Especially because some classes
        // (e.g. startup module) iterate more than once over all modules to get versions.
        $contextHash = $context->getHash();
        if ( !array_key_exists( $contextHash, $this->versionHash ) ) {

            if ( $this->enableModuleContentVersion() ) {
                // Detect changes directly
                $str = json_encode( $this->getModuleContent( $context ) );
            } else {
                // Infer changes based on definition and other metrics
                $summary = $this->getDefinitionSummary( $context );
                if ( !isset( $summary['_cacheEpoch'] ) ) {
                    throw new LogicException( 'getDefinitionSummary must call parent method' );
                }
                $str = json_encode( $summary );

                $mtime = $this->getModifiedTime( $context );
                if ( $mtime !== null ) {
                    // Support: MediaWiki 1.25 and earlier
                    $str .= strval( $mtime );
                }

                $mhash = $this->getModifiedHash( $context );
                if ( $mhash !== null ) {
                    // Support: MediaWiki 1.25 and earlier
                    $str .= strval( $mhash );
                }
            }

            $this->versionHash[$contextHash] = ResourceLoader::makeHash( $str );
        }
        return $this->versionHash[$contextHash];
    }

    public function enableModuleContentVersion() {
        return false;
    }

    public function getDefinitionSummary( ResourceLoaderContext $context ) {
        return [
            '_class' => get_class( $this ),
            '_cacheEpoch' => $this->getConfig()->get( 'CacheEpoch' ),
        ];
    }

    public function getModifiedTime( ResourceLoaderContext $context ) {
        return null;
    }

    public function getModifiedHash( ResourceLoaderContext $context ) {
        return null;
    }

    public function getHashMtime( ResourceLoaderContext $context ) {
        if ( !is_string( $this->getModifiedHash( $context ) ) ) {
            return 1;
        }
        // Dummy that is > 1
        return 2;
    }

    public function getDefinitionMtime( ResourceLoaderContext $context ) {
        if ( $this->getDefinitionSummary( $context ) === null ) {
            return 1;
        }
        // Dummy that is > 1
        return 2;
    }

    public function isKnownEmpty( ResourceLoaderContext $context ) {
        return false;
    }

    private static $jsParser;
    private static $parseCacheVersion = 1;

    protected function validateScriptFile( $fileName, $contents ) {
        if ( $this->getConfig()->get( 'ResourceLoaderValidateJS' ) ) {
            // Try for cache hit
            $cache = ObjectCache::getMainWANInstance();
            $key = $cache->makeKey(
                'resourceloader',
                'jsparse',
                self::$parseCacheVersion,
                md5( $contents )
            );
            $cacheEntry = $cache->get( $key );
            if ( is_string( $cacheEntry ) ) {
                return $cacheEntry;
            }

            $parser = self::javaScriptParser();
            try {
                $parser->parse( $contents, $fileName, 1 );
                $result = $contents;
            } catch ( Exception $e ) {
                // We'll save this to cache to avoid having to validate broken JS over and over...
                $err = $e->getMessage();
                $result = "mw.log.error(" .
                    Xml::encodeJsVar( "JavaScript parse error: $err" ) . ");";
            }

            $cache->set( $key, $result );
            return $result;
        } else {
            return $contents;
        }
    }

    protected static function javaScriptParser() {
        if ( !self::$jsParser ) {
            self::$jsParser = new JSParser();
        }
        return self::$jsParser;
    }

    protected static function safeFilemtime( $filePath ) {
        MediaWiki\suppressWarnings();
        $mtime = filemtime( $filePath ) ?: 1;
        MediaWiki\restoreWarnings();
        return $mtime;
    }

    protected static function safeFileHash( $filePath ) {
        return FileContentsHasher::getFileContentsHash( $filePath );
    }
}