MediaHandler.php

Go to the documentation of this file.

<?php
namespace MediaWiki\Media;
 
use InvalidArgumentException;
use MediaWiki\Context\IContextSource;
use MediaWiki\FileRepo\File\File;
use MediaWiki\FileRepo\File\LocalFile;
use MediaWiki\HookContainer\HookRunner;
use MediaWiki\Language\Language;
use MediaWiki\MediaWikiServices;
use MediaWiki\Parser\Parser;
use MediaWiki\Status\Status;
use ReflectionClass;
use ReflectionMethod;
use Wikimedia\FileBackend\FSFile\FSFile;
 
abstract class MediaHandler {
    public const TRANSFORM_LATER = 1;
    public const METADATA_GOOD = true;
    public const METADATA_BAD = false;
    public const METADATA_COMPATIBLE = 2; // for old but backwards compatible.
    private const MAX_ERR_LOG_SIZE = 65535;
 
    private ?Language $lang = null;
 
    public static function getHandler( $type, ?Language $lang = null ) {
        return MediaWikiServices::getInstance()
            ->getMediaHandlerFactory()->getHandler( $type, $lang );
    }
 
    public function getLanguage(): Language {
        if ( !$this->lang ) {
            throw new \RuntimeException( "Need to set language before accessing." );
        }
        return $this->lang;
    }
 
    public function setLanguage( Language $lang ): void {
        $this->lang = $lang;
    }
 
    abstract public function getParamMap();
 
    abstract public function validateParam( $name, $value );
 
    abstract public function makeParamString( $params );
 
    abstract public function parseParamString( $str );
 
    abstract public function normaliseParams( $image, &$params );
 
    public function getImageSize( $image, $path ) {
        return false;
    }
 
    public function getSizeAndMetadata( $state, $path ) {
        return null;
    }
 
    public function getMetadata( $image, $path ) {
        return '';
    }
 
    protected function useLegacyMetadata() {
        return $this->hasMostDerivedMethod( 'getMetadata' )
            || $this->hasMostDerivedMethod( 'getImageSize' );
    }
 
    protected function hasMostDerivedMethod( $name ) {
        $rc = new ReflectionClass( $this );
        $rm = new ReflectionMethod( $this, $name );
        return $rm->getDeclaringClass()->getName() === $rc->getName();
    }
 
    public function emitSubclassDeprecations() {
        if ( $this->hasMostDerivedMethod( 'getMetadata' ) ) {
            wfDeprecatedMsg(
                static::class . ' overrides MediaHandler::getMetadata, ' .
                'this was deprecated in MediaWiki 1.37',
                '1.37'
            );
        }
        if ( $this->hasMostDerivedMethod( 'getImageSize' ) ) {
            wfDeprecatedMsg(
                static::class . ' overrides MediaHandler::getImageSize, ' .
                'this was deprecated in MediaWiki 1.37',
                '1.37'
            );
        }
    }
 
    final public function getSizeAndMetadataWithFallback( $file, $path ) {
        if ( !$this->useLegacyMetadata() ) {
            if ( $file instanceof MediaHandlerState ) {
                $state = $file;
            } else {
                $state = new TrivialMediaHandlerState;
            }
            $info = $this->getSizeAndMetadata( $state, $path );
            if ( $info === false ) {
                return false;
            }
            if ( $info !== null ) {
                $info += [ 'width' => 0, 'height' => 0, 'metadata' => [] ];
                if ( !is_array( $info['metadata'] ) ) {
                    throw new InvalidArgumentException( 'Media handler ' .
                        static::class . ' returned ' . get_debug_type( $info['metadata'] ) .
                        ' for metadata, should be array' );
                }
                return $info;
            }
        }
 
        $blob = $this->getMetadata( $file, $path );
        // @phan-suppress-next-line PhanParamTooMany
        $size = $this->getImageSize(
            $file,
            $path,
            $blob // Secret TimedMediaHandler parameter
        );
        if ( $blob === false && $size === false ) {
            return false;
        }
        if ( $size ) {
            $info = [
                'width' => $size[0] ?? 0,
                'height' => $size[1] ?? 0
            ];
            if ( isset( $size['bits'] ) ) {
                $info['bits'] = $size['bits'];
            }
        } else {
            $info = [ 'width' => 0, 'height' => 0 ];
        }
        if ( $blob !== false ) {
            // phpcs:ignore Generic.PHP.NoSilencedErrors.Discouraged
            $metadata = @unserialize( $blob );
            if ( $metadata === false ) {
                // Unserialize error
                $metadata = [ '_error' => $blob ];
            } elseif ( !is_array( $metadata ) ) {
                $metadata = [];
            }
            $info['metadata'] = $metadata;
        } else {
            $info['metadata'] = [];
        }
        return $info;
    }
 
    public static function getMetadataVersion() {
        $version = [ '2' ]; // core metadata version
        ( new HookRunner( MediaWikiServices::getInstance()->getHookContainer() ) )->onGetMetadataVersion( $version );
 
        return implode( ';', $version );
    }
 
