ImageModule.php

Go to the documentation of this file.

<?php
namespace MediaWiki\ResourceLoader;
 
use DomainException;
use InvalidArgumentException;
use Wikimedia\Minify\CSSMin;
 
class ImageModule extends Module {
    private $useMaskImage;
    protected $definition;
 
    protected $localBasePath = '';
 
    protected $origin = self::ORIGIN_CORE_SITEWIDE;
 
    protected $imageObjects = null;
    protected $images = [];
    protected $defaultColor = null;
    protected $useDataURI = true;
    protected $globalVariants = null;
    protected $variants = [];
    protected $prefix = null;
    protected $selectorWithoutVariant = '.{prefix}-{name}';
    protected $selectorWithVariant = '.{prefix}-{name}-{variant}';
 
    public function __construct( array $options = [], $localBasePath = null ) {
        $this->useMaskImage = $options['useMaskImage'] ?? false;
        $this->localBasePath = static::extractLocalBasePath( $options, $localBasePath );
 
        $this->definition = $options;
    }
 
    protected function loadFromDefinition() {
        if ( $this->definition === null ) {
            return;
        }
 
        $options = $this->definition;
        $this->definition = null;
 
        if ( isset( $options['data'] ) ) {
            $dataPath = $this->getLocalPath( $options['data'] );
            $data = json_decode( file_get_contents( $dataPath ), true );
            $options = array_merge( $data, $options );
        }
 
        // Accepted combinations:
        // * prefix
        // * selector
        // * selectorWithoutVariant + selectorWithVariant
        // * prefix + selector
        // * prefix + selectorWithoutVariant + selectorWithVariant
 
        $prefix = isset( $options['prefix'] ) && $options['prefix'];
        $selector = isset( $options['selector'] ) && $options['selector'];
        $selectorWithoutVariant = isset( $options['selectorWithoutVariant'] )
            && $options['selectorWithoutVariant'];
        $selectorWithVariant = isset( $options['selectorWithVariant'] )
            && $options['selectorWithVariant'];
 
        if ( $selectorWithoutVariant && !$selectorWithVariant ) {
            throw new InvalidArgumentException(
                "Given 'selectorWithoutVariant' but no 'selectorWithVariant'."
            );
        }
        if ( $selectorWithVariant && !$selectorWithoutVariant ) {
            throw new InvalidArgumentException(
                "Given 'selectorWithVariant' but no 'selectorWithoutVariant'."
            );
        }
        if ( $selector && $selectorWithVariant ) {
            throw new InvalidArgumentException(
                "Incompatible 'selector' and 'selectorWithVariant'+'selectorWithoutVariant' given."
            );
        }
        if ( !$prefix && !$selector && !$selectorWithVariant ) {
            throw new InvalidArgumentException(
                "None of 'prefix', 'selector' or 'selectorWithVariant'+'selectorWithoutVariant' given."
            );
        }
 
        foreach ( $options as $member => $option ) {
            switch ( $member ) {
                case 'images':
                case 'variants':
                    if ( !is_array( $option ) ) {
                        throw new InvalidArgumentException(
                            "Invalid list error. '$option' given, array expected."
                        );
                    }
                    if ( !isset( $option['default'] ) ) {
                        // Backwards compatibility
                        $option = [ 'default' => $option ];
                    }
                    foreach ( $option as $data ) {
                        if ( !is_array( $data ) ) {
                            throw new InvalidArgumentException(
                                "Invalid list error. '$data' given, array expected."
                            );
                        }
                    }
                    $this->{$member} = $option;
                    break;
 
                case 'useDataURI':
                    $this->{$member} = (bool)$option;
                    break;
                case 'defaultColor':
                case 'prefix':
                case 'selectorWithoutVariant':
                case 'selectorWithVariant':
                    $this->{$member} = (string)$option;
                    break;
 
                case 'selector':
                    $this->selectorWithoutVariant = $this->selectorWithVariant = (string)$option;
            }
        }
    }
 
    public function getPrefix() {
        $this->loadFromDefinition();
        return $this->prefix;
    }
 
    public function getSelectors() {
        $this->loadFromDefinition();
        return [
            'selectorWithoutVariant' => $this->selectorWithoutVariant,
            'selectorWithVariant' => $this->selectorWithVariant,
        ];
    }
 
    public function getImage( $name, Context $context ): ?Image {
        $this->loadFromDefinition();
        $images = $this->getImages( $context );
        return $images[$name] ?? null;
    }
 
    public function getImages( Context $context ): array {
        $skin = $context->getSkin();
        if ( $this->imageObjects === null ) {
            $this->loadFromDefinition();
            $this->imageObjects = [];
        }
        if ( !isset( $this->imageObjects[$skin] ) ) {
            $this->imageObjects[$skin] = [];
            if ( !isset( $this->images[$skin] ) ) {
                $this->images[$skin] = $this->images['default'] ?? [];
            }
            foreach ( $this->images[$skin] as $name => $options ) {
                $fileDescriptor = is_array( $options ) ? $options['file'] : $options;
 
                $allowedVariants = array_merge(
                    ( is_array( $options ) && isset( $options['variants'] ) ) ? $options['variants'] : [],
                    $this->getGlobalVariants( $context )
                );
                if ( isset( $this->variants[$skin] ) ) {
                    $variantConfig = array_intersect_key(
                        $this->variants[$skin],
                        array_fill_keys( $allowedVariants, true )
                    );
                } else {
                    $variantConfig = [];
                }
 
                $image = new Image(
                    $name,
                    $this->getName(),
                    $fileDescriptor,
                    $this->localBasePath,
                    $variantConfig,
                    $this->defaultColor
                );
                $this->imageObjects[$skin][$image->getName()] = $image;
            }
        }
 
        return $this->imageObjects[$skin];
    }
 
