GraphicalFunctions.php

Go to the documentation of this file.

<?php
 
/*
 * This file is part of the TYPO3 CMS project.
 *
 * It is free software; you can redistribute it and/or modify it under
 * the terms of the GNU General Public License, either version 2
 * of the License, or any later version.
 *
 * For the full copyright and license information, please read the
 * LICENSE.txt file that was distributed with this source code.
 *
 * The TYPO3 project - inspiring people to share!
 */
 
namespace ‪TYPO3\CMS\Core\Imaging;
 
use ‪TYPO3\CMS\Core\Core\Environment;
use TYPO3\CMS\Core\Type\File\ImageInfo;
use ‪TYPO3\CMS\Core\Utility\CommandUtility;
use ‪TYPO3\CMS\Core\Utility\GeneralUtility;
use ‪TYPO3\CMS\Core\Utility\MathUtility;
use ‪TYPO3\CMS\Core\Utility\PathUtility;
use ‪TYPO3\CMS\Core\Utility\StringUtility;
 
class GraphicalFunctions
{
    public $addFrameSelection = true;
 
    protected string $colorspace = 'RGB';
 
    protected array $allowedColorSpaceNames = [
        'CMY',
        'CMYK',
        'Gray',
        'HCL',
        'HSB',
        'HSL',
        'HWB',
        'Lab',
        'LCH',
        'LMS',
        'Log',
        'Luv',
        'OHTA',
        'Rec601Luma',
        'Rec601YCbCr',
        'Rec709Luma',
        'Rec709YCbCr',
        'RGB',
        'sRGB',
        'Transparent',
        'XYZ',
        'YCbCr',
        'YCC',
        'YIQ',
        'YCbCr',
        'YUV',
    ];
 
    protected array $imageFileExt = ['gif', 'jpg', 'jpeg', 'png', 'tif', 'bmp', 'tga', 'pcx', 'ai', 'pdf', 'webp'];
 
    protected array $webImageExt = ['gif', 'jpg', 'jpeg', 'png', 'webp'];
 
    public array $cmds = [
        'jpg' => '',
        'jpeg' => '',
        'gif' => '',
        'png' => '',
        'webp' => '',
    ];
 
    protected bool $processorEnabled;
    protected bool $mayScaleUp = true;
 
    public $filenamePrefix = '';
 
    public $imageMagickConvert_forceFileNameBody = '';
 
    public $dontCheckForExistingTempFile = false;
 
    public $alternativeOutputKey = '';
 
    public $IM_commands = [];
 
    public $scalecmd = '-auto-orient -geometry';
 
    protected string $im5fx_blurSteps = '1x2,2x2,3x2,4x3,5x3,5x4,6x4,7x5,8x5,9x5';
 
    protected string $im5fx_sharpenSteps = '1x2,2x2,3x2,2x3,3x3,4x3,3x4,4x4,4x5,5x5';
 
    protected int $pixelLimitGif = 10000;
 
    protected int $jpegQuality = 85;
 
    protected int $webpQuality = 85;
 
    public function __construct()
    {
        $gfxConf = ‪$GLOBALS['TYPO3_CONF_VARS']['GFX'];
        $this->colorspace = $this->getColorspaceFromConfiguration();
 
        $this->processorEnabled = (bool)$gfxConf['processor_enabled'];
        $this->jpegQuality = ‪MathUtility::forceIntegerInRange($gfxConf['jpg_quality'], 1, 100, 85);
        if (isset($gfxConf['webp_quality'])) {
            if ($gfxConf['webp_quality'] === 'lossless') {
                $this->webpQuality = 101;
            } else {
                $this->webpQuality = ‪MathUtility::forceIntegerInRange($gfxConf['webp_quality'], 1, 101, $this->webpQuality);
            }
        }
        $this->addFrameSelection = (bool)$gfxConf['processor_allowFrameSelection'];
        $this->imageFileExt = ‪GeneralUtility::trimExplode(',', $gfxConf['imagefile_ext']);
 
        // Processor Effects. This is necessary if using ImageMagick 5+.
        // Effects in Imagemagick 5+ tends to render very slowly!
        // Therefore, must be disabled in order not to perform sharpen, blurring and such.
        // but if 'processor_effects' is set, enable effects
        if ($gfxConf['processor_effects']) {
            $this->cmds['jpg'] = $this->v5_sharpen(10);
            $this->cmds['jpeg'] = $this->v5_sharpen(10);
        }
        // Secures that images are not scaled up.
        $this->mayScaleUp = (bool)$gfxConf['processor_allowUpscaling'];
    }
 
