MediaHandler.php

Go to the documentation of this file.

<?php
use MediaWiki\MediaWikiServices;

abstract class MediaHandler {
    const TRANSFORM_LATER = 1;
    const METADATA_GOOD = true;
    const METADATA_BAD = false;
    const METADATA_COMPATIBLE = 2; // for old but backwards compatible.
    const MAX_ERR_LOG_SIZE = 65535;

    static function getHandler( $type ) {
        return MediaWikiServices::getInstance()
            ->getMediaHandlerFactory()->getHandler( $type );
    }

    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 );

    abstract function getImageSize( $image, $path );

    public function getMetadata( $image, $path ) {
        return '';
    }

    static function getMetadataVersion() {
        $version = [ '2' ]; // core metadata version
        Hooks::run( 'GetMetadataVersion', [ &$version ] );

        return implode( ';', $version );
    }

    function convertMetadataVersion( $metadata, $version = 1 ) {
        if ( !is_array( $metadata ) ) {
            // unserialize to keep return parameter consistent.
            Wikimedia\suppressWarnings();
            $ret = unserialize( $metadata );
            Wikimedia\restoreWarnings();

            return $ret;
        }

        return $metadata;
    }

    function getMetadataType( $image ) {
        return false;
    }

    public function isMetadataValid( $image, $metadata ) {
        return self::METADATA_GOOD;
    }

    public function getCommonMetaArray( File $file ) {
        return false;
    }

    function getScriptedTransform( $image, $script, $params ) {
        return false;
    }

    final function getTransform( $image, $dstPath, $dstUrl, $params ) {
        return $this->doTransform( $image, $dstPath, $dstUrl, $params, self::TRANSFORM_LATER );
    }

    abstract function doTransform( $image, $dstPath, $dstUrl, $params, $flags = 0 );

    public function getThumbType( $ext, $mime, $params = null ) {
        $magic = MediaWiki\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
            $extensions = $magic->getExtensionsForType( $mime );
            if ( $extensions ) {
                return [ strtok( $extensions, ' ' ), $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;
    }

    function isVectorized( $file ) {
        return false;
    }

    function isAnimatedImage( $file ) {
        return false;
    }

    function canAnimateThumbnail( $file ) {
        return true;
    }

    public function isEnabled() {
        return true;
    }

    public function getPageDimensions( File $image, $page ) {
        $gis = $this->getImageSize( $image, $image->getLocalRefPath() );
        if ( $gis ) {
            return [
                'width' => $gis[0],
                'height' => $gis[1]
            ];
        } else {
            return false;
        }
    }

    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;
    }

    function formatMetadataHelper( $metadataArray, $context = false ) {
        $result = [
            'visible' => [],
            'collapsed' => []
        ];

        $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 visibleMetadataFields() {
        return FormatMetadata::getVisibleFields();
    }

    protected static function addMeta( &$array, $visibility, $type, $id, $value, $param = false ) {
        $msg = wfMessage( "$type-$id", $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 . "\n" );
            $name = wfEscapeWikiText( $id );
        }
        $array[$visibility][] = [
            'id' => "$type-$id",
            'name' => $name,
            'value' => $value
        ];
    }

    function getShortDesc( $file ) {
        return self::getGeneralShortDesc( $file );
    }

    public function getLongDesc( $file ) {
        return self::getGeneralLongDesc( $file );
    }

    static function getGeneralShortDesc( $file ) {
        global $wgLang;

        return htmlspecialchars( $wgLang->formatSize( $file->getSize() ) );
    }

    static function getGeneralLongDesc( $file ) {
        return wfMessage( 'file-info' )->sizeParams( $file->getSize() )
            ->params( '<span class="mime-type">' . $file->getMimeType() . '</span>' )->parse();
    }

    public static function fitBoxWidth( $boxWidth, $boxHeight, $maxHeight ) {
        $idealWidth = $boxWidth * $maxHeight / $boxHeight;
        $roundedUp = ceil( $idealWidth );
        if ( round( $roundedUp * $boxHeight / $boxWidth ) > $maxHeight ) {
            return floor( $idealWidth );
        } else {
            return $roundedUp;
        }
    }

    function getDimensionsString( $file ) {
        return '';
    }

    function parserTransformHook( $parser, $file ) {
    }

    public function verifyUpload( $fileName ) {
        return Status::newGood();
    }

    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;
    }

    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
    }
}