Problem/Motivation
Part of #3221796: [META] Modernise file upload logic. Replace file_managed_file_save_upload(), file_save_upload() and _file_save_upload_from_form with new services to separate the Form API and user-facing messages from API-level services.
Steps to reproduce
Current sequence:
Proposed resolution
| Before | After | Notes |
|---|---|---|
file_managed_file_save_upload() and _file_save_upload_from_form() | \Drupal\file\Upload\FileElementHelper::saveFileUploads() | Provides a callback for \Drupal\file\Element\ManagedFile::valueCallback()Handles setting form errors, including combining error messages, and user-facing messages |
file_save_upload() | \Drupal\file\Upload\FormFileUploadHandler::saveFileUploads() | Loops through multiple uploads for the existing \Drupal\file\Upload\FileUploadHandler::handleFileUpload()By default adds error messages using Messenger::addError() but can be suppressed for cases where FileElementHelper wants to add them as form errors.
|
Notes on error handling
In order to decouple adding Messenger error messages in low-level file upload logic, we introduce an error handler that comes in two flavours:
- One that simply collects error messages for later retrieval
- On that just adds error messages to the Messenger service
In order to display info messages when a file is renamed, we introduced an event handler that handles FileUploadedEvents.
Reasoning:
Currently file_managed_file_save_upload() and _file_save_upload_from_form() have behaviour to combine upload errors and display them in a list, only if there is more than one. It does this by manipulating error messages (removing them, storing them, then re-adding them).
Default behaviour of file_save_upload() is just to add Messenger error messages.
Proposed sequence:
Remaining tasks
- Add tests for new services
- Add legacy tests for deprecated functions
Update mermain diagrams with current architectureUpdate issue summary
User interface changes
API changes
file_managed_file_save_upload(),_file_save_upload_from_formandfile_save_upload()are deprecated- New
\Drupal\file\Upload\FileElementHelperand \Drupal\file\Upload\FormFileUploadHandlerservices are added - A new
FileUploadedevent is dispatched on success of individual file uploads