Module.php

Go to the documentation of this file.

<?php
namespace MediaWiki\ResourceLoader;
 
use InvalidArgumentException;
use LogicException;
use MediaWiki\Config\Config;
use MediaWiki\HookContainer\HookContainer;
use MediaWiki\MainConfigNames;
use MediaWiki\MediaWikiServices;
use MediaWiki\Utils\FileContentsHasher;
use Peast\Peast;
use Peast\Syntax\Exception as PeastSyntaxException;
use Psr\Log\LoggerAwareInterface;
use Psr\Log\LoggerInterface;
use Psr\Log\NullLogger;
use RuntimeException;
use Wikimedia\RelPath;
 
abstract class Module implements LoggerAwareInterface {
    protected $config;
    protected $logger;
 
    private ?VueComponentParser $vueComponentParser = null;
 
    protected $origin = self::ORIGIN_CORE_SITEWIDE;
 
    protected $name = null;
    protected $skins = null;
 
    protected $fileDeps = [];
    protected $msgBlobs = [];
    protected $versionHash = [];
    protected $contents = [];
 
    private $hookRunner;
 
    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 = 4;
 
    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 getOrigin() {
        return $this->origin;
    }
 
    public function getFlip( Context $context ) {
        return MediaWikiServices::getInstance()->getContentLanguage()->getDir() !==
            $context->getDirection();
    }
 
    public function getDeprecationWarning() {
        if ( !$this->deprecated ) {
            return null;
        }
        $name = $this->getName();
        $warning = 'This page is using the deprecated ResourceLoader module "' . $name . '".';
        if ( is_string( $this->deprecated ) ) {
            $warning .= "\n" . $this->deprecated;
        }
        return $warning;
    }
 
    public function getScript( Context $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 ): void {
        $this->logger = $logger;
    }
 
