#107290Add an API-Feature to \TYPO3\CMS\Core\Resource\Processing\LocalCropScaleMaskHelper
Description
Hi
The LocalCropScaleMaskHelper class contains a lot of smart logic that I’d like to use in my extension.
Unfortunately, I’m missing one small detail in LocalCropScaleMaskHelper. It uses the GraphicalFunctions#resize(…) method but doesn’t utilize the last parameter: $forceCreation. Normally that’s fine, but in my case it’s not, because my extension always needs a result, not just sometimes.
That’s why I extended the helper and LocalImageProcessor. My LocalImageProcessor now uses a subclassed helper that copies and slightly adjusts the most comprehensive method from the original class.
However, this isn’t elegant in the long run, because I always have to keep an eye on the original helper.
So here’s my proposal: (An optional constructor parameter controls $forceCreation)
<?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\Resource\Processing;
use TYPO3\CMS\Core\Core\Environment;
use TYPO3\CMS\Core\Imaging\GraphicalFunctions;
use TYPO3\CMS\Core\Imaging\ImageProcessingInstructions;
use TYPO3\CMS\Core\Resource\FileInterface;
use TYPO3\CMS\Core\Utility\GeneralUtility;
/**
* Helper class to locally perform a crop/scale/mask task with the TYPO3 image processing classes.
*/
class LocalCropScaleMaskHelper
{
public function __construct(private readonly bool $forceCreation = false)
{
}
/**
* This method actually does the processing of files locally
*
* Takes the original file (for remote storages this will be fetched from the remote server),
* does the IM magic on the local server by creating a temporary typo3temp/ file,
* copies the typo3temp/ file to the processing folder of the target storage and
* removes the typo3temp/ file.
*
* The returned array has the following structure:
* width => 100
* height => 200
* filePath => /some/path
*
* If filePath isn't set but width and height are the original file is used as ProcessedFile
* with the returned width and height. This is for example useful for SVG images.
*
* @param TaskInterface $task
* @return array|null
*/
public function process(TaskInterface $task)
{
return $this->processWithLocalFile($task, $task->getSourceFile()->getForLocalProcessing(false));
}
/**
* Does the heavy lifting prescribed in processTask()
* except that the processing can be performed on any given local image
*/
public function processWithLocalFile(TaskInterface $task, string $originalFileName): ?array
{
$result = null;
$targetFile = $task->getTargetFile();
$targetFileExtension = $task->getTargetFileExtension();
$imageOperations = GeneralUtility::makeInstance(GraphicalFunctions::class);
$configuration = $targetFile->getProcessingConfiguration();
$configuration['additionalParameters'] ??= '';
// Normal situation (no masking) - just scale the image
if (!is_array($configuration['maskImages'] ?? null)) {
// the result info is an array with 0=width,1=height,2=extension,3=filename
$result = $imageOperations->resize(
$originalFileName,
$targetFileExtension,
$configuration['width'] ?? '',
$configuration['height'] ?? '',
$configuration['additionalParameters'],
$configuration,
$this->forceCreation
);
} else {
$temporaryFileName = $this->getFilenameForImageCropScaleMask($task);
$maskImage = $configuration['maskImages']['maskImage'] ?? null;
$maskBackgroundImage = $configuration['maskImages']['backgroundImage'];
if ($maskImage instanceof FileInterface && $maskBackgroundImage instanceof FileInterface) {
// This converts the original image to a temporary PNG file during all steps of the masking process
$tempFileInfo = $imageOperations->resize(
$originalFileName,
'png',
$configuration['width'] ?? '',
$configuration['height'] ?? '',
$configuration['additionalParameters'],
$configuration,
$this->forceCreation
);
if ($tempFileInfo !== null) {
// Scaling
$command = '-geometry ' . $tempFileInfo->getWidth() . 'x' . $tempFileInfo->getHeight() . '!';
$imageOperations->mask(
$tempFileInfo->getRealPath(),
$temporaryFileName,
$maskImage->getForLocalProcessing(),
$maskBackgroundImage->getForLocalProcessing(),
$command,
$configuration
);
$maskBottomImage = $configuration['maskImages']['maskBottomImage'] ?? null;
$maskBottomImageMask = $configuration['maskImages']['maskBottomImageMask'] ?? null;
if ($maskBottomImage instanceof FileInterface && $maskBottomImageMask instanceof FileInterface) {
// Uses the temporary PNG file from the previous step and applies another mask
$imageOperations->mask(
$temporaryFileName,
$temporaryFileName,
$maskBottomImage->getForLocalProcessing(),
$maskBottomImageMask->getForLocalProcessing(),
$command,
$configuration
);
}
}
$result = $tempFileInfo;
}
}
// check if the processing really generated a new file (scaled and/or cropped)
if ($result !== null) {
// The file processing yielded a different file extension than we anticipated. Most likely because
// the processing service found out a file type needed to use fallback storage. In this case, we
// append the actually received file extension to our file to be stored, which will also hint at
// a failed conversion, like some-file.avif.jpg. Otherwise use the same file extension. This is
// evaluated for persistence in @see LocalImageProcessor->processTaskWithLocalFile().
$remapProcessedTargetFileExtension = ($targetFileExtension !== $result->getExtension())
// Remap to correct image type extension.
? $result->getExtension()
// No file extension remap required.
: null;
// @todo: realpath handling should be revisited, they may produce issues
// with open_basedir restrictions and/or lockRootPath.
if ($result->getRealPath() !== realpath($originalFileName)) {
$result = [
'width' => $result->getWidth(),
'height' => $result->getHeight(),
'filePath' => $result->getRealPath(),
'remapProcessedTargetFileExtension' => $remapProcessedTargetFileExtension,
];
} else {
// No file was generated
$result = null;
}
}
// If noScale option is applied, we need to reset the width and height to ensure the scaled values
// are used for the generated image tag even if the image itself is not scaled. This is needed, as
// the result is discarded due to the fact that the original image is used.
// @see https://forge.typo3.org/issues/100972
// Note: This should only happen if no image has been generated ($result === null).
if ($result === null && ($configuration['noScale'] ?? false)) {
$configuration = $task->getConfiguration();
$localProcessedFile = $task->getSourceFile()->getForLocalProcessing(false);
$imageDimensions = $imageOperations->getImageDimensions($localProcessedFile, true);
$imageScaleInfo = ImageProcessingInstructions::fromCropScaleValues(
$imageDimensions->getWidth(),
$imageDimensions->getHeight(),
$configuration['width'] ?? '',
$configuration['height'] ?? '',
$configuration
);
$targetFile->updateProperties([
'width' => $imageScaleInfo->width,
'height' => $imageScaleInfo->height,
]);
}
return $result;
}
/**
* Returns the filename for a cropped/scaled/masked file which will be put in typo3temp for the time being.
*/
protected function getFilenameForImageCropScaleMask(TaskInterface $task): string
{
$targetFileExtension = $task->getTargetFileExtension();
return Environment::getPublicPath() . '/typo3temp/' . $task->getTargetFile()->generateProcessedFileNameWithoutExtension() . '.' . ltrim(trim($targetFileExtension), '.');
}
}Reviews 5
- main 90428[TASK] LocalCropScaleMaskHelper can optionally always create images
- main 90780[FEATURE] Enhance BeforeFileProcessingEvent for force-resizing an image
- main 90779[TASK] LocalCropScaleMaskHelper can optionally always create images
- main 90462[POC][TASK] Make LocalCropScaleMaskHelper aware of "forceCreation"
- main 90455[TASK] LocalCropScaleMaskHelper can optionally always create images
History 755
Show 530 earlier messages
-
Garvin Hicking commented and changed status
NewNeeds Feedback <span data-processor="relativetime" data-value="2025-08-14T20:16:07+00:00" > 08/14/25, 20:16 </span> -
C. Gogolin commented <span data-processor="relativetime" data-value="2025-08-15T18:15:11+00:00" > 08/15/25, 18:15 </span>
Garvin Hicking wrote in #note-1:
> Hi!
>
> Thanks for contributing! Would you like to propose this as a patch on gerrit (review.typo3.org, see contribution guide on https://docs.typo3.org/core-contribution)? That would make code review and voting and testing easier. :)Can you help me?
git push origin HEAD:refs/for/main
docmcfly@review.typo3.org: Permission denied (publickey).
fatal: Konnte nicht vom Remote-Repository lesen.Bitte stellen Sie sicher, dass die korrekten Zugriffsberechtigungen bestehen
und das Repository existiert. -
Garvin Hicking commented <span data-processor="relativetime" data-value="2025-08-15T19:28:19+00:00" > 08/15/25, 19:28 </span>
Hey, sure. Are you on slack? Send me a DM (supergarv).
Did you upload your public key in the Gerrit (review.typo3.org) interface? The contrib guide should have a screenshot.
-
C. Gogolin commented <span data-processor="relativetime" data-value="2025-08-16T13:49:13+00:00" > 08/16/25, 13:49 </span>
I just signed into Slack and now remember why I wanted to leave it.
Sending a message to supergarv doesn’t seem possible—I’d have to invite you somehow, and that requires an email address… <— OMG, that’s annoying.
Yes, I uploaded my public key to Gerrit and it’s shown as valid. To be safe, I adjusted the config:
Host review.typo3.org HostName review.typo3.org User docmcfly Port 22 IdentityFile /home/clemens/.ssh/keys/typo3 Compression yesBut still:
$ ssh review.typo3.org docmcfly@review.typo3.org: Permission denied (publickey).Is it really this complicated to submit a change request to Typo3?
-
Garvin Hicking commented <span data-processor="relativetime" data-value="2025-08-16T18:12:45+00:00" > 08/16/25, 18:12 </span>
Did you login to the typo3 slack (https://typo3.org/community/meet/chat-slack)?! If you’re in there you don’t need any invitations to send DMs.
In that DM you can send me screenshots of your gerrit UI that shows the public key. Which key type did you use? Try ed25519.?
Also, your username is the username you use on my.typo3.org right?
Also, please be patient. After all I’m trying to help here. :-)
You can also send a github PR that will get converted to gerrit. This way you will probably not get feedback on gerrit and submitting changes to a patch will not be possible.
-
Gerrit Code Review pushed patch set 1 for main to change 90428 status
Needs FeedbackUnder Review <span data-processor="relativetime" data-value="2025-08-17T15:58:28+00:00" > 08/17/25, 15:58 </span> -
Gerrit Code Review pushed patch set 2 for main to change 90428 <span data-processor="relativetime" data-value="2025-08-19T10:07:14+00:00" > 08/19/25, 10:07 </span>
-
Gerrit Code Review pushed patch set 1 for main to change 90455 <span data-processor="relativetime" data-value="2025-08-19T10:26:04+00:00" > 08/19/25, 10:26 </span>
-
Gerrit Code Review pushed patch set 3 for main to change 90428 <span data-processor="relativetime" data-value="2025-08-19T15:24:06+00:00" > 08/19/25, 15:24 </span>
-
Gerrit Code Review pushed patch set 2 for main to change 90455 <span data-processor="relativetime" data-value="2025-08-19T15:24:07+00:00" > 08/19/25, 15:24 </span>
-
Gerrit Code Review pushed patch set 4 for main to change 90428 <span data-processor="relativetime" data-value="2025-08-20T06:55:03+00:00" > 08/20/25, 06:55 </span>
-
Gerrit Code Review pushed patch set 5 for main to change 90428 <span data-processor="relativetime" data-value="2025-08-20T06:56:03+00:00" > 08/20/25, 06:56 </span>
-
Gerrit Code Review pushed patch set 6 for main to change 90428 <span data-processor="relativetime" data-value="2025-08-20T07:06:22+00:00" > 08/20/25, 07:06 </span>
-
Gerrit Code Review pushed patch set 7 for main to change 90428 <span data-processor="relativetime" data-value="2025-08-20T07:26:45+00:00" > 08/20/25, 07:26 </span>
-
Gerrit Code Review pushed patch set 8 for main to change 90428 <span data-processor="relativetime" data-value="2025-08-20T07:50:59+00:00" > 08/20/25, 07:50 </span>
-
Gerrit Code Review pushed patch set 9 for main to change 90428 <span data-processor="relativetime" data-value="2025-08-20T08:17:46+00:00" > 08/20/25, 08:17 </span>
-
Gerrit Code Review pushed patch set 10 for main to change 90428 <span data-processor="relativetime" data-value="2025-08-22T08:18:07+00:00" > 08/22/25, 08:18 </span>
-
Gerrit Code Review pushed patch set 11 for main to change 90428 <span data-processor="relativetime" data-value="2025-08-22T19:34:21+00:00" > 08/22/25, 19:34 </span>
-
Gerrit Code Review pushed patch set 12 for main to change 90428 <span data-processor="relativetime" data-value="2025-08-23T11:16:19+00:00" > 08/23/25, 11:16 </span>
-
Gerrit Code Review pushed patch set 13 for main to change 90428 <span data-processor="relativetime" data-value="2025-08-23T15:05:19+00:00" > 08/23/25, 15:05 </span>
-
Gerrit Code Review pushed patch set 14 for main to change 90428 <span data-processor="relativetime" data-value="2025-08-23T15:12:26+00:00" > 08/23/25, 15:12 </span>
-
Gerrit Code Review pushed patch set 15 for main to change 90428 <span data-processor="relativetime" data-value="2025-08-23T15:15:54+00:00" > 08/23/25, 15:15 </span>
-
Gerrit Code Review pushed patch set 16 for main to change 90428 <span data-processor="relativetime" data-value="2025-08-23T15:32:03+00:00" > 08/23/25, 15:32 </span>
-
Gerrit Code Review pushed patch set 17 for main to change 90428 <span data-processor="relativetime" data-value="2025-08-23T15:47:38+00:00" > 08/23/25, 15:47 </span>
-
Gerrit Code Review pushed patch set 18 for main to change 90428 <span data-processor="relativetime" data-value="2025-08-24T19:30:19+00:00" > 08/24/25, 19:30 </span>
-
Gerrit Code Review pushed patch set 19 for main to change 90428 <span data-processor="relativetime" data-value="2025-08-24T19:30:42+00:00" > 08/24/25, 19:30 </span>
-
Gerrit Code Review pushed patch set 20 for main to change 90428 <span data-processor="relativetime" data-value="2025-08-29T19:12:27+00:00" > 08/29/25, 19:12 </span>
-
Gerrit Code Review pushed patch set 21 for main to change 90428 <span data-processor="relativetime" data-value="2025-08-31T14:21:32+00:00" > 08/31/25, 14:21 </span>
-
Gerrit Code Review pushed patch set 22 for main to change 90428 <span data-processor="relativetime" data-value="2025-08-31T15:21:17+00:00" > 08/31/25, 15:21 </span>
-
Gerrit Code Review pushed patch set 23 for main to change 90428 <span data-processor="relativetime" data-value="2025-08-31T15:32:19+00:00" > 08/31/25, 15:32 </span>
-
Gerrit Code Review pushed patch set 24 for main to change 90428 <span data-processor="relativetime" data-value="2025-08-31T15:46:55+00:00" > 08/31/25, 15:46 </span>
-
Gerrit Code Review pushed patch set 25 for main to change 90428 <span data-processor="relativetime" data-value="2025-08-31T18:28:14+00:00" > 08/31/25, 18:28 </span>
-
Gerrit Code Review pushed patch set 26 for main to change 90428 <span data-processor="relativetime" data-value="2025-08-31T18:57:18+00:00" > 08/31/25, 18:57 </span>
-
Gerrit Code Review pushed patch set 27 for main to change 90428 <span data-processor="relativetime" data-value="2025-08-31T19:00:01+00:00" > 08/31/25, 19:00 </span>
-
Gerrit Code Review pushed patch set 28 for main to change 90428 <span data-processor="relativetime" data-value="2025-09-14T14:55:56+00:00" > 09/14/25, 14:55 </span>
-
Gerrit Code Review pushed patch set 29 for main to change 90428 <span data-processor="relativetime" data-value="2025-09-14T15:37:34+00:00" > 09/14/25, 15:37 </span>
-
Gerrit Code Review pushed patch set 30 for main to change 90428 <span data-processor="relativetime" data-value="2025-09-21T06:54:48+00:00" > 09/21/25, 06:54 </span>
-
Gerrit Code Review pushed patch set 31 for main to change 90428 <span data-processor="relativetime" data-value="2025-09-21T11:13:21+00:00" > 09/21/25, 11:13 </span>
-
Gerrit Code Review pushed patch set 32 for main to change 90428 <span data-processor="relativetime" data-value="2025-09-21T15:07:48+00:00" > 09/21/25, 15:07 </span>
-
Gerrit Code Review pushed patch set 33 for main to change 90428 <span data-processor="relativetime" data-value="2025-09-21T16:55:05+00:00" > 09/21/25, 16:55 </span>
-
Gerrit Code Review pushed patch set 34 for main to change 90428 <span data-processor="relativetime" data-value="2025-09-21T16:56:58+00:00" > 09/21/25, 16:56 </span>
-
Gerrit Code Review pushed patch set 35 for main to change 90428 <span data-processor="relativetime" data-value="2025-09-21T17:11:49+00:00" > 09/21/25, 17:11 </span>
-
Gerrit Code Review pushed patch set 36 for main to change 90428 <span data-processor="relativetime" data-value="2025-09-21T17:24:42+00:00" > 09/21/25, 17:24 </span>
-
Gerrit Code Review pushed patch set 37 for main to change 90428 <span data-processor="relativetime" data-value="2025-09-22T17:38:10+00:00" > 09/22/25, 17:38 </span>
-
Gerrit Code Review pushed patch set 38 for main to change 90428 <span data-processor="relativetime" data-value="2025-09-22T18:01:57+00:00" > 09/22/25, 18:01 </span>
-
Gerrit Code Review pushed patch set 39 for main to change 90428 <span data-processor="relativetime" data-value="2025-09-22T18:18:35+00:00" > 09/22/25, 18:18 </span>
-
Gerrit Code Review pushed patch set 1 for main to change 90779 <span data-processor="relativetime" data-value="2025-09-23T20:06:45+00:00" > 09/23/25, 20:06 </span>
-
Gerrit Code Review pushed patch set 2 for main to change 90779 <span data-processor="relativetime" data-value="2025-09-23T20:11:09+00:00" > 09/23/25, 20:11 </span>
-
Gerrit Code Review pushed patch set 3 for main to change 90779 <span data-processor="relativetime" data-value="2025-09-23T20:12:30+00:00" > 09/23/25, 20:12 </span>
-
Gerrit Code Review pushed patch set 4 for main to change 90779 <span data-processor="relativetime" data-value="2025-09-23T20:14:22+00:00" > 09/23/25, 20:14 </span>
-
Gerrit Code Review pushed patch set 40 for main to change 90428 <span data-processor="relativetime" data-value="2025-09-25T19:34:44+00:00" > 09/25/25, 19:34 </span>
-
Gerrit Code Review pushed patch set 39 for main to change 90780 <span data-processor="relativetime" data-value="2025-10-29T14:30:47+00:00" > 10/29/25, 14:30 </span>
-
Gerrit Code Review pushed patch set 40 for main to change 90780 <span data-processor="relativetime" data-value="2025-10-29T17:59:47+00:00" > 10/29/25, 17:59 </span>
-
Benni Mack changed target version <span data-processor="relativetime" data-value="2026-04-21T11:25:13+00:00" > 04/21/26, 11:25 </span>
-
Garvin Hicking commented and changed status
Under ReviewClosed <span data-processor="relativetime" data-value="2026-11-11T13:37:52+00:00" > 11/11/26, 13:37 </span>Abandoning, I’m afraid we couldn’t move this forward – closing for housekeeping. Can be restored if work shall be put up again.
Hi!
Thanks for contributing! Would you like to propose this as a patch on gerrit (review.typo3.org, see contribution guide on https://docs.typo3.org/core-contribution)? That would make code review and voting and testing easier. :)