TYPO3 13.4 API: GraphicalFunctions

GraphicalFunctions

Standard graphical functions

Class contains a bunch of cool functions for manipulating graphics with GDlib/Freetype and ImageMagick. VERY OFTEN used with gifbuilder that uses this class and provides a TypoScript API to using these functions

Properties

$addFrameSelection : bool: If set, the frame pointer is appended to the filenames.
$alternativeOutputKey : string: For debugging only.
$cmds : array{jpg: string, jpeg: string, gif: string, png: string, webp: string}
$dontCheckForExistingTempFile : bool: This flag should always be FALSE. If set TRUE, imageMagickConvert will always write a new file to the tempdir! Used for debugging.
$filenamePrefix : string: Filename prefix for images scaled in imageMagickConvert()
$IM_commands : array<int, array{0: string, 1: string}>: All ImageMagick commands executed is stored in this array for tracking. Used by the Install Tools Image section
$imageMagickConvert_forceFileNameBody : string: Forcing the output filename of imageMagickConvert() to this value. However after calling imageMagickConvert() it will be set blank again.
$scalecmd : non-empty-string: ImageMagick scaling command; "-auto-orient -geometry" or "-auto-orient -sample". Used in makeText() and imageMagickConvert()
$allowedColorSpaceNames : array<int, non-empty-string>: colorspace names allowed
$colorspace : non-empty-string: defines the RGB colorspace to use
$im5fx_blurSteps : non-empty-string: Used by v5_blur() to simulate 10 continuous steps of blurring
$im5fx_sharpenSteps : non-empty-string: Used by v5_sharpen() to simulate 10 continuous steps of sharpening.
$imageFileExt : array<int, non-empty-string>: Allowed file extensions perceived as images by TYPO3.
$jpegQuality : int<1, 100>
$mayScaleUp : bool
$pixelLimitGif : int<1, max>: This is the limit for the number of pixels in an image before it will be rendered as JPG instead of GIF/PNG
$processorEnabled : bool: Whether ImageMagick/GraphicsMagick is enabled or not
$webImageExt : array<int, non-empty-string>: Web image extensions (can be shown by a webbrowser)
$webpQuality : int<1, 101>

Methods

__construct() : mixed: Reads configuration information from $GLOBALS['TYPO3_CONF_VARS']['GFX'] and sets some values in internal variables.
combineExec() : string: Executes an ImageMagick "combine" (or composite in newer times) on four filenames - $input, $overlay and $mask as input files and $output as the output filename (written to) Can be used for many things, mostly scaling and effects.
convert() : ImageProcessingResult|null: A simple call to migrate a file to a different web-based file format. Let's say you want to convert a PDF to a PNG, use this method.
getImageDimensions() : ImageProcessingResult|array<string|int, mixed>|null: Gets the input image dimensions.
getImageFileExt() : array<string|int, mixed>
gif_or_jpg() : string: Returns an image extension for an output image based on the number of pixels of the output and the file extension of the original file.
imageMagickConvert() : array<string|int, mixed>|null: Converts $imagefile to another file in temp-dir of type $targetFileExtension.
imageMagickExec() : string: Executes an ImageMagick "convert" on two filenames, $input and $output using $params before them.
imageMagickIdentify() : array<string|int, mixed>|null: Call the identify command
isProcessingEnabled() : bool
mask() : mixed: This applies an image onto the $inputFile with an additional backgroundImage for the mask
randomName() : string: Returns a random filename prefixed with "temp_" and then 32 char md5 hash (without extension).
resize() : ImageProcessingResult|null: Converts $sourceFile to another file in temp-dir of type $targetFileExtension.
setImageFileExt() : void
v5_blur() : string: Returns the IM command for blurring with ImageMagick 5.
v5_sharpen() : string: Returns the IM command for sharpening with ImageMagick 5 Uses $this->im5fx_sharpenSteps for translation of the factor to an actual command.
webpSupportAvailable() : bool: convert -list format returns all formats, ideally with a line like this: "WEBP P rw- WebP Image Format (libwepb v1.3.2, ENCODER ABI 0x020F)" only if we have "rw" included, TYPO3 can fully support to read and write webp images.
executeIdentifyCommandForImageFile() : string|null: Internal function to execute an IM command fetching information on an image
getColorspaceFromConfiguration() : string: Returns the recommended colorspace for a processor or the one set in the configuration
modifyImageMagickStripProfileParameters() : string: Modifies the parameters for ImageMagick for stripping of profile information.

$addFrameSelection

If set, the frame pointer is appended to the filenames.


    public
        bool
    $addFrameSelection
     = true

