SkinModule.php

Go to the documentation of this file.

<?php
namespace MediaWiki\ResourceLoader;
 
use InvalidArgumentException;
use MediaWiki\Config\Config;
use MediaWiki\MainConfigNames;
use MediaWiki\Output\OutputPage;
use Wikimedia\Minify\CSSMin;
 
class SkinModule extends LessVarFileModule {
 
    private const FEATURE_FILES = [
        'accessibility' => [
            'all' => [ 'resources/src/mediawiki.skinning/accessibility.less' ],
        ],
        'normalize' => [
            'all' => [ 'resources/src/mediawiki.skinning/normalize.less' ],
        ],
        'logo' => [
            // Applies the logo and ensures it downloads prior to printing.
            'all' => [ 'resources/src/mediawiki.skinning/logo.less' ],
            // Reserves whitespace for the logo in a pseudo element.
            'print' => [ 'resources/src/mediawiki.skinning/logo-print.less' ],
        ],
        'content-media' => [],
        'content-links' => [
            'screen' => [ 'resources/src/mediawiki.skinning/content.links.less' ]
        ],
        'content-links-external' => [
            'screen' => [ 'resources/src/mediawiki.skinning/content.externallinks.less' ]
        ],
        'content-body' => [
            'screen' => [ 'resources/src/mediawiki.skinning/content.body.less' ],
            'print' => [ 'resources/src/mediawiki.skinning/content.body-print.less' ],
        ],
        'content-tables' => [
            'screen' => [ 'resources/src/mediawiki.skinning/content.tables.less' ],
            'print' => [ 'resources/src/mediawiki.skinning/content.tables-print.less' ]
        ],
        // Legacy shorthand for 6 features: interface-core, interface-edit-section-links,
        // interface-indicators, interface-subtitle, interface-site-notice, interface-user-message
        'interface' => [],
        'interface-category' => [
            'screen' => [ 'resources/src/mediawiki.skinning/interface.category.less' ],
            'print' => [ 'resources/src/mediawiki.skinning/interface.category-print.less' ],
        ],
        'interface-core' => [
            'screen' => [ 'resources/src/mediawiki.skinning/interface.less' ],
            'print' => [ 'resources/src/mediawiki.skinning/interface-print.less' ],
        ],
        'interface-edit-section-links' => [
            'screen' => [ 'resources/src/mediawiki.skinning/interface-edit-section-links.less' ],
        ],
        'interface-indicators' => [
            'screen' => [ 'resources/src/mediawiki.skinning/interface-indicators.less' ],
        ],
        'interface-site-notice' => [
            'screen' => [ 'resources/src/mediawiki.skinning/interface-site-notice.less' ],
        ],
        'interface-subtitle' => [
            'screen' => [ 'resources/src/mediawiki.skinning/interface-subtitle.less' ],
        ],
        'interface-message-box' => [
            'all' => [ 'resources/src/mediawiki.skinning/messageBoxes.less' ],
        ],
        'interface-user-message' => [
            'screen' => [ 'resources/src/mediawiki.skinning/interface-user-message.less' ],
        ],
        'elements' => [
            'screen' => [ 'resources/src/mediawiki.skinning/elements.less' ],
            'print' => [ 'resources/src/mediawiki.skinning/elements-print.less' ],
        ],
        // The styles of the legacy feature was removed in 1.39. This can be removed when no skins are referencing it
        // (Dropping this line will trigger InvalidArgumentException: Feature 'legacy' is not recognised)
        'legacy' => [],
        'i18n-ordered-lists' => [
            'screen' => [ 'resources/src/mediawiki.skinning/i18n-ordered-lists.less' ],
        ],
        'i18n-all-lists-margins' => [
            'screen' => [ 'resources/src/mediawiki.skinning/i18n-all-lists-margins.less' ],
        ],
        'i18n-headings' => [
            'screen' => [ 'resources/src/mediawiki.skinning/i18n-headings.less' ],
        ],
        'toc' => [
            'all' => [ 'resources/src/mediawiki.skinning/toc/common.css' ],
            'screen' => [ 'resources/src/mediawiki.skinning/toc/screen.less' ],
            'print' => [ 'resources/src/mediawiki.skinning/toc/print.css' ],
        ],
    ];
 
    private $features;
 
    private const DEFAULT_FEATURES_SPECIFIED = [
        'accessibility' => true,
        'content-body' => true,
        'interface-core' => true,
        'toc' => true
    ];
 
