TransformationalImageHandler.php

Go to the documentation of this file.

<?php
namespace MediaWiki\Media;
 
use InvalidArgumentException;
use MediaWiki\FileRepo\File\File;
use MediaWiki\HookContainer\HookRunner;
use MediaWiki\MainConfigNames;
use MediaWiki\MediaWikiServices;
use MediaWiki\Shell\Shell;
 
abstract class TransformationalImageHandler extends ImageHandler {
    public function normaliseParams( $image, &$params ) {
        if ( !parent::normaliseParams( $image, $params ) ) {
            return false;
        }
 
        # Obtain the source, pre-rotation dimensions
        $srcWidth = $image->getWidth( $params['page'] );
        $srcHeight = $image->getHeight( $params['page'] );
 
        $params['physicalWidth'] = $this->getSteppedThumbWidth(
            $image, $params['physicalWidth'], $srcWidth, $srcHeight
        );
        $params['physicalHeight'] = File::scaleHeight( $srcWidth, $srcHeight, $params['physicalWidth'] );
 
        # Don't make an image bigger than the source
        if ( $params['physicalWidth'] >= $srcWidth ) {
            $params['physicalWidth'] = $srcWidth;
            $params['physicalHeight'] = $srcHeight;
 
            # Skip scaling limit checks if no scaling is required
            # due to requested size being bigger than source.
            if ( !$image->mustRender() ) {
                return true;
            }
        }
 
        return true;
    }
 
    public function extractPreRotationDimensions( $params, $rotation ) {
        if ( $rotation === 90 || $rotation === 270 ) {
            // We'll resize before rotation, so swap the dimensions again
            $width = $params['physicalHeight'];
            $height = $params['physicalWidth'];
        } else {
            $width = $params['physicalWidth'];
            $height = $params['physicalHeight'];
        }
 
        return [ $width, $height ];
    }
 
