ResourceLoaderModule.php

Go to the documentation of this file.

<?php
use MediaWiki\HookContainer\HookContainer;
use MediaWiki\MainConfigNames;
use MediaWiki\MediaWikiServices;
use MediaWiki\ResourceLoader\HookRunner;
use Psr\Log\LoggerAwareInterface;
use Psr\Log\LoggerInterface;
use Psr\Log\NullLogger;
use Wikimedia\RelPath;
use Wikimedia\RequestTimeout\TimeoutException;
 
abstract class ResourceLoaderModule implements LoggerAwareInterface {
    protected $config;
    protected $logger;
 
    protected $origin = self::ORIGIN_CORE_SITEWIDE;
 
    protected $name = null;
    protected $targets = [ 'desktop' ];
    protected $skins = null;
 
    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 GROUP_SITE = 'site';
    public const GROUP_USER = 'user';
    public const GROUP_PRIVATE = 'private';
    public const GROUP_NOSCRIPT = 'noscript';
 
    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;
 
    private const USERJSPARSE_CACHE_VERSION = 2;
 
    public function getName() {
        return $this->name;
    }
 
    public function setName( $name ) {
        $this->name = $name;
    }
 
    public function setSkinStylesOverride( array $moduleSkinStyles ): void {
        // Stub, only supported by FileModule currently.
    }
 
    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 ) {
            throw new RuntimeException( 'Config accessed before it is set' );
        }
 
        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 ) {
        $rl = $context->getResourceLoader();
        $derivative = new DerivativeResourceLoaderContext( $context );
        $derivative->setModules( [ $this->getName() ] );
        $derivative->setOnly( 'scripts' );
 
        $url = $rl->createLoaderURL(
            $this->getSource(),
            $derivative
        );
 
        // Expand debug URL in case we are another wiki's module source (T255367)
        $url = $rl->expandUrl( $this->getConfig()->get( MainConfigNames::Server ), $url );
 
        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' );
 
        $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 getSkins(): ?array {
        return $this->skins;
    }
 
    public function getType() {
        return self::LOAD_GENERAL;
    }
 
    public function getSkipFunction() {
        return null;
    }
 
    public function requiresES6() {
        return false;
    }
 
    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 ( TimeoutException $e ) {
            throw $e;
        } 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( static function ( $path ) use ( $IP ) {
            return RelPath::getRelativePath( $path, $IP );
        }, $filePaths );
    }
 
    public static function expandRelativePaths( array $filePaths ) {
        global $IP;
        return array_map( static 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 ( $context->getDebug() === $context::DEBUG_LEGACY && !$context->getOnly() && $this->supportsURLLoading() ) {
            // In legacy debug mode, let supporting modules like FileModule replace the bundled
            // script closure with an array of alternative script URLs to consecutively load instead.
            // See self::getScriptURLsForDebug() more details.
            $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 ) ) {
                $scripts = ResourceLoader::ensureNewline( $scripts );
            }
        }
        $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;
    }
 
    final public function getVersionHash( ResourceLoaderContext $context ) {
        if ( $context->getDebug() ) {
            // In debug mode, make uncached startup module extra fast by not computing any hashes.
            // Server responses from load.php for individual modules already have no-cache so
            // we don't need them. This also makes breakpoint debugging easier, as each module
            // gets its own consistent URL. (T235672)
            return '';
        }
 
        // 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() === self::GROUP_PRIVATE;
    }
 
    protected function validateScriptFile( $fileName, $contents ) {
        $error = null;
 
        if ( $this->getConfig()->get( MainConfigNames::ResourceLoaderValidateJS ) ) {
            $cache = MediaWikiServices::getInstance()->getMainWANObjectCache();
            // Cache potentially slow parsing of JavaScript code during the
            // critical path. This happens lazily when responding to requests
            // for modules=site, modules=user, and Gadgets.
            $error = $cache->getWithSetCallback(
                $cache->makeKey(
                    'resourceloader-userjsparse',
                    self::USERJSPARSE_CACHE_VERSION,
                    md5( $contents ),
                    $fileName
                ),
                $cache::TTL_WEEK,
                static function () use ( $contents, $fileName ) {
                    $parser = new JSParser();
                    try {
                        // Ignore compiler warnings (T77169)
                        // phpcs:ignore Generic.PHP.NoSilencedErrors.Discouraged
                        @$parser->parse( $contents, $fileName, 1 );
                    } catch ( TimeoutException $e ) {
                        throw $e;
                    } catch ( Exception $e ) {
                        return $e->getMessage();
                    }
                    // Cache success as null
                    return null;
                }
            );
        }
 
        if ( $error ) {
            // Send the error to the browser console client-side.
            // By returning this as replacement for the actual script,
            // we ensure user-provided scripts are safe to include in a batch
            // request, without risk of a syntax error in this blob breaking
            // the response itself.
            return 'mw.log.error(' .
                json_encode(
                    'JavaScript parse error (scripts need to be valid ECMAScript 5): ' .
                    $error
                ) .
                ');';
        } else {
            return $contents;
        }
    }
 
    protected static function safeFileHash( $filePath ) {
        return FileContentsHasher::getFileContentsHash( $filePath );
    }
 
    public static function getVary( ResourceLoaderContext $context ) {
        return implode( '|', [
            $context->getSkin(),
            $context->getLanguage(),
        ] );
    }
}