    private const DEFAULT_FEATURES_ABSENT = [
        'logo',
    ];
 
    private const LESS_MESSAGES = [
        // `toc` feature, used in screen.less
        'hidetoc',
        'showtoc',
    ];
 
    public function __construct(
        array $options = [],
        $localBasePath = null,
        $remoteBasePath = null
    ) {
        $features = $options['features'] ?? self::DEFAULT_FEATURES_ABSENT;
        $listMode = array_keys( $features ) === range( 0, count( $features ) - 1 );
 
        $messages = '';
        // NOTE: Compatibility is only applied when features are provided
        // in map-form. The list-form does not currently get these.
        $features = $listMode ? self::applyFeaturesCompatibility(
            array_fill_keys( $features, true ), false, $messages
        ) : self::applyFeaturesCompatibility( $features, true, $messages );
 
        foreach ( $features as $key => $enabled ) {
            if ( !isset( self::FEATURE_FILES[$key] ) ) {
                throw new InvalidArgumentException( "Feature '$key' is not recognised" );
            }
        }
 
        $this->features = $listMode
            ? array_keys( array_filter( $features ) )
            : array_keys( array_filter( $features + self::DEFAULT_FEATURES_SPECIFIED ) );
 
        // Only the `toc` feature makes use of interface messages.
        // For skins not using the `toc` feature, make sure LocalisationCache
        // remains untouched (T270027).
        if ( in_array( 'toc', $this->features ) ) {
            $options['lessMessages'] = array_merge(
                $options['lessMessages'] ?? [],
                self::LESS_MESSAGES
            );
        }
 
        if ( $messages !== '' ) {
            $messages .= 'More information can be found at [[mw:Manual:ResourceLoaderSkinModule]]. ';
            $options['deprecated'] = $messages;
        }
        parent::__construct( $options, $localBasePath, $remoteBasePath );
    }
 
    protected static function applyFeaturesCompatibility(
        array $features, bool $addUnspecifiedFeatures = true, &$messages = ''
    ): array {
        // The `content` feature is mapped to `content-media`.
        if ( isset( $features[ 'content' ] ) ) {
            $features[ 'content-media' ] = $features[ 'content' ];
            unset( $features[ 'content' ] );
            $messages .= '[1.37] The use of the `content` feature with SkinModule'
                . ' is deprecated. Use `content-media` instead. ';
        }
 
        // The `content-thumbnails` feature is mapped to `content-media`.
        if ( isset( $features[ 'content-thumbnails' ] ) ) {
            $features[ 'content-media' ] = $features[ 'content-thumbnails' ];
            $messages .= '[1.37] The use of the `content-thumbnails` feature with SkinModule'
                . ' is deprecated. Use `content-media` instead. ';
            unset( $features[ 'content-thumbnails' ] );
        }
 
        // If `content-links` feature is set but no preference for `content-links-external` is set
        if ( $addUnspecifiedFeatures && isset( $features[ 'content-links' ] )
            && !isset( $features[ 'content-links-external' ] )
        ) {
            // Assume the same true/false preference for both.
            $features[ 'content-links-external' ] = $features[ 'content-links' ];
        }
 
        // The legacy feature no longer exists (T89981) but to avoid fatals in skins is retained.
        if ( isset( $features['legacy'] ) && $features['legacy'] ) {
            $messages .= '[1.37] The use of the `legacy` feature with SkinModule is deprecated'
                . '(T89981) and is a NOOP since 1.39 (T304325). This should be urgently omited to retain compatibility '
                . 'with future MediaWiki versions';
        }
 
        // The `content-links` feature was split out from `elements`.
        // Make sure skins asking for `elements` also get these by default.
        if ( $addUnspecifiedFeatures && isset( $features[ 'element' ] ) && !isset( $features[ 'content-links' ] ) ) {
            $features[ 'content-links' ] = $features[ 'element' ];
        }
 
        // `content-parser-output` was renamed to `content-body`.
        // No need to go through deprecation process here since content-parser-output added and removed in 1.36.
        // Remove this check when no matches for
        // https://codesearch.wmcloud.org/search/?q=content-parser-output&i=nope&files=&excludeFiles=&repos=
        if ( isset( $features[ 'content-parser-output' ] ) ) {
            $features[ 'content-body' ] = $features[ 'content-parser-output' ];
            unset( $features[ 'content-parser-output' ] );
        }
 
        // The interface module is a short hand for several modules. Enable them now.
        if ( isset( $features[ 'interface' ] ) && $features[ 'interface' ] ) {
            unset( $features[ 'interface' ] );
            $features[ 'interface-core' ] = true;
            $features[ 'interface-indicators' ] = true;
            $features[ 'interface-subtitle' ] = true;
            $features[ 'interface-user-message' ] = true;
            $features[ 'interface-site-notice' ] = true;
            $features[ 'interface-edit-section-links' ] = true;
        }
        return $features;
    }
 
