class FileUploadResource
Same name in other branches
- 8.9.x core/modules/file/src/Plugin/rest/resource/FileUploadResource.php \Drupal\file\Plugin\rest\resource\FileUploadResource
- 10 core/modules/file/src/Plugin/rest/resource/FileUploadResource.php \Drupal\file\Plugin\rest\resource\FileUploadResource
- 11.x core/modules/file/src/Plugin/rest/resource/FileUploadResource.php \Drupal\file\Plugin\rest\resource\FileUploadResource
File upload resource.
This is implemented as a field-level resource for the following reasons:
- Validation for uploaded files is tied to fields (allowed extensions, max size, etc..).
- The actual files do not need to be stored in another temporary location, to be later moved when they are referenced from a file field.
- Permission to upload a file can be determined by a users field level create access to the file field.
Plugin annotation
@RestResource(
id = "file:upload",
label = @Translation("File Upload"),
serialization_class = "Drupal\file\Entity\File",
uri_paths = {
"create" = "/file/upload/{entity_type_id}/{bundle}/{field_name}"
}
)
Hierarchy
- class \Drupal\Component\Plugin\PluginBase implements \Drupal\Component\Plugin\PluginInspectionInterface, \Drupal\Component\Plugin\DerivativeInspectionInterface
- class \Drupal\Core\Plugin\PluginBase extends \Drupal\Component\Plugin\PluginBase uses \Drupal\Core\StringTranslation\StringTranslationTrait, \Drupal\Core\DependencyInjection\DependencySerializationTrait, \Drupal\Core\Messenger\MessengerTrait
- class \Drupal\rest\Plugin\ResourceBase extends \Drupal\Core\Plugin\PluginBase implements \Drupal\Core\Plugin\ContainerFactoryPluginInterface, \Drupal\rest\Plugin\ResourceInterface
- class \Drupal\file\Plugin\rest\resource\FileUploadResource extends \Drupal\rest\Plugin\ResourceBase uses \Drupal\rest\Plugin\rest\resource\EntityResourceValidationTrait
- class \Drupal\rest\Plugin\ResourceBase extends \Drupal\Core\Plugin\PluginBase implements \Drupal\Core\Plugin\ContainerFactoryPluginInterface, \Drupal\rest\Plugin\ResourceInterface
- class \Drupal\Core\Plugin\PluginBase extends \Drupal\Component\Plugin\PluginBase uses \Drupal\Core\StringTranslation\StringTranslationTrait, \Drupal\Core\DependencyInjection\DependencySerializationTrait, \Drupal\Core\Messenger\MessengerTrait
Expanded class hierarchy of FileUploadResource
File
-
core/
modules/ file/ src/ Plugin/ rest/ resource/ FileUploadResource.php, line 57
Namespace
Drupal\file\Plugin\rest\resourceView source
class FileUploadResource extends ResourceBase {
use EntityResourceValidationTrait {
validate as resourceValidate;
}
/**
* The regex used to extract the filename from the content disposition header.
*
* @var string
*/
const REQUEST_HEADER_FILENAME_REGEX = '@\\bfilename(?<star>\\*?)=\\"(?<filename>.+)\\"@';
/**
* The amount of bytes to read in each iteration when streaming file data.
*
* @var int
*/
const BYTES_TO_READ = 8192;
/**
* The file system service.
*
* @var \Drupal\Core\File\FileSystem
*/
protected $fileSystem;
/**
* The entity type manager.
*
* @var \Drupal\Core\Entity\EntityTypeManagerInterface
*/
protected $entityTypeManager;
/**
* The entity field manager.
*
* @var \Drupal\Core\Entity\EntityFieldManagerInterface
*/
protected $entityFieldManager;
/**
* The currently authenticated user.
*
* @var \Drupal\Core\Session\AccountInterface
*/
protected $currentUser;
/**
* The MIME type guesser.
*
* @var \Symfony\Component\Mime\MimeTypeGuesserInterface
*/
protected $mimeTypeGuesser;
/**
* The token replacement instance.
*
* @var \Drupal\Core\Utility\Token
*/
protected $token;
/**
* The lock service.
*
* @var \Drupal\Core\Lock\LockBackendInterface
*/
protected $lock;
/**
* @var \Drupal\Core\Config\ImmutableConfig
*/
protected $systemFileConfig;
/**
* The event dispatcher to dispatch the filename sanitize event.
*
* @var \Symfony\Contracts\EventDispatcher\EventDispatcherInterface
*/
protected $eventDispatcher;
/**
* Constructs a FileUploadResource instance.
*
* @param array $configuration
* A configuration array containing information about the plugin instance.
* @param string $plugin_id
* The plugin_id for the plugin instance.
* @param mixed $plugin_definition
* The plugin implementation definition.
* @param array $serializer_formats
* The available serialization formats.
* @param \Psr\Log\LoggerInterface $logger
* A logger instance.
* @param \Drupal\Core\File\FileSystemInterface $file_system
* The file system service.
* @param \Drupal\Core\Entity\EntityTypeManagerInterface $entity_type_manager
* The entity type manager.
* @param \Drupal\Core\Entity\EntityFieldManagerInterface $entity_field_manager
* The entity field manager.
* @param \Drupal\Core\Session\AccountInterface $current_user
* The currently authenticated user.
* @param \Symfony\Component\Mime\MimeTypeGuesserInterface $mime_type_guesser
* The MIME type guesser.
* @param \Drupal\Core\Utility\Token $token
* The token replacement instance.
* @param \Drupal\Core\Lock\LockBackendInterface $lock
* The lock service.
* @param \Drupal\Core\Config\Config $system_file_config
* The system file configuration.
* @param \Symfony\Contracts\EventDispatcher\EventDispatcherInterface $event_dispatcher
* The event dispatcher service.
*/
public function __construct(array $configuration, $plugin_id, $plugin_definition, $serializer_formats, LoggerInterface $logger, FileSystemInterface $file_system, EntityTypeManagerInterface $entity_type_manager, EntityFieldManagerInterface $entity_field_manager, AccountInterface $current_user, $mime_type_guesser, Token $token, LockBackendInterface $lock, Config $system_file_config, EventDispatcherInterface $event_dispatcher = NULL) {
parent::__construct($configuration, $plugin_id, $plugin_definition, $serializer_formats, $logger);
$this->fileSystem = $file_system;
$this->entityTypeManager = $entity_type_manager;
$this->entityFieldManager = $entity_field_manager;
$this->currentUser = $current_user;
$this->mimeTypeGuesser = $mime_type_guesser;
$this->token = $token;
$this->lock = $lock;
$this->systemFileConfig = $system_file_config;
if (!$event_dispatcher) {
@trigger_error('The event dispatcher service should be passed to FileUploadResource::__construct() since 9.2.0. This will be required in Drupal 10.0.0. See https://www.drupal.org/node/3032541', E_USER_DEPRECATED);
$event_dispatcher = \Drupal::service('event_dispatcher');
}
$this->eventDispatcher = $event_dispatcher;
}
/**
* {@inheritdoc}
*/
public static function create(ContainerInterface $container, array $configuration, $plugin_id, $plugin_definition) {
return new static($configuration, $plugin_id, $plugin_definition, $container->getParameter('serializer.formats'), $container->get('logger.factory')
->get('rest'), $container->get('file_system'), $container->get('entity_type.manager'), $container->get('entity_field.manager'), $container->get('current_user'), $container->get('file.mime_type.guesser'), $container->get('token'), $container->get('lock'), $container->get('config.factory')
->get('system.file'), $container->get('event_dispatcher'));
}
/**
* {@inheritdoc}
*/
public function permissions() {
// Access to this resource depends on field-level access so no explicit
// permissions are required.
// @see \Drupal\file\Plugin\rest\resource\FileUploadResource::validateAndLoadFieldDefinition()
// @see \Drupal\rest\Plugin\rest\resource\EntityResource::permissions()
return [];
}
/**
* Creates a file from an endpoint.
*
* @param \Symfony\Component\HttpFoundation\Request $request
* The current request.
* @param string $entity_type_id
* The entity type ID.
* @param string $bundle
* The entity bundle. This will be the same as $entity_type_id for entity
* types that don't support bundles.
* @param string $field_name
* The field name.
*
* @return \Drupal\rest\ModifiedResourceResponse
* A 201 response, on success.
*
* @throws \Symfony\Component\HttpKernel\Exception\HttpException
* Thrown when temporary files cannot be written, a lock cannot be acquired,
* or when temporary files cannot be moved to their new location.
*/
public function post(Request $request, $entity_type_id, $bundle, $field_name) {
$filename = $this->validateAndParseContentDispositionHeader($request);
$field_definition = $this->validateAndLoadFieldDefinition($entity_type_id, $bundle, $field_name);
$destination = $this->getUploadLocation($field_definition->getSettings());
// Check the destination file path is writable.
if (!$this->fileSystem
->prepareDirectory($destination, FileSystemInterface::CREATE_DIRECTORY)) {
throw new HttpException(500, 'Destination file path is not writable');
}
$validators = $this->getUploadValidators($field_definition);
$prepared_filename = $this->prepareFilename($filename, $validators);
// Create the file.
$file_uri = "{$destination}/{$prepared_filename}";
$temp_file_path = $this->streamUploadData();
$file_uri = $this->fileSystem
->getDestinationFilename($file_uri, FileSystemInterface::EXISTS_RENAME);
// Lock based on the prepared file URI.
$lock_id = $this->generateLockIdFromFileUri($file_uri);
if (!$this->lock
->acquire($lock_id)) {
throw new HttpException(503, sprintf('File "%s" is already locked for writing', $file_uri), NULL, [
'Retry-After' => 1,
]);
}
// Begin building file entity.
$file = File::create([]);
$file->setOwnerId($this->currentUser
->id());
$file->setFilename($prepared_filename);
if ($this->mimeTypeGuesser instanceof MimeTypeGuesserInterface) {
$file->setMimeType($this->mimeTypeGuesser
->guessMimeType($prepared_filename));
}
else {
$file->setMimeType($this->mimeTypeGuesser
->guess($prepared_filename));
@trigger_error('\\Symfony\\Component\\HttpFoundation\\File\\MimeType\\MimeTypeGuesserInterface is deprecated in drupal:9.1.0 and is removed from drupal:10.0.0. Implement \\Symfony\\Component\\Mime\\MimeTypeGuesserInterface instead. See https://www.drupal.org/node/3133341', E_USER_DEPRECATED);
}
$file->setFileUri($temp_file_path);
// Set the size. This is done in File::preSave() but we validate the file
// before it is saved.
$file->setSize(@filesize($temp_file_path));
// Validate the file against field-level validators first while the file is
// still a temporary file. Validation is split up in 2 steps to be the same
// as in _file_save_upload_single().
// For backwards compatibility this part is copied from ::validate() to
// leave that method behavior unchanged.
// @todo Improve this with a file uploader service in
// https://www.drupal.org/project/drupal/issues/2940383
$errors = file_validate($file, $validators);
if (!empty($errors)) {
$message = "Unprocessable Entity: file validation failed.\n";
$message .= implode("\n", array_map([
PlainTextOutput::class,
'renderFromHtml',
], $errors));
throw new UnprocessableEntityHttpException($message);
}
$file->setFileUri($file_uri);
// Move the file to the correct location after validation. Use
// FileSystemInterface::EXISTS_ERROR as the file location has already been
// determined above in FileSystem::getDestinationFilename().
try {
$this->fileSystem
->move($temp_file_path, $file_uri, FileSystemInterface::EXISTS_ERROR);
} catch (FileException $e) {
throw new HttpException(500, 'Temporary file could not be moved to file location');
}
// Second step of the validation on the file object itself now.
$this->resourceValidate($file);
$file->save();
$this->lock
->release($lock_id);
// 201 Created responses return the newly created entity in the response
// body. These responses are not cacheable, so we add no cacheability
// metadata here.
return new ModifiedResourceResponse($file, 201);
}
/**
* Streams file upload data to temporary file and moves to file destination.
*
* @return string
* The temp file path.
*
* @throws \Symfony\Component\HttpKernel\Exception\HttpException
* Thrown when input data cannot be read, the temporary file cannot be
* opened, or the temporary file cannot be written.
*/
protected function streamUploadData() {
// 'rb' is needed so reading works correctly on Windows environments too.
$file_data = fopen('php://input', 'rb');
$temp_file_path = $this->fileSystem
->tempnam('temporary://', 'file');
$temp_file = fopen($temp_file_path, 'wb');
if ($temp_file) {
while (!feof($file_data)) {
$read = fread($file_data, static::BYTES_TO_READ);
if ($read === FALSE) {
// Close the file streams.
fclose($temp_file);
fclose($file_data);
$this->logger
->error('Input data could not be read');
throw new HttpException(500, 'Input file data could not be read');
}
if (fwrite($temp_file, $read) === FALSE) {
// Close the file streams.
fclose($temp_file);
fclose($file_data);
$this->logger
->error('Temporary file data for "%path" could not be written', [
'%path' => $temp_file_path,
]);
throw new HttpException(500, 'Temporary file data could not be written');
}
}
// Close the temp file stream.
fclose($temp_file);
}
else {
// Close the input file stream since we can't proceed with the upload.
// Don't try to close $temp_file since it's FALSE at this point.
fclose($file_data);
$this->logger
->error('Temporary file "%path" could not be opened for file upload', [
'%path' => $temp_file_path,
]);
throw new HttpException(500, 'Temporary file could not be opened');
}
// Close the input stream.
fclose($file_data);
return $temp_file_path;
}
/**
* Validates and extracts the filename from the Content-Disposition header.
*
* @param \Symfony\Component\HttpFoundation\Request $request
* The request object.
*
* @return string
* The filename extracted from the header.
*
* @throws \Symfony\Component\HttpKernel\Exception\BadRequestHttpException
* Thrown when the 'Content-Disposition' request header is invalid.
*/
protected function validateAndParseContentDispositionHeader(Request $request) {
// Firstly, check the header exists.
if (!$request->headers
->has('content-disposition')) {
throw new BadRequestHttpException('"Content-Disposition" header is required. A file name in the format "filename=FILENAME" must be provided');
}
$content_disposition = $request->headers
->get('content-disposition');
// Parse the header value. This regex does not allow an empty filename.
// i.e. 'filename=""'. This also matches on a word boundary so other keys
// like 'not_a_filename' don't work.
if (!preg_match(static::REQUEST_HEADER_FILENAME_REGEX, $content_disposition, $matches)) {
throw new BadRequestHttpException('No filename found in "Content-Disposition" header. A file name in the format "filename=FILENAME" must be provided');
}
// Check for the "filename*" format. This is currently unsupported.
if (!empty($matches['star'])) {
throw new BadRequestHttpException('The extended "filename*" format is currently not supported in the "Content-Disposition" header');
}
// Don't validate the actual filename here, that will be done by the upload
// validators in validate().
// @see \Drupal\file\Plugin\rest\resource\FileUploadResource::validate()
$filename = $matches['filename'];
// Make sure only the filename component is returned. Path information is
// stripped as per https://tools.ietf.org/html/rfc6266#section-4.3.
return $this->fileSystem
->basename($filename);
}
/**
* Validates and loads a field definition instance.
*
* @param string $entity_type_id
* The entity type ID the field is attached to.
* @param string $bundle
* The bundle the field is attached to.
* @param string $field_name
* The field name.
*
* @return \Drupal\Core\Field\FieldDefinitionInterface
* The field definition.
*
* @throws \Symfony\Component\HttpKernel\Exception\BadRequestHttpException
* Thrown when the field does not exist.
* @throws \Symfony\Component\HttpFoundation\File\Exception\AccessDeniedException
* Thrown when the target type of the field is not a file, or the current
* user does not have 'edit' access for the field.
*/
protected function validateAndLoadFieldDefinition($entity_type_id, $bundle, $field_name) {
$field_definitions = $this->entityFieldManager
->getFieldDefinitions($entity_type_id, $bundle);
if (!isset($field_definitions[$field_name])) {
throw new NotFoundHttpException(sprintf('Field "%s" does not exist', $field_name));
}
/** @var \Drupal\Core\Field\FieldDefinitionInterface $field_definition */
$field_definition = $field_definitions[$field_name];
if ($field_definition->getSetting('target_type') !== 'file') {
throw new AccessDeniedHttpException(sprintf('"%s" is not a file field', $field_name));
}
$entity_access_control_handler = $this->entityTypeManager
->getAccessControlHandler($entity_type_id);
$bundle = $this->entityTypeManager
->getDefinition($entity_type_id)
->hasKey('bundle') ? $bundle : NULL;
$access_result = $entity_access_control_handler->createAccess($bundle, NULL, [], TRUE)
->andIf($entity_access_control_handler->fieldAccess('edit', $field_definition, NULL, NULL, TRUE));
if (!$access_result->isAllowed()) {
throw new AccessDeniedHttpException($access_result->getReason());
}
return $field_definition;
}
/**
* Validates the file.
*
* @todo this method is unused in this class because file validation needs to
* be split up in 2 steps in ::post(). Add a deprecation notice as soon as a
* central core file upload service can be used in this class.
* See https://www.drupal.org/project/drupal/issues/2940383
*
* @param \Drupal\file\FileInterface $file
* The file entity to validate.
* @param array $validators
* An array of upload validators to pass to file_validate().
*
* @throws \Symfony\Component\HttpKernel\Exception\UnprocessableEntityHttpException
* Thrown when there are file validation errors.
*/
protected function validate(FileInterface $file, array $validators) {
$this->resourceValidate($file);
// Validate the file based on the field definition configuration.
$errors = file_validate($file, $validators);
if (!empty($errors)) {
$message = "Unprocessable Entity: file validation failed.\n";
$message .= implode("\n", array_map(function ($error) {
return PlainTextOutput::renderFromHtml($error);
}, $errors));
throw new UnprocessableEntityHttpException($message);
}
}
/**
* Prepares the filename to strip out any malicious extensions.
*
* @param string $filename
* The file name.
* @param array $validators
* The array of upload validators.
*
* @return string
* The prepared/munged filename.
*/
protected function prepareFilename($filename, array &$validators) {
// The actual extension validation occurs in
// \Drupal\file\Plugin\rest\resource\FileUploadResource::validate().
$extensions = $validators['file_validate_extensions'][0] ?? '';
$event = new FileUploadSanitizeNameEvent($filename, $extensions);
$this->eventDispatcher
->dispatch($event);
return $event->getFilename();
}
/**
* Determines the URI for a file field.
*
* @param array $settings
* The array of field settings.
*
* @return string
* An un-sanitized file directory URI with tokens replaced. The result of
* the token replacement is then converted to plain text and returned.
*/
protected function getUploadLocation(array $settings) {
$destination = trim($settings['file_directory'], '/');
// Replace tokens. As the tokens might contain HTML we convert it to plain
// text.
$destination = PlainTextOutput::renderFromHtml($this->token
->replace($destination, []));
return $settings['uri_scheme'] . '://' . $destination;
}
/**
* Retrieves the upload validators for a field definition.
*
* This is copied from \Drupal\file\Plugin\Field\FieldType\FileItem as there
* is no entity instance available here that a FileItem would exist for.
*
* @param \Drupal\Core\Field\FieldDefinitionInterface $field_definition
* The field definition for which to get validators.
*
* @return array
* An array suitable for passing to file_save_upload() or the file field
* element's '#upload_validators' property.
*/
protected function getUploadValidators(FieldDefinitionInterface $field_definition) {
$validators = [
// Add in our check of the file name length.
'file_validate_name_length' => [],
];
$settings = $field_definition->getSettings();
// Cap the upload size according to the PHP limit.
$max_filesize = Bytes::toNumber(Environment::getUploadMaxSize());
if (!empty($settings['max_filesize'])) {
$max_filesize = min($max_filesize, Bytes::toNumber($settings['max_filesize']));
}
// There is always a file size limit due to the PHP server limit.
$validators['file_validate_size'] = [
$max_filesize,
];
// Add the extension check if necessary.
if (!empty($settings['file_extensions'])) {
$validators['file_validate_extensions'] = [
$settings['file_extensions'],
];
}
return $validators;
}
/**
* {@inheritdoc}
*/
protected function getBaseRoute($canonical_path, $method) {
return new Route($canonical_path, [
'_controller' => RequestHandler::class . '::handleRaw',
], $this->getBaseRouteRequirements($method), [], '', [], [
$method,
]);
}
/**
* {@inheritdoc}
*/
protected function getBaseRouteRequirements($method) {
$requirements = parent::getBaseRouteRequirements($method);
// Add the content type format access check. This will enforce that all
// incoming requests can only use the 'application/octet-stream'
// Content-Type header.
$requirements['_content_type_format'] = 'bin';
return $requirements;
}
/**
* Generates a lock ID based on the file URI.
*
* @param $file_uri
* The file URI.
*
* @return string
* The generated lock ID.
*/
protected static function generateLockIdFromFileUri($file_uri) {
return 'file:rest:' . Crypt::hashBase64($file_uri);
}
}
Members
Title Sort descending | Modifiers | Object type | Summary | Member alias | Overriden Title | Overrides |
---|---|---|---|---|---|---|
EntityResourceValidationTrait::validate | protected | function | Verifies that an entity does not violate any validation constraints. | Aliased as: resourceValidate | ||
FileUploadResource::$currentUser | protected | property | The currently authenticated user. | |||
FileUploadResource::$entityFieldManager | protected | property | The entity field manager. | |||
FileUploadResource::$entityTypeManager | protected | property | The entity type manager. | |||
FileUploadResource::$eventDispatcher | protected | property | The event dispatcher to dispatch the filename sanitize event. | |||
FileUploadResource::$fileSystem | protected | property | The file system service. | |||
FileUploadResource::$lock | protected | property | The lock service. | |||
FileUploadResource::$mimeTypeGuesser | protected | property | The MIME type guesser. | |||
FileUploadResource::$systemFileConfig | protected | property | ||||
FileUploadResource::$token | protected | property | The token replacement instance. | |||
FileUploadResource::BYTES_TO_READ | constant | The amount of bytes to read in each iteration when streaming file data. | ||||
FileUploadResource::create | public static | function | Creates an instance of the plugin. | Overrides ResourceBase::create | ||
FileUploadResource::generateLockIdFromFileUri | protected static | function | Generates a lock ID based on the file URI. | |||
FileUploadResource::getBaseRoute | protected | function | Gets the base route for a particular method. | Overrides ResourceBase::getBaseRoute | ||
FileUploadResource::getBaseRouteRequirements | protected | function | Gets the base route requirements for a particular method. | Overrides ResourceBase::getBaseRouteRequirements | ||
FileUploadResource::getUploadLocation | protected | function | Determines the URI for a file field. | |||
FileUploadResource::getUploadValidators | protected | function | Retrieves the upload validators for a field definition. | |||
FileUploadResource::permissions | public | function | Implements ResourceInterface::permissions(). | Overrides ResourceBase::permissions | ||
FileUploadResource::post | public | function | Creates a file from an endpoint. | |||
FileUploadResource::prepareFilename | protected | function | Prepares the filename to strip out any malicious extensions. | |||
FileUploadResource::REQUEST_HEADER_FILENAME_REGEX | constant | The regex used to extract the filename from the content disposition header. | ||||
FileUploadResource::streamUploadData | protected | function | Streams file upload data to temporary file and moves to file destination. | |||
FileUploadResource::validate | protected | function | Validates the file. | |||
FileUploadResource::validateAndLoadFieldDefinition | protected | function | Validates and loads a field definition instance. | |||
FileUploadResource::validateAndParseContentDispositionHeader | protected | function | Validates and extracts the filename from the Content-Disposition header. | |||
FileUploadResource::__construct | public | function | Constructs a FileUploadResource instance. | Overrides ResourceBase::__construct | ||
PluginInspectionInterface::getPluginDefinition | public | function | Gets the definition of the plugin implementation. | 6 | ||
PluginInspectionInterface::getPluginId | public | function | Gets the plugin_id of the plugin instance. | 2 | ||
ResourceBase::$logger | protected | property | A logger instance. | |||
ResourceBase::$serializerFormats | protected | property | The available serialization formats. | |||
ResourceBase::availableMethods | public | function | Returns the available HTTP request methods on this plugin. | Overrides ResourceInterface::availableMethods | 1 | |
ResourceBase::requestMethods | protected | function | Provides predefined HTTP request methods. | |||
ResourceBase::routes | public | function | Returns a collection of routes with URL path information for the resource. | Overrides ResourceInterface::routes |
Buggy or inaccurate documentation? Please file an issue. Need support? Need help programming? Connect with the Drupal community.