    protected function getLogger(): LoggerInterface {
        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 supportsURLLoading() {
        return true;
    }
 
    public function getStyles( Context $context ) {
        // Stub, override expected
        return [];
    }
 
    public function getStyleURLsForDebug( Context $context ) {
        $resourceLoader = $context->getResourceLoader();
        $derivative = new DerivativeContext( $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( ?Context $context = null ) {
        // Stub, override expected
        return [];
    }
 
    public function getSkins(): ?array {
        return $this->skins;
    }
 
    public function getType() {
        return self::LOAD_GENERAL;
    }
 
    public function getSkipFunction() {
        return null;
    }
 
    public function requiresES6() {
        return true;
    }
 
    protected function getFileDependencies( Context $context ) {
        $variant = self::getVary( $context );
 
        if ( !isset( $this->fileDeps[$variant] ) ) {
            $depStore = $context->getResourceLoader()->getDependencyStore();
            $moduleName = $this->getName();
            $styleDependencies = $depStore->retrieve( "$moduleName|$variant" );
            $this->fileDeps[$variant] = $styleDependencies['paths'];
        }
 
        return $this->fileDeps[$variant];
    }
 
    public function setFileDependencies( Context $context, array $paths ) {
        $variant = self::getVary( $context );
        $this->fileDeps[$variant] = $paths;
    }
 
    protected function saveFileDependencies( Context $context, array $curFileRefs ) {
        // 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.
 
        $paths = self::getRelativePaths( $curFileRefs );
        $priorPaths = $this->getFileDependencies( $context );
 
        if ( array_diff( $paths, $priorPaths ) || array_diff( $priorPaths, $paths ) ) {
            $depStore = $context->getResourceLoader()->getDependencyStore();
            $variant = self::getVary( $context );
            $moduleName = $this->getName();
            $depStore->storeMulti( [ "$moduleName|$variant" => $paths ] );
        }
    }
 
    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( Context $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( Context $context ) {
        $formattedLinks = [];
        foreach ( $this->getPreloadLinks( $context ) as $url => $attribs ) {
            $link = "<{$url}>;rel=preload";
            foreach ( $attribs as $key => $val ) {
                $link .= ";{$key}={$val}";
            }
            $formattedLinks[] = $link;
        }
        if ( $formattedLinks ) {
            return [ 'Link: ' . implode( ',', $formattedLinks ) ];
        }
        return [];
    }
 
    protected function getPreloadLinks( Context $context ) {
        return [];
    }
 
    protected function getLessVars( Context $context ) {
        return [];
    }
 
    public function getModuleContent( Context $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( Context $context ) {
        $statsFactory = MediaWikiServices::getInstance()->getStatsFactory();
        $timer = $statsFactory->getTiming( 'resourceloader_build_seconds' )
            ->setLabel( 'name', strtr( $this->getName(), '.', '_' ) )
            ->start();
 
        // 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
        $scripts = $this->getScript( $context );
        if ( is_string( $scripts ) ) {
            $scripts = [ 'plainScripts' => [ [ 'content' => $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.impl 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;
        }
 
        $deprecationWarning = $this->getDeprecationWarning();
        if ( $deprecationWarning !== null ) {
            $content['deprecationWarning'] = $deprecationWarning;
        }
 
        $timer->stop();
 
        return $content;
    }
 
    final public function getVersionHash( Context $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( Context $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( Context $context ) {
        return false;
    }
 
    public function shouldEmbedModule( Context $context ) {
        return $this->getGroup() === self::GROUP_PRIVATE;
    }
 
    public function shouldSkipStructureTest() {
        return $this->getGroup() === self::GROUP_PRIVATE;
    }
 
    protected function validateScriptFile( $fileName, $contents ) {
        if ( !$this->getConfig()->get( MainConfigNames::ResourceLoaderValidateJS ) ) {
            return $contents;
        }
        $cache = MediaWikiServices::getInstance()->getMainWANObjectCache();
        // Cache potentially slow parsing of JavaScript code during the critical path.
        // This happens during load.php requests for modules=site, modules=user, and Gadgets.
        $error = $cache->getWithSetCallback(
            // A content hash is included in the cache key so that this is immediately
            // correct and re-computed after edits without relying on TTL or purges.
            //
            // We avoid accidental or abusive conflicts with other pages by including the
            // wiki (makeKey vs makeGlobalKey) and page, because hashes are not unique.
            $cache->makeKey(
                'resourceloader-userjsparse',
                self::USERJSPARSE_CACHE_VERSION,
                md5( $contents ),
                $fileName
            ),
            $cache::TTL_WEEK,
            static function () use ( $contents ) {
                try {
                    Peast::ES2017( $contents )->parse();
                } catch ( PeastSyntaxException $e ) {
                    return $e->getMessage() . " on line " . $e->getPosition()->getLine();
                }
                // 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 serve to a browser,
            // without breaking unrelated modules in the same response.
            return 'mw.log.error(' .
                json_encode(
                    "Parse error: $error in $fileName"
                ) .
                ');';
        }
        return $contents;
    }
 
    protected function parseVueContent( Context $context, string $content ): array {
        $this->vueComponentParser ??= new VueComponentParser;
        $parsedComponent = $this->vueComponentParser->parse(
            $content,
            [ 'minifyTemplate' => !$context->getDebug() ]
        );
        $encodedTemplate = json_encode( $parsedComponent['template'] );
        if ( $context->getDebug() ) {
            // Replace \n (backslash-n) with space + backslash-n + backslash-newline in debug mode
            // The \n has to be preserved to prevent Vue parser issues (T351771)
            // We only replace \n if not preceded by a backslash, to avoid breaking '\\n'
            $encodedTemplate = preg_replace( '/(?<!\\\\)\\\\n/', " \\n\\\n", $encodedTemplate );
            // Expand \t to real tabs in debug mode
            $encodedTemplate = strtr( $encodedTemplate, [ "\\t" => "\t" ] );
        }
        return [
            'script' => $parsedComponent['script'] .
                ";\nmodule.exports.template = $encodedTemplate;",
            'style' => $parsedComponent['style'] ?? '',
            'styleLang' => $parsedComponent['styleLang'] ?? 'css'
        ];
    }
 
    protected static function safeFileHash( $filePath ) {
        return FileContentsHasher::getFileContentsHash( $filePath );
    }
 
    public static function getVary( Context $context ) {
        return implode( '|', [
            $context->getSkin(),
            $context->getLanguage(),
        ] );
    }
}