$alternativeOutputKey

For debugging only.


    public
        string
    $alternativeOutputKey
     = ''

Filenames will not be based on mtime and only filename (not path) will be used. This key is also included in the hash of the filename...

$cmds


    public
        array{jpg: string, jpeg: string, gif: string, png: string, webp: string}
    $cmds
     = ['jpg' => '', 'jpeg' => '', 'gif' => '', 'png' => '', 'webp' => '']

$dontCheckForExistingTempFile

This flag should always be FALSE. If set TRUE, imageMagickConvert will always write a new file to the tempdir! Used for debugging.


    public
        bool
    $dontCheckForExistingTempFile
     = false

$filenamePrefix

Filename prefix for images scaled in imageMagickConvert()


    public
        string
    $filenamePrefix
     = ''

$IM_commands

All ImageMagick commands executed is stored in this array for tracking. Used by the Install Tools Image section


    public
        array<int, array{0: string, 1: string}>
    $IM_commands
     = []

$imageMagickConvert_forceFileNameBody

Forcing the output filename of imageMagickConvert() to this value. However after calling imageMagickConvert() it will be set blank again.


    public
        string
    $imageMagickConvert_forceFileNameBody
     = ''

$scalecmd

ImageMagick scaling command; "-auto-orient -geometry" or "-auto-orient -sample". Used in makeText() and imageMagickConvert()


    public
        non-empty-string
    $scalecmd
     = '-auto-orient -geometry'

$allowedColorSpaceNames

colorspace names allowed


    protected
        array<int, non-empty-string>
    $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']

$colorspace

defines the RGB colorspace to use


    protected
        non-empty-string
    $colorspace
     = 'RGB'

$im5fx_blurSteps

Used by v5_blur() to simulate 10 continuous steps of blurring


    protected
        non-empty-string
    $im5fx_blurSteps
     = '1x2,2x2,3x2,4x3,5x3,5x4,6x4,7x5,8x5,9x5'

$im5fx_sharpenSteps

Used by v5_sharpen() to simulate 10 continuous steps of sharpening.


    protected
        non-empty-string
    $im5fx_sharpenSteps
     = '1x2,2x2,3x2,2x3,3x3,4x3,3x4,4x4,4x5,5x5'

$imageFileExt

Allowed file extensions perceived as images by TYPO3.


    protected
        array<int, non-empty-string>
    $imageFileExt
     = ['gif', 'jpg', 'jpeg', 'png', 'tif', 'bmp', 'tga', 'pcx', 'ai', 'pdf', 'webp']

List should be set to gif,png,jpeg,jpg if IM is not available.

$jpegQuality


    protected
        int<1, 100>
    $jpegQuality
     = 85

$mayScaleUp


    protected
        bool
    $mayScaleUp
     = true

$pixelLimitGif

This is the limit for the number of pixels in an image before it will be rendered as JPG instead of GIF/PNG


    protected
        int<1, max>
    $pixelLimitGif
     = 10000

$processorEnabled

Whether ImageMagick/GraphicsMagick is enabled or not


    protected
        bool
    $processorEnabled

$webImageExt

Web image extensions (can be shown by a webbrowser)


    protected
        array<int, non-empty-string>
    $webImageExt
     = ['gif', 'jpg', 'jpeg', 'png', 'webp']

$webpQuality


    protected
        int<1, 101>
    $webpQuality
     = 85

__construct()

Reads configuration information from $GLOBALS['TYPO3_CONF_VARS']['GFX'] and sets some values in internal variables.


    public
                    __construct() : mixed

combineExec()

Executes an ImageMagick "combine" (or composite in newer times) on four filenames - $input, $overlay and $mask as input files and $output as the output filename (written to) Can be used for many things, mostly scaling and effects.


    public
                    combineExec(string $input, string $overlay, string $mask, string $output) : string

Parameters

$input : string: The relative to public web path image filepath, bottom file
$overlay : string: The relative to public web path image filepath, overlay file (top)
$mask : string: The relative to public web path image filepath, the mask file (grayscale)
$output : string: The relative to public web path image filepath, output filename (written to)

Return values

string

convert()

A simple call to migrate a file to a different web-based file format. Let's say you want to convert a PDF to a PNG, use this method.


    public
                    convert(string $sourceFile[, string $targetFileExtension = 'web' ]) : ImageProcessingResult|null

If you want to also resize it, try "resize" instead.

Parameters

$sourceFile : string
$targetFileExtension : string = 'web'

Return values

ImageProcessingResult|null

getImageDimensions()