    public function doTransform( $image, $dstPath, $dstUrl, $params, $flags = 0 ) {
        if ( !$this->normaliseParams( $image, $params ) ) {
            return new TransformParameterError( $params );
        }
 
        // Create a parameter array to pass to the scaler
        $scalerParams = [
            // The size to which the image will be resized
            'physicalWidth' => $params['physicalWidth'],
            'physicalHeight' => $params['physicalHeight'],
            'physicalDimensions' => "{$params['physicalWidth']}x{$params['physicalHeight']}",
            // The size of the image on the page
            'clientWidth' => $params['width'],
            'clientHeight' => $params['height'],
            // Comment as will be added to the Exif of the thumbnail
            'comment' => isset( $params['descriptionUrl'] )
                ? "File source: {$params['descriptionUrl']}"
                : '',
            // Properties of the original image
            'srcWidth' => $image->getWidth(),
            'srcHeight' => $image->getHeight(),
            'mimeType' => $image->getMimeType(),
            'dstPath' => $dstPath,
            'dstUrl' => $dstUrl,
            'interlace' => $params['interlace'] ?? false,
        ];
 
        if ( isset( $params['quality'] ) && $params['quality'] === 'low' ) {
            $scalerParams['quality'] = 30;
        }
 
        // For subclasses that might be paged.
        if ( $image->isMultipage() && isset( $params['page'] ) ) {
            $scalerParams['page'] = (int)$params['page'];
        }
 
        # Determine scaler type
        $scaler = $this->getScalerType( $dstPath );
 
        if ( is_array( $scaler ) ) {
            $scalerName = get_class( $scaler[0] );
        } else {
            $scalerName = $scaler;
        }
 
        wfDebug( __METHOD__ . ": creating {$scalerParams['physicalDimensions']} " .
            "thumbnail of {$image->getPath()} at $dstPath using scaler $scalerName" );
 
        if ( !$image->mustRender() &&
            $scalerParams['physicalWidth'] == $scalerParams['srcWidth']
            && $scalerParams['physicalHeight'] == $scalerParams['srcHeight']
            && !isset( $scalerParams['quality'] )
        ) {
            # normaliseParams (or the user) wants us to return the unscaled image
            wfDebug( __METHOD__ . ": returning unscaled image" );
 
            return $this->getClientScalingThumbnailImage( $image, $params );
        }
 
        if ( $scaler === 'client' ) {
            # Client-side image scaling, use the source URL
            # Using the destination URL in a TRANSFORM_LATER request would be incorrect
            return $this->getClientScalingThumbnailImage( $image, $params );
        }
 
        if ( $image->isTransformedLocally() && !$this->isImageAreaOkForThumbnaling( $image, $params ) ) {
            $maxImageArea = MediaWikiServices::getInstance()->getMainConfig()->get( MainConfigNames::MaxImageArea );
            return new TransformTooBigImageAreaError( $params, $maxImageArea );
        }
 
        if ( $flags & self::TRANSFORM_LATER ) {
            wfDebug( __METHOD__ . ": Transforming later per flags." );
            return new ThumbnailImage( $image, $dstUrl, false, $params );
        }
 
        # Try to make a target path for the thumbnail
        if ( !wfMkdirParents( dirname( $dstPath ), null, __METHOD__ ) ) {
            wfDebug( __METHOD__ . ": Unable to create thumbnail destination " .
                "directory, falling back to client scaling" );
 
            return $this->getClientScalingThumbnailImage( $image, $params );
        }
 
        # Transform functions and binaries need a FS source file
        $thumbnailSource = $this->getThumbnailSource( $image, $params );
 
        // If the source isn't the original, disable EXIF rotation because it's already been applied
        if ( $scalerParams['srcWidth'] != $thumbnailSource['width']
            || $scalerParams['srcHeight'] != $thumbnailSource['height'] ) {
            $scalerParams['disableRotation'] = true;
        }
 
        $scalerParams['srcPath'] = $thumbnailSource['path'];
        $scalerParams['srcWidth'] = $thumbnailSource['width'];
        $scalerParams['srcHeight'] = $thumbnailSource['height'];
 
        if ( $scalerParams['srcPath'] === false ) { // Failed to get local copy
            wfDebugLog( 'thumbnail',
                sprintf( 'Thumbnail failed on %s: could not get local copy of "%s"',
                    wfHostname(), $image->getName() ) );
 
            return new MediaTransformError( 'thumbnail_error',
                $scalerParams['clientWidth'], $scalerParams['clientHeight'],
                wfMessage( 'filemissing' )
            );
        }
 
        // Try a hook. Called "Bitmap" for historical reasons.
        $mto = null;
        ( new HookRunner( MediaWikiServices::getInstance()->getHookContainer() ) )
            ->onBitmapHandlerTransform( $this, $image, $scalerParams, $mto );
        if ( $mto !== null ) {
            wfDebug( __METHOD__ . ": Hook to BitmapHandlerTransform created an mto" );
            $scaler = 'hookaborted';
        }
 
        // $scaler will return a MediaTransformError on failure, or false on success.
        // If the scaler is successful, it will have created a thumbnail at the destination
        // path.
        if ( is_array( $scaler ) && is_callable( $scaler ) ) {
            // Allow subclasses to specify their own rendering methods.
            $err = $scaler( $image, $scalerParams );
        } else {
            switch ( $scaler ) {
                case 'hookaborted':
                    # Handled by the hook above
                    $err = $mto->isError() ? $mto : false;
                    break;
                case 'im':
                    $err = $this->transformImageMagick( $image, $scalerParams );
                    break;
                case 'custom':
                    $err = $this->transformCustom( $image, $scalerParams );
                    break;
                case 'imext':
                    $err = $this->transformImageMagickExt( $image, $scalerParams );
                    break;
                case 'gd':
                default:
                    $err = $this->transformGd( $image, $scalerParams );
                    break;
            }
        }
 
        // Remove the file if a zero-byte thumbnail was created, or if there was an error
        // @phan-suppress-next-line PhanTypeMismatchArgument Relaying on bool/int conversion to cast objects correct
        $removed = $this->removeBadFile( $dstPath, (bool)$err );
        if ( $err ) {
            // transform returned MediaTransformError
            return $err;
        }
 
        if ( $removed ) {
            // Thumbnail was zero-byte and had to be removed
            return new MediaTransformError( 'thumbnail_error',
                $scalerParams['clientWidth'], $scalerParams['clientHeight'],
                wfMessage( 'unknown-error' )
            );
        }
 
        if ( $mto ) {
            // @phan-suppress-next-line PhanTypeMismatchReturnSuperType
            return $mto;
        }
 
        return new ThumbnailImage( $image, $dstUrl, $dstPath, $params );
    }
 
    protected function getThumbnailSource( $file, $params ) {
        return $file->getThumbnailSource( $params );
    }
 
    abstract protected function getScalerType( $dstPath, $checkDstPath = true );
 
    protected function getClientScalingThumbnailImage( $image, $params ) {
        $url = $image->modifyClientThumbUrl( $image->getUrl(), $params );
        return new ThumbnailImage( $image, $url, null, $params );
    }
 
    protected function transformImageMagick( $image, $params ) {
        return $this->getMediaTransformError( $params, "Unimplemented" );
    }
 
    protected function transformImageMagickExt( $image, $params ) {
        return $this->getMediaTransformError( $params, "Unimplemented" );
    }
 
    protected function transformCustom( $image, $params ) {
        return $this->getMediaTransformError( $params, "Unimplemented" );
    }
 
    public function getMediaTransformError( $params, $errMsg ) {
        return new MediaTransformError( 'thumbnail_error', $params['clientWidth'],
            $params['clientHeight'], $errMsg );
    }
 