    public function getGlobalVariants( Context $context ): array {
        $skin = $context->getSkin();
        if ( $this->globalVariants === null ) {
            $this->loadFromDefinition();
            $this->globalVariants = [];
        }
        if ( !isset( $this->globalVariants[$skin] ) ) {
            $this->globalVariants[$skin] = [];
            if ( !isset( $this->variants[$skin] ) ) {
                $this->variants[$skin] = $this->variants['default'] ?? [];
            }
            foreach ( $this->variants[$skin] as $name => $config ) {
                if ( $config['global'] ?? false ) {
                    $this->globalVariants[$skin][] = $name;
                }
            }
        }
 
        return $this->globalVariants[$skin];
    }
 
    public function getStyles( Context $context ): array {
        $this->loadFromDefinition();
 
        // Build CSS rules
        $rules = [];
 
        $sources = $oldSources = $context->getResourceLoader()->getSources();
        $this->getHookRunner()->onResourceLoaderModifyEmbeddedSourceUrls( $sources );
        if ( array_keys( $sources ) !== array_keys( $oldSources ) ) {
            throw new DomainException( 'ResourceLoaderModifyEmbeddedSourceUrls hook must not add or remove sources' );
        }
        $script = $sources[ $this->getSource() ];
 
        $selectors = $this->getSelectors();
 
        foreach ( $this->getImages( $context ) as $name => $image ) {
            $declarations = $this->getStyleDeclarations( $context, $image, $script );
            $selector = strtr(
                $selectors['selectorWithoutVariant'],
                [
                    '{prefix}' => $this->getPrefix(),
                    '{name}' => $name,
                    '{variant}' => '',
                ]
            );
            $rules[] = "$selector {\n\t$declarations\n}";
 
            foreach ( $image->getVariants() as $variant ) {
                $declarations = $this->getStyleDeclarations( $context, $image, $script, $variant );
                $selector = strtr(
                    $selectors['selectorWithVariant'],
                    [
                        '{prefix}' => $this->getPrefix(),
                        '{name}' => $name,
                        '{variant}' => $variant,
                    ]
                );
                $rules[] = "$selector {\n\t$declarations\n}";
            }
        }
 
        $style = implode( "\n", $rules );
 
        return [ 'all' => $style ];
    }
 
    private function getStyleDeclarations(
        Context $context,
        Image $image,
        $script,
        $variant = null
    ) {
        $imageDataUri = $this->useDataURI ? $image->getDataUri( $context, $variant, 'original' ) : false;
        $primaryUrl = $imageDataUri ?: $image->getUrl( $context, $script, $variant, 'original' );
        $declarations = $this->getCssDeclarations(
            $primaryUrl
        );
        return implode( "\n\t", $declarations );
    }
 
    protected function getCssDeclarations( $primary ): array {
        $primaryUrl = CSSMin::buildUrlValue( $primary );
        if ( $this->supportsMaskImage() ) {
            return [
                "-webkit-mask-image: $primaryUrl;",
                "mask-image: $primaryUrl;",
            ];
        }
        return [
            "background-image: $primaryUrl;",
        ];
    }
 
    public function supportsMaskImage() {
        return $this->useMaskImage;
    }
 
    public function supportsURLLoading() {
        return false;
    }
 
    public function getDefinitionSummary( Context $context ) {
        $this->loadFromDefinition();
        $summary = parent::getDefinitionSummary( $context );
 
        $options = [];
        foreach ( [
            'localBasePath',
            'images',
            'variants',
            'prefix',
            'selectorWithoutVariant',
            'selectorWithVariant',
        ] as $member ) {
            $options[$member] = $this->{$member};
        }
 
        $summary[] = [
            'options' => $options,
            'fileHashes' => $this->getFileHashes( $context ),
        ];
        return $summary;
    }
 
    private function getFileHashes( Context $context ) {
        $this->loadFromDefinition();
        $files = [];
        foreach ( $this->getImages( $context ) as $image ) {
            $files[] = $image->getPath( $context );
        }
        $files = array_values( array_unique( $files ) );
        return array_map( [ __CLASS__, 'safeFileHash' ], $files );
    }
 
    protected function getLocalPath( $path ) {
        if ( $path instanceof FilePath ) {
            return $path->getLocalPath();
        }
 
        return "{$this->localBasePath}/$path";
    }
 
    public static function extractLocalBasePath( array $options, $localBasePath = null ) {
        global $IP;
 
        if ( array_key_exists( 'localBasePath', $options ) ) {
            $localBasePath = (string)$options['localBasePath'];
        }
 
        return $localBasePath ?? $IP;
    }
 
    public function getType() {
        return self::LOAD_STYLES;
    }
}