ResourceLoaderModule.php

Go to the documentation of this file.

<?php
abstract class ResourceLoaderModule {

    # Type of resource
    const TYPE_SCRIPTS = 'scripts';
    const TYPE_STYLES = 'styles';
    const TYPE_MESSAGES = 'messages';
    const TYPE_COMBINED = 'combined';

    # 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 = array( 'desktop' );

    // In-object cache for file dependencies
    protected $fileDeps = array();
    // In-object cache for message blob mtime
    protected $msgBlobMtime = array();

    /* Methods */

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

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

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

    public function setOrigin( $origin ) {
        $this->origin = $origin;
    }

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

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

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

    public function getScriptURLsForDebug( ResourceLoaderContext $context ) {
        $url = ResourceLoader::makeLoaderURL(
            array( $this->getName() ),
            $context->getLanguage(),
            $context->getSkin(),
            $context->getUser(),
            $context->getVersion(),
            true, // debug
            'scripts', // only
            $context->getRequest()->getBool( 'printable' ),
            $context->getRequest()->getBool( 'handheld' )
        );
        return array( $url );
    }

    public function supportsURLLoading() {
        return true;
    }

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

    public function getStyleURLsForDebug( ResourceLoaderContext $context ) {
        $url = ResourceLoader::makeLoaderURL(
            array( $this->getName() ),
            $context->getLanguage(),
            $context->getSkin(),
            $context->getUser(),
            $context->getVersion(),
            true, // debug
            'styles', // only
            $context->getRequest()->getBool( 'printable' ),
            $context->getRequest()->getBool( 'handheld' )
        );
        return array( 'all' => array( $url ) );
    }

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

    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 getLoaderScript() {
        // Stub, override expected
        return false;
    }

    public function getDependencies() {
        // Stub, override expected
        return array();
    }

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

    public function getFileDependencies( $skin ) {
        // Try in-object cache first
        if ( isset( $this->fileDeps[$skin] ) ) {
            return $this->fileDeps[$skin];
        }

        $dbr = wfGetDB( DB_SLAVE );
        $deps = $dbr->selectField( 'module_deps', 'md_deps', array(
                'md_module' => $this->getName(),
                'md_skin' => $skin,
            ), __METHOD__
        );
        if ( !is_null( $deps ) ) {
            $this->fileDeps[$skin] = (array)FormatJson::decode( $deps, true );
        } else {
            $this->fileDeps[$skin] = array();
        }
        return $this->fileDeps[$skin];
    }

    public function setFileDependencies( $skin, $deps ) {
        $this->fileDeps[$skin] = $deps;
    }

    public function getMsgBlobMtime( $lang ) {
        if ( !isset( $this->msgBlobMtime[$lang] ) ) {
            if ( !count( $this->getMessages() ) ) {
                return 0;
            }

            $dbr = wfGetDB( DB_SLAVE );
            $msgBlobMtime = $dbr->selectField( 'msg_resource', 'mr_timestamp', array(
                    'mr_resource' => $this->getName(),
                    'mr_lang' => $lang
                ), __METHOD__
            );
            // If no blob was found, but the module does have messages, that means we need
            // to regenerate it. Return NOW
            if ( $msgBlobMtime === false ) {
                $msgBlobMtime = wfTimestampNow();
            }
            $this->msgBlobMtime[$lang] = wfTimestamp( TS_UNIX, $msgBlobMtime );
        }
        return $this->msgBlobMtime[$lang];
    }

    public function setMsgBlobMtime( $lang, $mtime ) {
        $this->msgBlobMtime[$lang] = $mtime;
    }

    /* Abstract Methods */

    public function getModifiedTime( ResourceLoaderContext $context ) {
        // 0 would mean now
        return 1;
    }

    public function getHashMtime( ResourceLoaderContext $context ) {
        $hash = $this->getModifiedHash( $context );
        if ( !is_string( $hash ) ) {
            return 0;
        }

        $cache = wfGetCache( CACHE_ANYTHING );
        $key = wfMemcKey( 'resourceloader', 'modulemodifiedhash', $this->getName(), $hash );

        $data = $cache->get( $key );
        if ( is_array( $data ) && $data['hash'] === $hash ) {
            // Hash is still the same, re-use the timestamp of when we first saw this hash.
            return $data['timestamp'];
        }

        $timestamp = wfTimestamp();
        $cache->set( $key, array(
            'hash' => $hash,
            'timestamp' => $timestamp,
        ) );

        return $timestamp;
    }

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

    public function getDefinitionMtime( ResourceLoaderContext $context ) {
        wfProfileIn( __METHOD__ );
        $summary = $this->getDefinitionSummary( $context );
        if ( $summary === null ) {
            wfProfileOut( __METHOD__ );
            return 0;
        }

        $hash = md5( json_encode( $summary ) );

        $cache = wfGetCache( CACHE_ANYTHING );

        // Embed the hash itself in the cache key. This allows for a few nifty things:
        // - During deployment, servers with old and new versions of the code communicating
        //   with the same memcached will not override the same key repeatedly increasing
        //   the timestamp.
        // - In case of the definition changing and then changing back in a short period of time
        //   (e.g. in case of a revert or a corrupt server) the old timestamp and client-side cache
        //   url will be re-used.
        // - If different context-combinations (e.g. same skin, same language or some combination
        //   thereof) result in the same definition, they will use the same hash and timestamp.
        $key = wfMemcKey( 'resourceloader', 'moduledefinition', $this->getName(), $hash );

        $data = $cache->get( $key );
        if ( is_int( $data ) && $data > 0 ) {
            // We've seen this hash before, re-use the timestamp of when we first saw it.
            wfProfileOut( __METHOD__ );
            return $data;
        }

        wfDebugLog( 'resourceloader', __METHOD__ . ": New definition hash for module {$this->getName()} in context {$context->getHash()}: $hash." );

        $timestamp = time();
        $cache->set( $key, $timestamp );

        wfProfileOut( __METHOD__ );
        return $timestamp;
    }

    public function getDefinitionSummary( ResourceLoaderContext $context ) {
        return array(
            'class' => get_class( $this ),
        );
    }

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

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

    protected function validateScriptFile( $fileName, $contents ) {
        global $wgResourceLoaderValidateJS;
        if ( $wgResourceLoaderValidateJS ) {
            // Try for cache hit
            // Use CACHE_ANYTHING since filtering is very slow compared to DB queries
            $key = wfMemcKey( 'resourceloader', 'jsparse', self::$parseCacheVersion, md5( $contents ) );
            $cache = wfGetCache( CACHE_ANYTHING );
            $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 = "throw new 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( $filename ) {
        if ( file_exists( $filename ) ) {
            return filemtime( $filename );
        } else {
            // We only ever map this function on an array if we're gonna call max() after,
            // so return our standard minimum timestamps here. This is 1, not 0, because
            // wfTimestamp(0) == NOW
            return 1;
        }
    }
}