    protected function transformGd( $image, $params ) {
        return $this->getMediaTransformError( $params, "Unimplemented" );
    }
 
    protected function escapeMagickProperty( $s ) {
        // Double the backslashes
        $s = str_replace( '\\', '\\\\', $s );
        // Double the percents
        $s = str_replace( '%', '%%', $s );
        // Escape initial - or @
        if ( strlen( $s ) > 0 && ( $s[0] === '-' || $s[0] === '@' ) ) {
            $s = '\\' . $s;
        }
 
        return $s;
    }
 
    protected function escapeMagickInput( $path, $scene = false ) {
        # Die on initial metacharacters (caller should prepend path)
        $firstChar = substr( $path, 0, 1 );
        if ( $firstChar === '~' || $firstChar === '@' ) {
            throw new InvalidArgumentException( __METHOD__ . ': cannot escape this path name' );
        }
 
        # Escape glob chars
        $path = preg_replace( '/[*?\[\]{}]/', '\\\\\0', $path );
 
        return $this->escapeMagickPath( $path, $scene );
    }
 
    protected function escapeMagickOutput( $path, $scene = false ) {
        $path = str_replace( '%', '%%', $path );
 
        return $this->escapeMagickPath( $path, $scene );
    }
 
    protected function escapeMagickPath( $path, $scene = false ) {
        # Die on format specifiers (other than drive letters). The regex is
        # meant to match all the formats you get from "convert -list format"
        if ( preg_match( '/^([a-zA-Z0-9-]+):/', $path, $m ) ) {
            if ( wfIsWindows() && is_dir( $m[0] ) ) {
                // OK, it's a drive letter
                // ImageMagick has a similar exception, see IsMagickConflict()
            } else {
                throw new InvalidArgumentException( __METHOD__ . ': unexpected colon character in path name' );
            }
        }
 
        # If there are square brackets, add a do-nothing scene specification
        # to force a literal interpretation
        if ( $scene === false ) {
            if ( str_contains( $path, '[' ) ) {
                $path .= '[0--1]';
            }
        } else {
            $path .= "[$scene]";
        }
 
        return $path;
    }
 
    protected function getMagickVersion() {
        $cache = MediaWikiServices::getInstance()->getLocalServerObjectCache();
        $method = __METHOD__;
        return $cache->getWithSetCallback(
            $cache->makeGlobalKey( 'imagemagick-version' ),
            $cache::TTL_HOUR,
            static function () use ( $method ) {
                $imageMagickConvertCommand = MediaWikiServices::getInstance()
                    ->getMainConfig()->get( MainConfigNames::ImageMagickConvertCommand );
 
                wfDebug( $method . ": Running convert -version" );
                $return = Shell::command( $imageMagickConvertCommand, '-version' )
                    ->includeStderr()
                    ->execute()
                    ->getStdout() ?? '';
                $x = preg_match(
                    '/Version: ImageMagick ([0-9]*\.[0-9]*\.[0-9]*)/', $return, $matches
                );
                if ( $x != 1 ) {
                    wfDebug( $method . ": ImageMagick version check failed" );
                    return false;
                }
 
                return $matches[1];
            }
        );
    }
 
    public function canRotate() {
        return false;
    }
 
    public function autoRotateEnabled() {
        return false;
    }
 
    public function rotate( $file, $params ) {
        return new MediaTransformError( 'thumbnail_error', 0, 0,
            static::class . ' rotation not implemented' );
    }
 
    public function mustRender( $file ) {
        return $this->canRotate() && $this->getRotation( $file ) != 0;
    }
 
    public function isImageAreaOkForThumbnaling( $file, &$params ) {
        $maxImageArea = MediaWikiServices::getInstance()->getMainConfig()->get( MainConfigNames::MaxImageArea );
 
        # For historical reasons, hook starts with BitmapHandler
        $checkImageAreaHookResult = null;
        ( new HookRunner( MediaWikiServices::getInstance()->getHookContainer() ) )->onBitmapHandlerCheckImageArea(
            $file, $params, $checkImageAreaHookResult );
 
        if ( $checkImageAreaHookResult !== null ) {
            // was set by hook, so return that value
            return (bool)$checkImageAreaHookResult;
        }
 
        if ( $maxImageArea === false ) {
            // Checking is disabled, fine to thumbnail
            return true;
        }
 
        $srcWidth = $file->getWidth( $params['page'] );
        $srcHeight = $file->getHeight( $params['page'] );
 
        if ( $srcWidth * $srcHeight > $maxImageArea
            && !( $file->getMimeType() === 'image/jpeg'
                && $this->getScalerType( null, false ) === 'im' )
        ) {
            # Only ImageMagick can efficiently downsize jpg images without loading
            # the entire file in memory
            return false;
        }
        return true;
    }
}
 
class_alias( TransformationalImageHandler::class, 'TransformationalImageHandler' );