    public function v5_sharpen($factor)
    {
        $factor = ‪MathUtility::forceIntegerInRange((int)ceil($factor / 10), 0, 10);
        $sharpenArr = explode(',', ',' . $this->im5fx_sharpenSteps);
        $sharpenF = trim($sharpenArr[$factor]);
        if ($sharpenF) {
            return ' -sharpen ' . $sharpenF;
        }
        return '';
    }
 
    public function v5_blur($factor)
    {
        $factor = ‪MathUtility::forceIntegerInRange((int)ceil($factor / 10), 0, 10);
        $blurArr = explode(',', ',' . $this->im5fx_blurSteps);
        $blurF = trim($blurArr[$factor]);
        if ($blurF) {
            return ' -blur ' . $blurF;
        }
        return '';
    }
 
    public function randomName()
    {
        ‪GeneralUtility::mkdir_deep(‪Environment::getVarPath() . '/transient/');
        return ‪Environment::getVarPath() . '/transient/' . md5(‪StringUtility::getUniqueId());
    }
 
    /***********************************
     *
     * Scaling, Dimensions of images
     *
     ***********************************/
 
    public function convert(string $sourceFile, string $targetFileExtension = 'web'): ?ImageProcessingResult
    {
        return $this->resize($sourceFile, $targetFileExtension);
    }
 
    public function resize(string $sourceFile, string $targetFileExtension, int|string $width = '', int|string $height = '', string $additionalParameters = '', array $options = [], bool $forceCreation = false): ?ImageProcessingResult
    {
        if (!$this->processorEnabled) {
            // Returning file info right away
            return $this->getImageDimensions($sourceFile, true);
        }
        $info = $this->getImageDimensions($sourceFile, true);
        if (!$info) {
            return null;
        }
        $originalFileExtension = $info->getExtension();
 
        // Determine the final target file extension
        $targetFileExtension = strtolower(trim($targetFileExtension));
        // If no extension is given the original extension is used
        $targetFileExtension = $targetFileExtension ?: $originalFileExtension;
        if ($targetFileExtension === 'web') {
            if (in_array($originalFileExtension, $this->webImageExt, true)) {
                $targetFileExtension = $originalFileExtension;
            } else {
                $targetFileExtension = $this->gif_or_jpg($originalFileExtension, $info->getWidth(), $info->getHeight());
            }
        }
        if (!in_array($targetFileExtension, $this->imageFileExt, true)) {
            return null;
        }
        // Clean up additional $params
        $additionalParameters = trim($additionalParameters);
        // Refers to which frame-number to select in the image. null or 0 will select the first frame, 1 will select the next and so on...
        $frame = $this->addFrameSelection && isset($options['frame']) ? (int)$options['frame'] : 0;
 
        $processingInstructions = ImageProcessingInstructions::fromCropScaleValues($info->getWidth(), $info->getHeight(), $width, $height, $options);
 
        $originalWidth = $info->getWidth() ?: $width;
        $originalHeight = $info->getHeight() ?: $height;
 
        // Check if conversion should be performed ($noScale - no processing needed).
        // $noScale flag is TRUE if the width / height does NOT dictate the image to be scaled. That is if no
        // width / height is given or if the destination w/h matches the original image dimensions, or if
        // the option to not scale the image is set.
        $noScale = !$originalWidth && !$originalHeight || $processingInstructions->width === $info->getWidth() && $processingInstructions->height === $info->getHeight() || !empty($options['noScale']);
        if ($noScale && !$processingInstructions->cropArea && !$additionalParameters && !$frame && $targetFileExtension === $info->getExtension() && !$forceCreation) {
            // Set the new width and height before returning,
            // if the noScale option is set, otherwise the incoming
            // values are calculated.
            if (!empty($options['noScale'])) {
                return new ImageProcessingResult(
                    $sourceFile,
                    $processingInstructions->width,
                    $processingInstructions->height
                );
            }
            return $info;
        }
 
        $command = '';
        if ($processingInstructions->cropArea) {
            $cropArea = $processingInstructions->cropArea;
            $command .= ' -crop ' . $cropArea->getWidth() . 'x' . $cropArea->getHeight() . '+' . $cropArea->getOffsetLeft() . '+' . $cropArea->getOffsetTop() . '! +repage ';
        }
 
        // Start with the default scale command
        // check if we should use -sample or -geometry
        if ($options['sample'] ?? false) {
            $command .= '-auto-orient -sample';
        } else {
            $command .= $this->scalecmd;
        }
        // from the IM docs -- https://imagemagick.org/script/command-line-processing.php
        // "We see that ImageMagick is very good about preserving aspect ratios of images, to prevent distortion
        // of your favorite photos and images. But you might really want the dimensions to be 100x200, thereby
        // stretching the image. In this case just tell ImageMagick you really mean it (!) by appending an exclamation
        // operator to the geometry. This will force the image size to exactly what you specify.
        // So, for example, if you specify 100x200! the dimensions will become exactly 100x200"
        $command .= ' ' . $processingInstructions->width . 'x' . $processingInstructions->height . '!';
        // Add params
        $additionalParameters = $this->modifyImageMagickStripProfileParameters($additionalParameters, $options);
        $command .= ($additionalParameters ? ' ' . $additionalParameters : $this->cmds[$targetFileExtension] ?? '');
 
        // Add quality parameter for jpg, jpeg or webp if not already set
        if (!str_contains($command, '-quality') && ($targetFileExtension === 'jpg' || $targetFileExtension === 'jpeg')) {
            $command .= ' -quality ' . $this->jpegQuality;
        }
        // Add quality parameter for webp if not already set
        if ($targetFileExtension === 'webp') {
            if (!str_contains($command, '-quality') && !str_contains($command, 'webp:lossless')) {
                if ($this->webpQuality === 101) {
                    $command .= ' -define webp:lossless=true';
                } else {
                    $command .= ' -quality ' . $this->webpQuality;
                }
            }
        }
        // re-apply colorspace-setting for the resulting image so colors don't appear to dark (sRGB instead of RGB)
        if (!str_contains($command, '-colorspace')) {
            $command .= ' -colorspace ' . CommandUtility::escapeShellArgument($this->colorspace);
        }
        if ($this->alternativeOutputKey) {
            $theOutputName = md5($command . $processingInstructions->cropArea . ‪PathUtility::basename($sourceFile) . $this->alternativeOutputKey . '[' . $frame . ']');
        } else {
            $theOutputName = md5($command . $processingInstructions->cropArea . $sourceFile . filemtime($sourceFile) . '[' . $frame . ']');
        }
        if ($this->imageMagickConvert_forceFileNameBody) {
            $theOutputName = $this->imageMagickConvert_forceFileNameBody;
            $this->imageMagickConvert_forceFileNameBody = '';
        }
        // Making the temporary filename
        ‪GeneralUtility::mkdir_deep(‪Environment::getPublicPath() . '/typo3temp/assets/images/');
        ‪$output = ‪Environment::getPublicPath() . '/typo3temp/assets/images/' . $this->filenamePrefix . $theOutputName . '.' . $targetFileExtension;
        if ($this->dontCheckForExistingTempFile || !file_exists(‪$output)) {
            $this->imageMagickExec($sourceFile, ‪$output, $command, $frame);
        }
        if (file_exists(‪$output)) {
            // params might change some image data, so this should be calculated again
            if ($additionalParameters) {
                return $this->getImageDimensions(‪$output, true);
            }
            return new ImageProcessingResult(‪$output, $processingInstructions->width, $processingInstructions->height);
        }
        return null;
    }
 