    public function getFeatureFilePaths() {
        // Bypass the current module paths so that these files are served from core,
        // instead of the individual skin's module directory.
        [ $defaultLocalBasePath, $defaultRemoteBasePath ] =
            FileModule::extractBasePaths(
                [],
                null,
                $this->getConfig()->get( MainConfigNames::ResourceBasePath )
            );
 
        $featureFilePaths = [];
 
        foreach ( self::FEATURE_FILES as $feature => $featureFiles ) {
            if ( in_array( $feature, $this->features ) ) {
                foreach ( $featureFiles as $mediaType => $files ) {
                    foreach ( $files as $filepath ) {
                        $featureFilePaths[$mediaType][] = new FilePath(
                            $filepath,
                            $defaultLocalBasePath,
                            $defaultRemoteBasePath
                        );
                    }
                }
 
                if ( $feature === 'content-media' ) {
                    if ( $this->getConfig()->get( MainConfigNames::UseLegacyMediaStyles ) ) {
                        $featureFilePaths['all'][] = new FilePath(
                            'resources/src/mediawiki.skinning/content.thumbnails-common.less',
                            $defaultLocalBasePath,
                            $defaultRemoteBasePath
                        );
                        $featureFilePaths['screen'][] = new FilePath(
                            'resources/src/mediawiki.skinning/content.thumbnails-screen.less',
                            $defaultLocalBasePath,
                            $defaultRemoteBasePath
                        );
                        $featureFilePaths['print'][] = new FilePath(
                            'resources/src/mediawiki.skinning/content.thumbnails-print.less',
                            $defaultLocalBasePath,
                            $defaultRemoteBasePath
                        );
                    }
                    if (
                        !$this->getConfig()->get( MainConfigNames::ParserEnableLegacyMediaDOM ) ||
                        $this->getConfig()->get( MainConfigNames::UseContentMediaStyles )
                    ) {
                        $featureFilePaths['all'][] = new FilePath(
                            'resources/src/mediawiki.skinning/content.media-common.less',
                            $defaultLocalBasePath,
                            $defaultRemoteBasePath
                        );
                        $featureFilePaths['screen'][] = new FilePath(
                            'resources/src/mediawiki.skinning/content.media-screen.less',
                            $defaultLocalBasePath,
                            $defaultRemoteBasePath
                        );
                        $featureFilePaths['print'][] = new FilePath(
                            'resources/src/mediawiki.skinning/content.media-print.less',
                            $defaultLocalBasePath,
                            $defaultRemoteBasePath
                        );
                    }
                }
            }
        }
        return $featureFilePaths;
    }
 
    private function combineFeatureAndParentStyles( $featureStyles, $parentStyles ) {
        $combinedFeatureStyles = ResourceLoader::makeCombinedStyles( $featureStyles );
        $combinedParentStyles = ResourceLoader::makeCombinedStyles( $parentStyles );
        $combinedStyles = array_merge( $combinedFeatureStyles, $combinedParentStyles );
        return [ '' => $combinedStyles ];
    }
 
