This is a framework agnostic upload handler library that is flexible and easy to use.
- Validates files agains usual rules: extension, file size, image size (wdith, height, ratio). It uses Sirius Validation for this purpose.
- Moves valid uploads into containers. Containers are usually local folders but you can implement your own or use other filesystem abstractions like Gaufrette or Flysystem.
- Works with PSR7
UploadedFileInterfaceobjects and with Symfony's
UploadedFiles (see integrations).
Used by Bolt CMS
How it works
- Uploaded file is validated against the rules. By default the library will check if the upload is valid (ie: no errors during upload)
- The name of the uploaded file is sanitized (keep only letters, numbers and underscore). You may implement your own sanitization function if you want.
- If overwrite is not allowed, and a file with the same name already exists in the container, the library will prepend the timestamp to the filename.
- Moves the uploaded file to the container. It also create a lock file (filename + '.lock') so that we know the upload is not confirmed. See file locking
- If something wrong happens in your app and you want to get rid of the uploaded file you can
clear()the uploaded file which will remove the file and its
.lockfile. Only files that have a corresponding
.lockfile attached can be cleared
- If everything is in order you can
confirmthe upload. This will remove the
.lockfile attached to the upload file.
1. The library makes no assumptions about the "web availability" of the uploaded file.
Most of the times once you have a valid upload the new file will be reachable on the internet. You may upload your files to
/var/www/public/images/users/ and have the files accessible at
//cdn.domain.com/users/. It's up to you to make your app work with the result of the upload.
2. You can handle multiple uploads at once if they have the same name
If you upload multiple files with the same name (eg:
<input type="file" name="pictures">) but you have to keep in mind that the
getMessages() methods will return arrays
$result = $uploadHandler->process($_FILES['pictures']); // will return a collection of files which implements \Iterator interface $messages = $result->getMessages(); // may return if the second file is not valid array( '1' => 'File type not accepted' );
In this case the library normalizes the
$_FILES array as PHP messes up the upload array.
It is up to you to decide what you want to do when some files fail to upload (eg: keep the valid files and discard the failed image or display error messages for the invalid images)