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
Table of Contents
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.
Properties
$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
Methods
__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
stringconvert()
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'
Tags
Return values
ImageProcessingResult|nullgetImageDimensions()
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
Tags
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>
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.
Tags
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
Return values
boolmask()
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>
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
stringresize()
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.
until imageMagickConvert() is marked as deprecated.
Tags
Return values
ImageProcessingResult|nullsetImageFileExt()
public
setImageFileExt(array<string|int, mixed> $imageFileExt) : void
Parameters
- $imageFileExt : array<string|int, mixed>
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)
Tags
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)
Tags
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
Return values
boolexecuteIdentifyCommandForImageFile()
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
stringmodifyImageMagickStripProfileParameters()
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>