    public function generateAndAppendLogoStyles( $featureStyles, $context ) {
        $logo = $this->getLogoData( $this->getConfig(), $context->getLanguage() );
        $default = !is_array( $logo ) ? $logo : ( $logo['svg'] ?? $logo['1x'] ?? null );
 
        // Can't add logo CSS if no logo defined.
        if ( !$default ) {
            return $featureStyles;
        }
 
        $featureStyles['all'][] = '.mw-wiki-logo { background-image: ' .
            CSSMin::buildUrlValue( $default ) .
            '; }';
 
        if ( is_array( $logo ) ) {
            if ( isset( $logo['svg'] ) ) {
                $featureStyles['all'][] = '.mw-wiki-logo { ' .
                    'background-size: 135px auto; }';
            } else {
                if ( isset( $logo['1.5x'] ) ) {
                    $featureStyles[
                        '(-webkit-min-device-pixel-ratio: 1.5), ' .
                        '(min-resolution: 1.5dppx), ' .
                        '(min-resolution: 144dpi)'
                    ][] = '.mw-wiki-logo { background-image: ' .
                        CSSMin::buildUrlValue( $logo['1.5x'] ) . ';' .
                        'background-size: 135px auto; }';
                }
                if ( isset( $logo['2x'] ) ) {
                    $featureStyles[
                        '(-webkit-min-device-pixel-ratio: 2), ' .
                        '(min-resolution: 2dppx), ' .
                        '(min-resolution: 192dpi)'
                    ][] = '.mw-wiki-logo { background-image: ' .
                        CSSMin::buildUrlValue( $logo['2x'] ) . ';' .
                        'background-size: 135px auto; }';
                }
            }
        }
        return $featureStyles;
    }
 
    public function getStyles( Context $context ) {
        $parentStyles = parent::getStyles( $context );
        $featureFilePaths = $this->getFeatureFilePaths();
        $featureStyles = $this->readStyleFiles( $featureFilePaths, $context );
 
        $this->normalizeStyles( $featureStyles );
        $this->normalizeStyles( $parentStyles );
 
        $isLogoFeatureEnabled = in_array( 'logo', $this->features );
        if ( $isLogoFeatureEnabled ) {
            $featureStyles = $this->generateAndAppendLogoStyles( $featureStyles, $context );
        }
 
        return $this->combineFeatureAndParentStyles( $featureStyles, $parentStyles );
    }
 
    public function getPreloadLinks( Context $context ): array {
        if ( !in_array( 'logo', $this->features ) ) {
            return [];
        }
 
        $logo = $this->getLogoData( $this->getConfig(), $context->getLanguage() );
 
        if ( !is_array( $logo ) ) {
            // No media queries required if we only have one variant
            return [ $logo => [ 'as' => 'image' ] ];
        }
 
        if ( isset( $logo['svg'] ) ) {
            // No media queries required if we only have a 1x and svg variant
            // because all preload-capable browsers support SVGs
            return [ $logo['svg'] => [ 'as' => 'image' ] ];
        }
 
        $logosPerDppx = [];
        foreach ( $logo as $dppx => $src ) {
            // Keys are in this format: "1.5x"
            $dppx = substr( $dppx, 0, -1 );
            $logosPerDppx[$dppx] = $src;
        }
 
        // Because PHP can't have floats as array keys
        uksort( $logosPerDppx, static function ( $a, $b ) {
            $a = floatval( $a );
            $b = floatval( $b );
            // Sort from smallest to largest (e.g. 1x, 1.5x, 2x)
            return $a <=> $b;
        } );
 
        $logos = [];
        foreach ( $logosPerDppx as $dppx => $src ) {
            $logos[] = [
                'dppx' => $dppx,
                'src' => $src
            ];
        }
 
        $logosCount = count( $logos );
        $preloadLinks = [];
        // Logic must match SkinModule:
        // - 1x applies to resolution < 1.5dppx
        // - 1.5x applies to resolution >= 1.5dppx && < 2dppx
        // - 2x applies to resolution >= 2dppx
        // Note that min-resolution and max-resolution are both inclusive.
        for ( $i = 0; $i < $logosCount; $i++ ) {
            if ( $i === 0 ) {
                // Smallest dppx
                // min-resolution is ">=" (larger than or equal to)
                // "not min-resolution" is essentially "<"
                $media_query = 'not all and (min-resolution: ' . $logos[1]['dppx'] . 'dppx)';
            } elseif ( $i !== $logosCount - 1 ) {
                // In between
                // Media query expressions can only apply "not" to the entire expression
                // (e.g. can't express ">= 1.5 and not >= 2).
                // Workaround: Use <= 1.9999 in place of < 2.
                $upper_bound = floatval( $logos[$i + 1]['dppx'] ) - 0.000001;
                $media_query = '(min-resolution: ' . $logos[$i]['dppx'] .
                    'dppx) and (max-resolution: ' . $upper_bound . 'dppx)';
            } else {
                // Largest dppx
                $media_query = '(min-resolution: ' . $logos[$i]['dppx'] . 'dppx)';
            }
 
            $preloadLinks[$logos[$i]['src']] = [
                'as' => 'image',
                'media' => $media_query
            ];
        }
 
        return $preloadLinks;
    }
 