    public function convertMetadataVersion( $metadata, $version = 1 ) {
        return $metadata;
    }
 
    public function getMetadataType( $image ) {
        return false;
    }
 
    public function isMetadataValid( $image, $metadata ) {
        return self::METADATA_GOOD;
    }
 
    public function isFileMetadataValid( $image ) {
        return self::METADATA_GOOD;
    }
 
    public function getCommonMetaArray( File $file ) {
        return false;
    }
 
    public function getScriptedTransform( $image, $script, $params ) {
        return false;
    }
 
    final public function getTransform( $image, $dstPath, $dstUrl, $params ) {
        return $this->doTransform( $image, $dstPath, $dstUrl, $params, self::TRANSFORM_LATER );
    }
 
    abstract public function doTransform( $image, $dstPath, $dstUrl, $params, $flags = 0 );
 
    public function getThumbType( $ext, $mime, $params = null ) {
        $magic = MediaWikiServices::getInstance()->getMimeAnalyzer();
        if ( !$ext || $magic->isMatchingExtension( $ext, $mime ) === false ) {
            // The extension is not valid for this MIME type and we do
            // recognize the MIME type
            $knownExt = $magic->getExtensionFromMimeTypeOrNull( $mime );
            if ( $knownExt !== null ) {
                return [ $knownExt, $mime ];
            }
        }
 
        // The extension is correct (true) or the MIME type is unknown to
        // MediaWiki (null)
        return [ $ext, $mime ];
    }
 
    public function canRender( $file ) {
        return true;
    }
 
    public function mustRender( $file ) {
        return false;
    }
 
    public function isMultiPage( $file ) {
        return false;
    }
 
    public function pageCount( File $file ) {
        return false;
    }
 
    public function isVectorized( $file ) {
        return false;
    }
 
    public function isAnimatedImage( $file ) {
        return false;
    }
 
    public function canAnimateThumbnail( $file ) {
        return true;
    }
 
    public function isEnabled() {
        return true;
    }
 
    public function getPageDimensions( File $image, $page ) {
        return false;
    }
 
    public function getPageText( File $image, $page ) {
        return false;
    }
 
    public function getEntireText( File $file ) {
        $numPages = $file->pageCount();
        if ( !$numPages ) {
            // Not a multipage document
            return $this->getPageText( $file, 1 );
        }
        $document = '';
        for ( $i = 1; $i <= $numPages; $i++ ) {
            $curPage = $this->getPageText( $file, $i );
            if ( is_string( $curPage ) ) {
                $document .= $curPage . "\n";
            }
        }
        if ( $document !== '' ) {
            return $document;
        }
        return false;
    }
 
    public function formatMetadata( $image, $context = false ) {
        return false;
    }
 
    protected function formatMetadataHelper( $metadataArray, $context = false ) {
        $result = [
            'visible' => [],
            'collapsed' => []
        ];
 
        // Allow this MediaHandler to override formatting on certain values
        foreach ( $metadataArray as $tag => $vals ) {
            $v = $this->formatTag( $tag, $vals, $context );
            if ( $v === false ) {
                // Use default formatting
                continue;
            }
            if ( $v === null ) {
                // Remove this tag, don't format it for display
                unset( $metadataArray[$tag] );
            } else {
                // Allow subclass to override default formatting.
                $metadataArray[$tag] = [ '_formatted' => $v ];
                if ( isset( $v['_type'] ) ) {
                    $metadataArray[$tag]['_type'] = $v['_type'];
                    unset( $metadataArray[$tag]['_formatted']['_type'] );
                }
            }
        }
 
        $formatted = FormatMetadata::getFormattedData( $metadataArray, $context );
        // Sort fields into visible and collapsed
        $visibleFields = $this->visibleMetadataFields();
        foreach ( $formatted as $name => $value ) {
            $tag = strtolower( $name );
            self::addMeta( $result,
                in_array( $tag, $visibleFields ) ? 'visible' : 'collapsed',
                'exif',
                $tag,
                $value
            );
        }
 
        return $result;
    }
 
    protected function formatTag( string $key, $vals, $context = false ) {
        return false; // Use default formatting
    }
 
    protected function visibleMetadataFields() {
        return FormatMetadata::getVisibleFields();
    }
 
    protected static function addMeta( &$array, $visibility, $type, $id, $value, $param = false ) {
        $msg = wfMessage( "$type-$id", (string)$param );
        if ( $msg->exists() ) {
            $name = $msg->text();
        } else {
            // This is for future compatibility when using instant commons.
            // So as to not display as ugly a name if a new metadata
            // property is defined that we don't know about
            // (not a major issue since such a property would be collapsed
            // by default).
            wfDebug( __METHOD__ . ' Unknown metadata name: ' . $id );
            $name = wfEscapeWikiText( $id );
        }
        $array[$visibility][] = [
            'id' => "$type-$id",
            'name' => $name,
            'value' => $value
        ];
    }
 
