Epic #103022
openExtbase file upload handling
50%
Description
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
Updated by Torben Hansen 7 months ago
- Related to Feature #102951: Provide PSR-7 request in extbase validators added
Updated by Torben Hansen 7 months ago
- Related to deleted (Feature #102951: Provide PSR-7 request in extbase validators)
Updated by Daniel Goerz 6 months ago
- Related to Task #97214: Use uploadedFile objects instead of $_FILES added
Updated by Daniel Goerz 6 months ago
- Related to Bug #102271: Broken backwards compatibility in request builder for file uploads as object property added
Updated by Daniel Goerz 6 months ago
- Related to Bug #100362: Issue with imageUpload and fileUpload fieds added
Updated by Daniel Goerz 6 months ago
- Related to Bug #102283: Extbase file upload using type converters not possible any more added