ResourceLoaderModule.php

Go to the documentation of this file.

<?php
use MediaWiki\MediaWikiServices;
use Psr\Log\LoggerAwareInterface;
use Psr\Log\LoggerInterface;
use Psr\Log\NullLogger;
use Wikimedia\RelPath;
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 $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;

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

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

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

    public function getFlip( $context ) {
        return MediaWikiServices::getInstance()->getContentLanguage()->getDir() !==
            $context->getDirection();
    }

    public function getDeprecationInformation() {
        $deprecationInfo = $this->deprecated;
        if ( $deprecationInfo ) {
            $name = $this->getName();
            $warning = 'This page is using the deprecated ResourceLoader module "' . $name . '".';
            if ( is_string( $deprecationInfo ) ) {
                $warning .= "\n" . $deprecationInfo;
            }
            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 = MediaWikiServices::getInstance()->getMainConfig();
        }

        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 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)json_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 ) {
        try {
            // Related bugs and performance considerations:
            // 1. Don't needlessly change the database value with the same list in a
            //    different order or with duplicates.
            // 2. Use relative paths to avoid ghost entries when $IP changes. (T111481)
            // 3. Don't needlessly replace the database with the same value
            //    just because $IP changed (e.g. when upgrading a wiki).
            // 4. Don't create an endless replace loop on every request for this
            //    module when '../' is used anywhere. Even though both are expanded
            //    (one expanded by getFileDependencies from the DB, the other is
            //    still raw as originally read by RL), the latter has not
            //    been normalized yet.

            // Normalise
            $localFileRefs = array_values( array_unique( $localFileRefs ) );
            sort( $localFileRefs );
            $localPaths = self::getRelativePaths( $localFileRefs );
            $storedPaths = self::getRelativePaths( $this->getFileDependencies( $context ) );

            if ( $localPaths === $storedPaths ) {
                // Unchanged. Avoid needless database query (especially master conn!).
                return;
            }

            // The file deps list has changed, we want to update it.
            $vary = $context->getSkin() . '|' . $context->getLanguage();
            $cache = ObjectCache::getLocalClusterInstance();
            $key = $cache->makeKey( __METHOD__, $this->getName(), $vary );
            $scopeLock = $cache->getScopedLock( $key, 0 );
            if ( !$scopeLock ) {
                // Another request appears to be doing this update already.
                // Avoid write slams (T124649).
                return;
            }

            // No needless escaping as this isn't HTML output.
            // Only stored in the database and parsed in PHP.
            $deps = json_encode( $localPaths, JSON_UNESCAPED_SLASHES );
            $dbw = wfGetDB( DB_MASTER );
            $dbw->upsert( 'module_deps',
                [
                    'md_module' => $this->getName(),
                    'md_skin' => $vary,
                    'md_deps' => $deps,
                ],
                [ 'md_module', 'md_skin' ],
                [
                    'md_deps' => $deps,
                ]
            );

            if ( $dbw->trxLevel() ) {
                $dbw->onTransactionResolution(
                    function () use ( &$scopeLock ) {
                        ScopedCallback::consume( $scopeLock ); // release after commit
                    },
                    __METHOD__
                );
            }
        } catch ( Exception $e ) {
            // Probably a DB failure. Either the read query from getFileDependencies(),
            // or the write query above.
            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;
    }

    final public function getHeaders( ResourceLoaderContext $context ) {
        $headers = [];

        $formattedLinks = [];
        foreach ( $this->getPreloadLinks( $context ) as $url => $attribs ) {
            $link = "<{$url}>;rel=preload";
            foreach ( $attribs as $key => $val ) {
                $link .= ";{$key}={$val}";
            }
            $formattedLinks[] = $link;
        }
        if ( $formattedLinks ) {
            $headers[] = 'Link: ' . implode( ',', $formattedLinks );
        }

        return $headers;
    }

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

    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 = MediaWikiServices::getInstance()->getStatsdDataFactory();
        $statStart = microtime( true );

        // This MUST build both scripts and styles, regardless of whether $context->getOnly()
        // is 'scripts' or 'styles' because the result is used by getVersionHash which
        // must be consistent regardless of the 'only' filter on the current request.
        // Also, when introducing new module content resources (e.g. templates, headers),
        // these should only be included in the array when they are non-empty so that
        // existing modules not using them do not get their cache invalidated.
        $content = [];

        // Scripts
        // 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 );
            // Make the script safe to concatenate by making sure there is at least one
            // trailing new line at the end of the content. Previously, this looked for
            // a semi-colon instead, but that breaks concatenation if the semicolon
            // is inside a comment like "// foo();". Instead, simply use a
            // line break as separator which matches JavaScript native logic for implicitly
            // ending statements even if a semi-colon is missing.
            // Bugs: T29054, T162719.
            if ( is_string( $scripts )
                && strlen( $scripts )
                && substr( $scripts, -1 ) !== "\n"
            ) {
                $scripts .= "\n";
            }
        }
        $content['scripts'] = $scripts;

        $styles = [];
        // Don't create empty stylesheets like [ '' => '' ] for modules
        // that don't *have* any stylesheets (T40024).
        $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;
        }

        $headers = $this->getHeaders( $context );
        if ( $headers ) {
            $content['headers'] = $headers;
        }

        $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 ) {
        // 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 by hashing the module contents.
                $str = json_encode( $this->getModuleContent( $context ) );
            } else {
                // Infer changes based on definition and other metrics
                $summary = $this->getDefinitionSummary( $context );
                if ( !isset( $summary['_class'] ) ) {
                    throw new LogicException( 'getDefinitionSummary must call parent method' );
                }
                $str = json_encode( $summary );
            }

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

    public function enableModuleContentVersion() {
        return false;
    }

    public function getDefinitionSummary( ResourceLoaderContext $context ) {
        return [
            '_class' => static::class,
            // Make sure that when filter cache for minification is invalidated,
            // we also change the HTTP urls and mw.loader.store keys (T176884).
            '_cacheVersion' => ResourceLoader::CACHE_VERSION,
        ];
    }

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

    public function shouldEmbedModule( ResourceLoaderContext $context ) {
        return $this->getGroup() === 'private';
    }

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

    protected function validateScriptFile( $fileName, $contents ) {
        if ( !$this->getConfig()->get( 'ResourceLoaderValidateJS' ) ) {
            return $contents;
        }
        $cache = MediaWikiServices::getInstance()->getMainWANObjectCache();
        return $cache->getWithSetCallback(
            $cache->makeGlobalKey(
                'resourceloader',
                'jsparse',
                self::$parseCacheVersion,
                md5( $contents ),
                $fileName
            ),
            $cache::TTL_WEEK,
            function () use ( $contents, $fileName ) {
                $parser = self::javaScriptParser();
                $err = null;
                try {
                    Wikimedia\suppressWarnings();
                    $parser->parse( $contents, $fileName, 1 );
                } catch ( Exception $e ) {
                    $err = $e;
                } finally {
                    Wikimedia\restoreWarnings();
                }
                if ( $err ) {
                    // Send the error to the browser console client-side.
                    // By returning this as replacement for the actual script,
                    // we ensure modules are safe to load in a batch request,
                    // without causing other unrelated modules to break.
                    return 'mw.log.error(' .
                        Xml::encodeJsVar( 'JavaScript parse error: ' . $err->getMessage() ) .
                        ');';
                }
                return $contents;
            }
        );
    }

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

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

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