    public function getShortDesc( $file ) {
        return self::getGeneralShortDesc( $file, $this->getLanguage() );
    }
 
    public function getLongDesc( $file ) {
        return self::getGeneralLongDesc( $file, $this->getLanguage() );
    }
 
    public static function getGeneralShortDesc( $file, Language $lang ) {
        return htmlspecialchars( $lang->formatSize( $file->getSize() ), ENT_QUOTES );
    }
 
    public static function getGeneralLongDesc( $file, Language $lang ) {
        return wfMessage( 'file-info' )
            ->sizeParams( $file->getSize() )
            ->params( '<span class="mime-type">' . $file->getMimeType() . '</span>' )
            ->inLanguage( $lang )
            ->parse();
    }
 
    public static function fitBoxWidth( $boxWidth, $boxHeight, $maxHeight ) {
        $idealWidth = $boxWidth * $maxHeight / $boxHeight;
        $roundedUp = ceil( $idealWidth );
        if ( round( $roundedUp * $boxHeight / $boxWidth ) > $maxHeight ) {
            return (int)floor( $idealWidth );
        }
        return (int)$roundedUp;
    }
 
    public function getDimensionsString( $file ) {
        return '';
    }
 
    public function parserTransformHook( $parser, $file ) {
    }
 
    public function verifyUpload( $fileName ) {
        return Status::newGood();
    }
 
    public function removeBadFile( $dstPath, $retval = 0 ) {
        if ( file_exists( $dstPath ) ) {
            $thumbstat = stat( $dstPath );
            if ( $thumbstat['size'] == 0 || $retval != 0 ) {
                $result = unlink( $dstPath );
 
                if ( $result ) {
                    wfDebugLog( 'thumbnail',
                        sprintf( 'Removing bad %d-byte thumbnail "%s". unlink() succeeded',
                            $thumbstat['size'], $dstPath ) );
                } else {
                    wfDebugLog( 'thumbnail',
                        sprintf( 'Removing bad %d-byte thumbnail "%s". unlink() failed',
                            $thumbstat['size'], $dstPath ) );
                }
 
                return true;
            }
        }
 
        return false;
    }
 
    public function filterThumbnailPurgeList( &$files, $options ) {
        // Do nothing
    }
 
    public function canRotate() {
        return false;
    }
 
    public function getRotation( $file ) {
        return 0;
    }
 
    public function getMirrored( $file ): string {
        return '';
    }
 
    protected function logErrorForExternalProcess( $retval, $err, $cmd ) {
        # Keep error output limited (T59985)
        $errMessage = trim( substr( $err, 0, self::MAX_ERR_LOG_SIZE ) );
 
        wfDebugLog( 'thumbnail',
            sprintf( 'thumbnail failed on %s: error %d "%s" from "%s"',
                    wfHostname(), $retval, $errMessage, $cmd ) );
    }
 
    public function getAvailableLanguages( File $file ) {
        return [];
    }
 
    public function getMatchedLanguage( $userPreferredLanguage, array $availableLanguages ) {
        return null;
    }
 
    public function getDefaultRenderLanguage( File $file ) {
        return null;
    }
 
    public function getLength( $file ) {
        return 0.0;
    }
 
    public function isExpensiveToThumbnail( $file ) {
        return false;
    }
 
    public function supportsBucketing() {
        return false;
    }
 
    public function sanitizeParamsForBucketing( $params ) {
        return $params;
    }
 
    public function getWarningConfig( $file ) {
        return null;
    }
 
    public static function getPageRangesByDimensions( $pagesByDimensions ) {
        $pageRangesByDimensions = [];
 
        foreach ( $pagesByDimensions as $dimensions => $pageList ) {
            $ranges = [];
            $firstPage = $pageList[0];
            $lastPage = $firstPage - 1;
 
            foreach ( $pageList as $page ) {
                if ( $page > $lastPage + 1 ) {
                    if ( $firstPage !== $lastPage ) {
                        $ranges[] = "$firstPage-$lastPage";
                    } else {
                        $ranges[] = "$firstPage";
                    }
 
                    $firstPage = $page;
                }
 
                $lastPage = $page;
            }
 
            if ( $firstPage != $lastPage ) {
                $ranges[] = "$firstPage-$lastPage";
            } else {
                $ranges[] = "$firstPage";
            }
 
            $pageRangesByDimensions[ $dimensions ] = $ranges;
        }
 
        $dimensionsString = [];
        foreach ( $pageRangesByDimensions as $dimensions => $pageRanges ) {
            $dimensionsString[] = "$dimensions:" . implode( ',', $pageRanges );
        }
 
        return implode( '/', $dimensionsString );
    }
 
    public function getContentHeaders( $metadata ) {
        return [ 'X-Content-Dimensions' => '' ]; // T175689
    }
 
    public function useSplitMetadata() {
        return false;
    }
}
 
class_alias( MediaHandler::class, 'MediaHandler' );