TYPO3 Core

Current state¶

There is currently no "official way" how extbase file upload should be performed. Since 2014, there is the TypeConverter approach, which Helmut Hummel published on GitHub and which is used by TYPO3 users and also the TYPO3 form extension. That approach for handling file uploads has however never become something the TYPO3 core did support officially (e.g. by providing a TypeConverter extension authors can use in their projects), most likely because a TypeConverter should not be responsible to handle uploaded files and other backdraws (see https://review.typo3.org/c/Packages/TYPO3.CMS/+/37898). Users using the TypeConverter approach do face the following challenges:

• Much code in initialize*Action is required for configuration, validation and property mapping configuration
• Debugging can be hard
• Temporary uploaded files will not be removed (e.g. ext:form)
• Deleting existing files and extbase file relations is complicated
• Handling multiple file uploads is not supported and must be implemented through another TypeConverter
• A custom TypeConverter needs to be created manually and must often be adapted on TYPO3 major updates
• Custom TypeConverter created by inexperienced users may introduce security issues

For TYPO3 v12, it is currently not possible to use a TypeConverter for file upload due to a bug (https://forge.typo3.org/issues/102271). For TYPO3 v13, code to map file uploads to extbase arguments has been removed, making it impossible to use a TypeConverter for file upload handling.

The idea¶

Extbase file upload handling is a process, which should have a clear API in terms of validation, file handling and object mapping. This API should support the following aspects:

• Handle file upload for one or multiple files
• Move uploaded file(s) to target folder
• Create new extbase file relation(s) for uploaded file(s) which an be mapped to configurable object properties
• Ensure, that only files passed the configured validation rules will be processed
• Deletions for uploaded files and removal of file relations
• Getter to retrieve processed uploaded files for further usage
• PSR-14 events for developers to customize logic (e.g. target file name)

The file upload validation should provide the following aspects:

• Validator can be used via annotation (usage uncomfortable due to too many options) or via new API (preferred)
• Allows to validate uploaded files by Extbase property name or uploadedFiles attribute
• Rules for: required, max files, file size and mime types.
• PHP files should be denied in general

The new API and validator must be covered with tests and must be well documented.

Possible example usage for an Extbase action

public function initializeUpdateAction(): void
{
    $this->extbaseFileUpload->addConfiguration(
        (new ExtbaseFileUploadConfiguration())
            ->for(objectName: 'data', property: 'file')
            ->validation([
                'required' => true,
                'maxFiles' => 1,
                'fileSize' => ['min' => '100k', 'max' => '2m'],
                'mimeTypes' => ['image/jpeg']
            ])
            ->moveTo('1:/user_upload/folder/', overwriteExisting: true)
            ->createFileReference(true, removeExisting: true)
    );
}

public function updateAction(Data $data): ResponseInterface
{
    $this->dataRepository->update($data);

    return $this->redirect('list');
}

Possible technical implementation (TBD)

• Extbase file upload API is always available in ActionController
• Validation can maybe also be defined on property basis (e.g. FileUploadValidator)
• Move uploaded file(s) to temporary folder, if other validation errors occur
• Garbage collection for temporary uploaded files
• Alternative: do not save uploaded file, if validation error occured somewhere
• Property mapping through TypeConverter and/or new extbase file upload API