Gets the input image dimensions.


    public
                    getImageDimensions(string $imageFile[, bool $useResultObject = false ]) : ImageProcessingResult|array<string|int, mixed>|null

Parameters

$imageFile : string: The absolute image filepath
$useResultObject : bool = false

Return values

ImageProcessingResult|array<string|int, mixed>|null —

Returns an array where [0]/[1] is w/h, [2] is extension and [3] is the absolute filepath.

getImageFileExt()


    public
                    getImageFileExt() : array<string|int, mixed>

Internal

Not part of TYPO3 Core API.

Return values

array<string|int, mixed>

gif_or_jpg()

Returns an image extension for an output image based on the number of pixels of the output and the file extension of the original file.


    public
                    gif_or_jpg(string $type, int $w, int $h) : string

For example: If the number of pixels exceeds $this->pixelLimitGif (normally 10000) then it will be a "jpg" string in return.

Parameters

$type : string: The file extension, lowercase.
$w : int: The width of the output image.
$h : int: The height of the output image.

Return values

string —

The filename, either "jpg" or "png"

imageMagickConvert()

Converts $imagefile to another file in temp-dir of type $targetFileExtension.


    public
                    imageMagickConvert(string $imagefile[, string $targetFileExtension = '' ][, string $w = '' ][, string $h = '' ][, string $params = '' ][, string $frame = '' ][, array<string|int, mixed> $options = [] ][, bool $mustCreate = false ]) : array<string|int, mixed>|null

Parameters

$imagefile : string: The absolute image filepath
$targetFileExtension : string = '': New image file extension. If $targetFileExtension is NOT set, the new imagefile will be of the original format. If set to = 'WEB' then one of the web-formats is applied.
$w : string = '': Width. $w / $h is optional. If only one is given the image is scaled proportionally. If an 'm' exists in the $w or $h and if both are present the $w and $h is regarded as the Maximum w/h and the proportions will be kept
$h : string = '': Height. See $w
$params : string = '': Additional ImageMagick parameters.
$frame : string = '': Refers to which frame-number to select in the image. '' or 0 will select the first frame, 1 will select the next and so on...
$options : array<string|int, mixed> = []: An array with options passed to getImageScale (see this function).
$mustCreate : bool = false: If set, then another image than the input imagefile MUST be returned. Otherwise, you can risk that the input image is good enough regarding measures etc and is of course not rendered to a new, temporary file in typo3temp/. But this option will force it to.

Return values

array<string|int, mixed>|null —

[0]/[1] is w/h, [2] is file extension and [3] is the filename.

imageMagickExec()

Executes an ImageMagick "convert" on two filenames, $input and $output using $params before them.


    public
                    imageMagickExec(string $input, string $output, string $params[, int $frame = 0 ]) : string

Can be used for many things, mostly scaling and effects.

Parameters

$input : string: The relative to public web path image filepath, input file (read from)
$output : string: The relative to public web path image filepath, output filename (written to)
$params : string: ImageMagick parameters
$frame : int = 0: Optional, refers to which frame-number to select in the image. '' or 0

Return values

string —

The result of a call to PHP function "exec()

imageMagickIdentify()

Call the identify command


    public
                    imageMagickIdentify(string $imagefile) : array<string|int, mixed>|null

Parameters

$imagefile : string: The relative to public web path image filepath

Return values

array<string|int, mixed>|null —

Returns an array where [0]/[1] is w/h, [2] is extension, [3] is the filename and [4] the real image type identified by ImageMagick.

isProcessingEnabled()


    public
                    isProcessingEnabled() : bool

Internal

Return values

bool

mask()

This applies an image onto the $inputFile with an additional backgroundImage for the mask


    public
                    mask(string $inputFile, string $outputFile, string $maskImage, string $maskBackgroundImage, string $params, array<string|int, mixed> $options) : mixed

Parameters

$inputFile : string
$outputFile : string
$maskImage : string
$maskBackgroundImage : string
$params : string
$options : array<string|int, mixed>

Internal

until API is finalized

randomName()

Returns a random filename prefixed with "temp_" and then 32 char md5 hash (without extension).


    public
                    randomName() : string

Used by functions in this class to create truly temporary files for the on-the-fly processing. These files will most likely be deleted right away.

Return values

string

resize()

Converts $sourceFile to another file in temp-dir of type $targetFileExtension.


    public
                    resize(string $sourceFile, string $targetFileExtension[, int|string $width = '' ][, int|string $height = '' ][, string $additionalParameters = '' ][, array<string|int, mixed> $options = [] ][, bool $forceCreation = false ]) : ImageProcessingResult|null

