ResourceLoaderModule.php

Go to the documentation of this file.

<?php
use MediaWiki\HookContainer\HookContainer;
use MediaWiki\HookContainer\HookRunner;
use MediaWiki\MediaWikiServices;
use Psr\Log\LoggerAwareInterface;
use Psr\Log\LoggerInterface;
use Psr\Log\NullLogger;
use Wikimedia\AtEase\AtEase;
use Wikimedia\RelPath;
 
abstract class ResourceLoaderModule implements LoggerAwareInterface {
    protected $config;
    protected $logger;
 
    protected $origin = self::ORIGIN_CORE_SITEWIDE;
 
    protected $name = null;
    protected $targets = [ 'desktop' ];
 
    protected $fileDeps = [];
    protected $msgBlobs = [];
    protected $versionHash = [];
    protected $contents = [];
 
    private $hookRunner;
 
    private $depLoadCallback;
    private $depSaveCallback;
 
    protected $deprecated = false;
 
    public const TYPE_SCRIPTS = 'scripts';
    public const TYPE_STYLES = 'styles';
    public const TYPE_COMBINED = 'combined';
 
    public const LOAD_STYLES = 'styles';
    public const LOAD_GENERAL = 'general';
 
    public const ORIGIN_CORE_SITEWIDE = 1;
    public const ORIGIN_CORE_INDIVIDUAL = 2;
    public const ORIGIN_USER_SITEWIDE = 3;
    public const ORIGIN_USER_INDIVIDUAL = 4;
    public const ORIGIN_ALL = 10;
 
    public function getName() {
        return $this->name;
    }
 
    public function setName( $name ) {
        $this->name = $name;
    }
 
    public function setDependencyAccessCallbacks( callable $loadCallback, callable $saveCallback ) {
        $this->depLoadCallback = $loadCallback;
        $this->depSaveCallback = $saveCallback;
    }
 
    public function getOrigin() {
        return $this->origin;
    }
 
    public function getFlip( ResourceLoaderContext $context ) {
        return MediaWikiServices::getInstance()->getContentLanguage()->getDir() !==
            $context->getDirection();
    }
 
    public function getDeprecationInformation( ResourceLoaderContext $context ) {
        $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 'mw.log.warn(' . $context->encodeJson( $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 setHookContainer( HookContainer $hookContainer ) : void {
        $this->hookRunner = new HookRunner( $hookContainer );
    }
 
    protected function getHookRunner() : HookRunner {
        return $this->hookRunner;
    }
 
    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 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 ) {
        $variant = self::getVary( $context );
 
        if ( !isset( $this->fileDeps[$variant] ) ) {
            if ( $this->depLoadCallback ) {
                $this->fileDeps[$variant] =
                    call_user_func( $this->depLoadCallback, $this->getName(), $variant );
            } else {
                $this->getLogger()->info( __METHOD__ . ": no callback registered" );
                $this->fileDeps[$variant] = [];
            }
        }
 
        return $this->fileDeps[$variant];
    }
 
    public function setFileDependencies( ResourceLoaderContext $context, array $paths ) {
        $variant = self::getVary( $context );
        $this->fileDeps[$variant] = $paths;
    }
 
    protected function saveFileDependencies( ResourceLoaderContext $context, array $curFileRefs ) {
        if ( !$this->depSaveCallback ) {
            $this->getLogger()->info( __METHOD__ . ": no callback registered" );
 
            return;
        }
 
        try {
            // Pitfalls and performance considerations:
            // 1. Don't keep updating the tracked paths due to duplicates or sorting.
            // 2. Use relative paths to avoid ghost entries when $IP changes. (T111481)
            // 3. Don't needlessly replace tracked paths 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.
            call_user_func(
                $this->depSaveCallback,
                $this->getName(),
                self::getVary( $context ),
                self::getRelativePaths( $curFileRefs ),
                self::getRelativePaths( $this->getFileDependencies( $context ) )
            );
        } catch ( Exception $e ) {
            $this->getLogger()->warning(
                __METHOD__ . ": failed to update dependencies: {$e->getMessage()}",
                [ 'exception' => $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 ) {
        $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' => ResourceLoader::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 $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 = new JSParser();
                $err = null;
                try {
                    AtEase::suppressWarnings();
                    $parser->parse( $contents, $fileName, 1 );
                } catch ( Exception $e ) {
                    $err = $e;
                } finally {
                    AtEase::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 (scripts need to be valid ECMAScript 5): ' .
                        $err->getMessage() ) . ');';
                }
                return $contents;
            }
        );
    }
 
    protected static function safeFileHash( $filePath ) {
        return FileContentsHasher::getFileContentsHash( $filePath );
    }
 
    public static function getVary( ResourceLoaderContext $context ) {
        return implode( '|', [
            $context->getSkin(),
            $context->getLanguage(),
        ] );
    }
}