    public function imageMagickConvert($imagefile, $targetFileExtension = '', $w = '', $h = '', $params = '', $frame = '', $options = [], $mustCreate = false)
    {
        if ($frame !== '') {
            $options['frame'] = (int)$frame;
        }
        $result = $this->resize($imagefile, $targetFileExtension, $w, $h, $params, $options, $mustCreate);
        return $result?->toLegacyArray();
    }
 
    public function mask(string $inputFile, string $outputFile, string $maskImage, string $maskBackgroundImage, string $params, array $options)
    {
        $params = $this->modifyImageMagickStripProfileParameters($params, $options);
        $tmpStr = $this->randomName();
        //  m_mask
        $intermediateMaskFile = $tmpStr . '_mask.png';
        $this->imageMagickExec($maskImage, $intermediateMaskFile, $params);
        //  m_bgImg
        $intermediateMaskBackgroundFile = $tmpStr . '_bgImg.miff';
        $this->imageMagickExec($maskBackgroundImage, $intermediateMaskBackgroundFile, $params);
        // The image onto the background
        $this->combineExec($intermediateMaskBackgroundFile, $inputFile, $intermediateMaskFile, $outputFile);
        // Unlink the temp-images...
        @unlink($intermediateMaskFile);
        @unlink($intermediateMaskBackgroundFile);
    }
 
    public function getImageDimensions(string $imageFile, bool $useResultObject = false): ImageProcessingResult|array|null
    {
        preg_match('/([^\\.]*)$/', $imageFile, $reg);
        if (!file_exists($imageFile)) {
            return null;
        }
        // @todo: check if we actually need this, ass ImageInfo deals with this much more professionally
        if (!in_array(strtolower($reg[0]), $this->imageFileExt, true)) {
            return null;
        }
        $imageInfoObject = GeneralUtility::makeInstance(ImageInfo::class, $imageFile);
        if ($imageInfoObject->isFile() && $imageInfoObject->getWidth()) {
            $result = ImageProcessingResult::createFromImageInfo($imageInfoObject);
            return $useResultObject ? $result : $result->toLegacyArray();
        }
        return null;
    }
 
    /***********************************
     *
     * ImageMagick API functions
     *
     ***********************************/
    public function imageMagickIdentify($imagefile)
    {
        if (!$this->processorEnabled) {
            return null;
        }
 
        $result = $this->executeIdentifyCommandForImageFile($imagefile);
        if ($result) {
            [$width, $height, $fileExtension, $fileType] = explode(' ', $result);
            if ((int)$width && (int)$height) {
                return [$width, $height, strtolower($fileExtension), $imagefile, strtolower($fileType)];
            }
        }
        return null;
    }
 
    protected function executeIdentifyCommandForImageFile(string $imageFile): ?string
    {
        $frame = $this->addFrameSelection ? 0 : null;
        $cmd = ‪CommandUtility::imageMagickCommand(
            'identify',
            '-format "%w %h %e %m" ' . ‪ImageMagickFile::fromFilePath($imageFile, $frame)
        );
        $returnVal = [];
        ‪CommandUtility::exec($cmd, $returnVal);
        $result = array_pop($returnVal);
        $this->IM_commands[] = ['identify', $cmd, $result];
        return $result;
    }
 
    public function imageMagickExec($input, ‪$output, $params, $frame = 0)
    {
        if (!$this->processorEnabled) {
            return '';
        }
        // If addFrameSelection is set in the Install Tool, a frame number is added to
        // select a specific page of the image (by default this will be the first page)
        $frame = $this->addFrameSelection ? (int)$frame : null;
        $cmd = ‪CommandUtility::imageMagickCommand(
            'convert',
            $params
                . ' ' . ‪ImageMagickFile::fromFilePath($input, $frame)
                . ' ' . CommandUtility::escapeShellArgument(‪$output)
        );
        $this->IM_commands[] = [‪$output, $cmd];
        $ret = ‪CommandUtility::exec($cmd);
        // Change the permissions of the file
        ‪GeneralUtility::fixPermissions(‪$output);
        return $ret;
    }
 