Parameters

$sourceFile : string: The absolute image filepath
$targetFileExtension : string: New extension, eg. "gif", "png", "jpg", "tif". If $targetFileExtension is NOT set, the new imagefile will be of the original format. If $targetFileExtension = 'WEB' then one of the web-formats is applied.
$width : int|string = '': Width. $width / $height is optional. If only one is given the image is scaled proportionally. If an 'm' exists in the $width or $height and if both are present the $width and $height is regarded as the Maximum w/h and the proportions will be kept
$height : int|string = '': Height. See $width
$additionalParameters : string = '': Additional ImageMagick parameters.
$options : array<string|int, mixed> = []: An array with options passed to getImageScale (see this function).
$forceCreation : bool = false: If set, then another image than the input imagefile MUST be returned. Otherwise you can risk that the input image is good enough regarding measures etc and is of course not rendered to a new, temporary file in typo3temp/. But this option will force it to.

Internal

until imageMagickConvert() is marked as deprecated.

Return values

ImageProcessingResult|null

setImageFileExt()


    public
                    setImageFileExt(array<string|int, mixed> $imageFileExt) : void

Parameters

$imageFileExt : array<string|int, mixed>

Internal

Only used for ext:install, not part of TYPO3 Core API.

v5_blur()

Returns the IM command for blurring with ImageMagick 5.


    public
                    v5_blur(int $factor) : string

Uses $this->im5fx_blurSteps for translation of the factor to an actual command.

Parameters

$factor : int: The blurring factor, 0-100 (effectively in 10 steps)

Return values

string —

The blurring command, e.g. " -blur 3x4"

v5_sharpen()

Returns the IM command for sharpening with ImageMagick 5 Uses $this->im5fx_sharpenSteps for translation of the factor to an actual command.


    public
                    v5_sharpen(int $factor) : string

Parameters

$factor : int: The sharpening factor, 0-100 (effectively in 10 steps)

Return values

string —

The sharpening command, eg. " -sharpen 3x4"

webpSupportAvailable()

convert -list format returns all formats, ideally with a line like this: "WEBP P rw- WebP Image Format (libwepb v1.3.2, ENCODER ABI 0x020F)" only if we have "rw" included, TYPO3 can fully support to read and write webp images.


    public
                    webpSupportAvailable() : bool

Internal

Return values

bool

executeIdentifyCommandForImageFile()

Internal function to execute an IM command fetching information on an image


    protected
                    executeIdentifyCommandForImageFile(string $imageFile) : string|null

Parameters

$imageFile : string: the absolute path to the image

Return values

string|null —

the raw result of the identify command.

getColorspaceFromConfiguration()

Returns the recommended colorspace for a processor or the one set in the configuration


    protected
                    getColorspaceFromConfiguration() : string

Return values

string

modifyImageMagickStripProfileParameters()

Modifies the parameters for ImageMagick for stripping of profile information.


    protected
                    modifyImageMagickStripProfileParameters(string $parameters, array<string|int, mixed> $options) : string

Strips profile information of image to save some space ideally

Parameters

$parameters : string: The parameters to be modified (if required)
$options : array<string|int, mixed>

Return values

string

GraphicalFunctions

Table of Contents

Properties

Methods

Properties

$addFrameSelection

$alternativeOutputKey

$cmds

$dontCheckForExistingTempFile

$filenamePrefix

$IM_commands

$imageMagickConvert_forceFileNameBody

$scalecmd

$allowedColorSpaceNames

$colorspace

$im5fx_blurSteps

$im5fx_sharpenSteps

$imageFileExt

$jpegQuality

$mayScaleUp

$pixelLimitGif

$processorEnabled

$webImageExt

$webpQuality

Methods

__construct()

combineExec()

Parameters

Return values

convert()

Parameters

Tags

Return values

getImageDimensions()

Parameters

Tags

Return values

getImageFileExt()

Return values

gif_or_jpg()

Parameters

Return values

imageMagickConvert()

Parameters

Tags

Return values

imageMagickExec()

Parameters

Return values

imageMagickIdentify()

Parameters

Return values

isProcessingEnabled()

Return values

mask()

Parameters

randomName()

Return values

resize()

Parameters

Tags

Return values

setImageFileExt()

Parameters

v5_blur()

Parameters

Tags

Return values

v5_sharpen()

Parameters

Tags

Return values

webpSupportAvailable()

Return values

executeIdentifyCommandForImageFile()

Parameters

Return values

getColorspaceFromConfiguration()

Return values

modifyImageMagickStripProfileParameters()