    private function normalizeStyles( array &$styles ): void {
        foreach ( $styles as $key => $val ) {
            if ( !is_array( $val ) ) {
                $styles[$key] = [ $val ];
            }
        }
    }
 
    private static function getRelativeSizedLogo( array $logoElement ) {
        $width = $logoElement['width'];
        $height = $logoElement['height'];
        $widthRelative = $width / 16;
        $heightRelative = $height / 16;
        // Allow skins to scale the wordmark with browser font size (T207789)
        $logoElement['style'] = 'width: ' . $widthRelative . 'em; height: ' . $heightRelative . 'em;';
        return $logoElement;
    }
 
    public static function getAvailableLogos( Config $conf, string $lang = null ): array {
        $logos = $conf->get( MainConfigNames::Logos );
        if ( $logos === false ) {
            // no logos were defined... this will either
            // 1. Load from wgLogo
            // 2. Trigger runtime exception if those are not defined.
            $logos = [];
        }
        if ( $lang && isset( $logos['variants'][$lang] ) ) {
            foreach ( $logos['variants'][$lang] as $type => $value ) {
                $logos[$type] = $value;
            }
        }
 
        // If logos['1x'] is not defined, see if we can use wgLogo
        if ( !isset( $logos[ '1x' ] ) ) {
            $logo = $conf->get( MainConfigNames::Logo );
            if ( $logo ) {
                $logos['1x'] = $logo;
            }
        }
 
        if ( isset( $logos['wordmark'] ) ) {
            // Allow skins to scale the wordmark with browser font size (T207789)
            $logos['wordmark'] = self::getRelativeSizedLogo( $logos['wordmark'] );
        }
        if ( isset( $logos['tagline'] ) ) {
            $logos['tagline'] = self::getRelativeSizedLogo( $logos['tagline'] );
        }
 
        return $logos;
    }
 
    protected function getLogoData( Config $conf, string $lang = null ) {
        $logoHD = self::getAvailableLogos( $conf, $lang );
        $logo = $logoHD['1x'];
 
        $logo1Url = OutputPage::transformResourcePath( $conf, $logo );
 
        $logoUrls = [
            '1x' => $logo1Url,
        ];
 
        if ( isset( $logoHD['svg'] ) ) {
            $logoUrls['svg'] = OutputPage::transformResourcePath(
                $conf,
                $logoHD['svg']
            );
        } elseif ( isset( $logoHD['1.5x'] ) || isset( $logoHD['2x'] ) ) {
            // Only 1.5x and 2x are supported
            if ( isset( $logoHD['1.5x'] ) ) {
                $logoUrls['1.5x'] = OutputPage::transformResourcePath(
                    $conf,
                    $logoHD['1.5x']
                );
            }
            if ( isset( $logoHD['2x'] ) ) {
                $logoUrls['2x'] = OutputPage::transformResourcePath(
                    $conf,
                    $logoHD['2x']
                );
            }
        } else {
            // Return a string rather than a one-element array, getLogoPreloadlinks depends on this
            return $logo1Url;
        }
 
        return $logoUrls;
    }
 
    public function isKnownEmpty( Context $context ) {
        // Regardless of whether the files are specified, we always
        // provide mw-wiki-logo styles.
        return false;
    }
 
    protected function getLessVars( Context $context ) {
        $lessVars = parent::getLessVars( $context );
        $logos = self::getAvailableLogos( $this->getConfig() );
 
        if ( isset( $logos['wordmark'] ) ) {
            $logo = $logos['wordmark'];
            $lessVars[ 'logo-enabled' ] = true;
            $lessVars[ 'logo-wordmark-url' ] = CSSMin::buildUrlValue( $logo['src'] );
            $lessVars[ 'logo-wordmark-width' ] = intval( $logo['width'] );
            $lessVars[ 'logo-wordmark-height' ] = intval( $logo['height'] );
        } else {
            $lessVars[ 'logo-enabled' ] = false;
        }
        return $lessVars;
    }
 
    public function getDefinitionSummary( Context $context ) {
        $summary = parent::getDefinitionSummary( $context );
        $summary[] = [
            'logos' => self::getAvailableLogos( $this->getConfig() ),
        ];
        return $summary;
    }
}