    public function combineExec($input, $overlay, $mask, ‪$output)
    {
        if (!$this->processorEnabled) {
            return '';
        }
        $theMask = $this->randomName() . '.png';
        // +matte = no alpha layer in output
        $this->imageMagickExec($mask, $theMask, '-colorspace GRAY +matte');
 
        $parameters = '-compose over'
            . ' -quality ' . $this->jpegQuality
            . ' +matte '
            . ‪ImageMagickFile::fromFilePath($input) . ' '
            . ‪ImageMagickFile::fromFilePath($overlay) . ' '
            . ‪ImageMagickFile::fromFilePath($theMask) . ' '
            . CommandUtility::escapeShellArgument(‪$output);
        $cmd = ‪CommandUtility::imageMagickCommand('combine', $parameters);
        $this->IM_commands[] = [‪$output, $cmd];
        $ret = ‪CommandUtility::exec($cmd);
        // Change the permissions of the file
        ‪GeneralUtility::fixPermissions(‪$output);
        if (is_file($theMask)) {
            @unlink($theMask);
        }
        return $ret;
    }
 
    protected function modifyImageMagickStripProfileParameters(string $parameters, array $options): string
    {
        if (!isset($options['stripProfile'])) {
            return $parameters;
        }
 
        $gfxConf = ‪$GLOBALS['TYPO3_CONF_VARS']['GFX'] ?? [];
        // Use legacy processor_stripColorProfileCommand setting if defined, otherwise
        // use the preferred configuration option processor_stripColorProfileParameters
        $stripColorProfileCommand = $gfxConf['processor_stripColorProfileCommand'] ??
            implode(' ', array_map(CommandUtility::escapeShellArgument(...), $gfxConf['processor_stripColorProfileParameters'] ?? []));
        if ($options['stripProfile'] && $stripColorProfileCommand !== '') {
            return $stripColorProfileCommand . ' ' . $parameters;
        }
 
        return $parameters . '###SkipStripProfile###';
    }
 
    /***********************************
     *
     * Various IO functions
     *
     ***********************************/
 
    public function gif_or_jpg($type, $w, $h)
    {
        if ($type === 'ai' || $w * $h < $this->pixelLimitGif) {
            return 'png';
        }
        return 'jpg';
    }
 
    public function isProcessingEnabled(): bool
    {
        return $this->processorEnabled;
    }
 
    public function webpSupportAvailable(): bool
    {
        $cmd = ‪CommandUtility::imageMagickCommand('convert', '-list format');
        ‪CommandUtility::exec($cmd, ‪$output);
        $this->IM_commands[] = ['', $cmd];
        foreach (‪$output as $outputLine) {
            $outputLine = trim($outputLine);
            if (str_starts_with($outputLine, 'WEBP') && str_contains($outputLine, ' rw')) {
                return true;
            }
        }
        return false;
    }
 
    public function setImageFileExt(array $imageFileExt): void
    {
        $this->imageFileExt = $imageFileExt;
    }
 
    public function getImageFileExt(): array
    {
        return $this->imageFileExt;
    }
 
    protected function getColorspaceFromConfiguration(): string
    {
        $gfxConf = ‪$GLOBALS['TYPO3_CONF_VARS']['GFX'];
 
        if ($gfxConf['processor'] === 'ImageMagick' && $gfxConf['processor_colorspace'] === '') {
            return 'sRGB';
        }
 
        if ($gfxConf['processor'] === 'GraphicsMagick' && $gfxConf['processor_colorspace'] === '') {
            return 'RGB';
        }
 
        return in_array($gfxConf['processor_colorspace'], $this->allowedColorSpaceNames, true) ? $gfxConf['processor_colorspace'] : $this->colorspace;
    }
}