Feature: #103511 - Introduce Extbase file upload and deletion handling

Nesting of domain models

File upload handling for nested domain models (e.g. modelA.modelB.fileReference) is not supported.

File upload configuration with the FileUpload attribute

File upload for a property of a domain model can be configured using the newly introduced \TYPO3\CMS\Extbase\Annotation\FileUpload attribute.

Example:

#[FileUpload([
    'validation' => [
        'required' => true,
        'maxFiles' => 1,
        'fileSize' => ['minimum' => '0K', 'maximum' => '2M'],
        'mimeType' => ['allowedMimeTypes' => ['image/jpeg', 'image/png']],
    ],
    'uploadFolder' => '1:/user_upload/files/',
])]
protected ?FileReference $file = null;

All configuration settings of the \TYPO3\CMS\Extbase\Mvc\Controller\FileUploadConfiguration object can be defined using the FileUpload attribute. It is however not possible to add custom validators using the FileUpload attribute, which you can achieve with a manual configuration as shown below.

The currently available configuration array keys are:

• validation ( array with keys required, maxFiles, minFiles, fileSize, allowedMimeTypes, mimeType, imageDimensions, see File upload validation)
• uploadFolder ( string, destination folder)
• duplicationBehavior ( object, behaviour when file exists)
• addRandomSuffix ( bool, suffixing files)
• createUploadFolderIfNotExist ( bool, whether to create missing directories)

It is also possible to use the FileUpload annotation to configure file upload properties, but it is recommended to use the FileUpload attribute due to better readability.

Manual file upload configuration

A file upload configuration can also be created manually and should be done in the initialize*Action.

Example:

public function initializeCreateAction(): void
{
    $mimeTypeValidator = GeneralUtility::makeInstance(MimeTypeValidator::class);
    $mimeTypeValidator->setOptions(['allowedMimeTypes' => ['image/jpeg']]);

    $fileHandlingServiceConfiguration = $this->arguments->getArgument('myArgument')->getFileHandlingServiceConfiguration();
    $fileHandlingServiceConfiguration->addFileUploadConfiguration(
        (new FileUploadConfiguration('myPropertyName'))
            ->setRequired()
            ->addValidator($mimeTypeValidator)
            ->setMaxFiles(1)
            ->setUploadFolder('1:/user_upload/files/')
    );

    $this->arguments->getArgument('myArgument')->getPropertyMappingConfiguration()->skipProperties('myPropertyName');
}

Configuration options for file uploads

The configuration for a file upload is defined in a FileUploadConfiguration object.

This object contains the following configuration options.

Modifying existing configuration

File upload configuration defined by the FileUpload attribute can be changed in the initialize*Action.

Example:

public function initializeCreateAction(): void
{
    $validator = GeneralUtility::makeInstance(MyCustomValidator::class);

    $argument = $this->arguments->getArgument('myArgument');
    $configuration = $argument->getFileHandlingServiceConfiguration()->getFileUploadConfigurationForProperty('file');
    $configuration?->setMinFiles(2);
    $configuration?->addValidator($validator);
    $configuration?->setUploadFolder('1:/user_upload/custom_folder');
}

The example shows how to modify the file upload configuration for the argument item and the property file. The minimum amount of files to be uploaded is set to 2 and a custom validator is added.

To remove all defined validators except the DenyPhpUploadValidator, use the resetValidators() method.

Using TypoScript configuration for file uploads configuration

When a file upload configuration for a property has been added using the FileUpload attribute, it may be required make the upload folder or other configuration options configurable with TypoScript.

Extension authors should use the initialize*Action to apply settings from TypoScript to a file upload configuration.

Example:

public function initializeCreateAction(): void
{
    $argument = $this->arguments->getArgument('myArgument');
    $configuration = $argument->getFileHandlingServiceConfiguration()->getConfigurationForProperty('file');
    $configuration?->setUploadFolder($this->settings['uploadFolder'] ?? '1:/fallback_folder');
}

File upload validation

Each uploaded file can be validated against a configurable set of validators. The validation section of the FileUpload attribute allows to configure commonly used validators using a configuration shorthand.

The following validation rules can be configured in the validation section of the FileUpload attribute:

• required
• minFiles
• maxFiles
• fileSize (for \TYPO3\CMS\Extbase\Validation\Validator\FilesizeValidator)
• imageDimensions (for \TYPO3\CMS\Extbase\Validation\Validator\ImageDimensionsValidator )
• mimeType (for \TYPO3\CMS\Extbase\Validation\Validator\MimeTypeValidator )
• allowedMimeTypes (shorthand notation for configuration option allowedMimeTypes of the MimeTypeValidator)

Example:

#[FileUpload([
    'validation' => [
        'required' => true,
        'maxFiles' => 1,
        'fileSize' => ['minimum' => '0K', 'maximum' => '2M'],
        'mimeType' => ['allowedMimeTypes' => ['image/jpeg']],
        'imageDimensions' => ['maxWidth' => 4096, 'maxHeight' => 4096]
    ],
    'uploadFolder' => '1:/user_upload/extbase_single_file/',
])]

Extbase will internally use the Extbase file upload validators for fileSize, mimeType and imageDimensions validation.

Custom validators can be created according to project requirements and must extend the Extbase AbstractValidator . The value to be validated is always a PSR-7 UploadedFile object. Custom validators can however not be used in the FileUpload attribute and must be configured manually.

#[FileUpload([
    'validation' => [
        'required' => true,
        'mimeType' => [
            'allowedMimeTypes' => ['image/jpeg'],
            'ignoreFileExtensionCheck' => false,
            'notAllowedMessage' => 'LLL:EXT:my_extension/Resources/Private/Language/locallang.xlf:validation.mimetype.notAllowedMessage',
            'invalidExtensionMessage' => 'LLL:EXT:my_extension/Resources/Private/Language/locallang.xlf:validation.mimetype.invalidExtensionMessage',
        ],
    ],
    'uploadFolder' => '1:/user_upload/files/',
])]

Deletion of uploaded files and file references

The new Fluid ViewHelper Form.uploadDeleteCheckbox ViewHelper <f:form.uploadDeleteCheckbox> can be used to show a "delete file" checkbox in a form.

Example for object with FileReference property:

<f:form.uploadDeleteCheckbox property="file" fileReference="{object.file}" />

Example for an object with an TYPO3\CMS\Extbase\Persistence\ObjectStorage<\TYPO3\CMS\Extbase\Domain\Model\FileReference> property, containing multiple files and allowing to delete the first one (iteration is possible within Fluid, to do that for every object of the collection):

<f:form.uploadDeleteCheckbox property="file.0" fileReference="{object.file}" />

Extbase will then handle file deletion(s) before persisting a validated object. It will:

• validate that minimum and maximum file upload configuration for the affected property is fulfilled (only if the property has a FileUpload )
• delete the affected sys_file_reference record
• delete the affected file

Internally, Extbase uses FileUploadDeletionConfiguration objects to track file deletions for properties of arguments. Files are deleted directly without checking whether the current file is referenced by other objects.

Apart from using this ViewHelper, it is of course still possible to manipulate FileReference properties with custom logic before persistence.

New PSR-14 events

The following new PSR-14 event has been added to allow customization of file upload related tasks: