Reference
File Uploads
zend-form provides support for file uploading by using features from each of zend-inputfilter, zend-validator, zend-filter, and zend-progressbar. These reusable framework components provide a convenient and secure way for handling file uploads in your projects.
Limited to POST uploads
The file upload features described here are specifically for forms using the
POST
method. zend-form does not currently provide specific support for handling uploads via thePUT
method, but it is possible with vanilla PHP. See the PUT Method Support in the PHP documentation for more information.
Basic Example
Handling file uploads is essentially the same as how you would use Zend\Form
for form processing, but with some slight caveats that will be described below.
In this example we will:
- Define a Form for backend validation and filtering.
- Create a view template with a
<form>
containing a file input. - Process the form within a Controller action (zend-mvc) or in a Request Handler (Expressive).
The Form and InputFilter
Here we define a Zend\Form\Element\File
input in a Form
extension named
UploadForm
.
use Zend\Form\Element;
use Zend\Form\Form;
class UploadForm extends Form
{
public function __construct($name = null, $options = [])
{
parent::__construct($name, $options);
$this->addElements();
}
public function addElements()
{
// File Input
$file = new Element\File('image-file');
$file->setLabel('Avatar Image Upload');
$file->setAttribute('id', 'image-file');
$this->add($file);
}
}
The File
element provides several automated features:
- The form's
enctype
will automatically be set tomultipart/form-data
when the form'sprepare()
method is called. - The file element's default input specification will create the correct
Input
type:Zend\InputFilter\FileInput
. - The
FileInput
will automatically prepend an UploadFile validator to securely validate that the file is actually an uploaded file, and to report any upload errors to the user.
The View Template
In the view template, we render the <form>
, a file input (with label and
errors), and a submit button.
<!-- File: upload-form.phtml -->
<?php
$form->prepare(); // The correct enctype is set here
$fileElement = $form->get('image-file');
echo $this->form()->openTag($form);
?>
<div class="form-element">
<?= $this->formLabel($fileElement) ?>
<?= $this->formFile($fileElement) ?>
<?= $this->formElementErrors($fileElement) ?>
</div>
<button>Submit</button>
<?= $this->form()->closeTag() ?>
When rendered, the HTML should look similar to:
<form name="upload-form" id="upload-form" method="post" enctype="multipart/form-data">
<div class="form-element">
<label for="image-file">Avatar Image Upload</label>
<input type="file" name="image-file" id="image-file">
</div>
<button>Submit</button>
</form>
The Controller Action
When using zend-mvc, the final step will be to instantiate the UploadForm
and
process any postbacks in a controller action.
The form processing in the controller action will be similar to normal forms,
except that you must merge the $_FILES
information in the request with
the other post data.
public function uploadFormAction()
{
$form = new UploadForm('upload-form');
$request = $this->getRequest();
if ($request->isPost()) {
// Make certain to merge the $_FILES info!
$post = array_merge_recursive(
$request->getPost()->toArray(),
$request->getFiles()->toArray()
);
$form->setData($post);
if ($form->isValid()) {
$data = $form->getData();
// Form is valid, save the form!
return $this->redirect()->toRoute('upload-form/success');
}
}
return ['form' => $form];
}
Upon a successful file upload, $form->getData()
would return:
array(1) {
["image-file"] => array(5) {
["name"] => string(11) "myimage.png"
["type"] => string(9) "image/png"
["tmp_name"] => string(22) "/private/tmp/phpgRXd58"
["error"] => int(0)
["size"] => int(14908679)
}
}
Using nested array notation for uploads
It is suggested that you always use the
Zend\Http\PhpEnvironment\Request
object to retrieve and merge the$_FILES
information with the form, instead of using$_FILES
directly, due to how the file information is mapped in the$_FILES
array:// A $_FILES array with single input and multiple files: array(1) { ["image-file"]=array(2) { ["name"]=array(2) { [0]=string(9)"file0.txt" [1]=string(9)"file1.txt" } ["type"]=array(2) { [0]=string(10)"text/plain" [1]=string(10)"text/html" } } } // How Zend\Http\PhpEnvironment\Request remaps the $_FILES array: array(1) { ["image-file"]=array(2) { [0]=array(2) { ["name"]=string(9)"file0.txt" ["type"]=string(10)"text/plain" }, [1]=array(2) { ["name"]=string(9)"file1.txt" ["type"]=string(10)"text/html" } } }
Zend\InputFilter\FileInput
expects the file data be in this re-mapped array format.Note: PSR-7 also remaps the
$_FILES
array in this way.
Expressive Request Handler
If you are using a PSR-15 request handler
with PSR-7 request payload, the final step
involves merging $request->getParsedBody()
with
$request->getUploadedFiles()
.
public function handle(ServerRequestInterface $request) : ResponseInterface
{
$form = new UploadForm('upload-form');
if ($request->getMethod() === 'POST') {
$post = array_merge_recursive(
$request->getParsedBody(),
$request->getUploadedFiles()
);
$form->setData($post);
if ($form->isValid()) {
$data = $form->getData();
// Form is valid, save the form!
return new RedirectResponse('upload-form/success');
}
}
return new HtmlResponse(
$this->template->render('app::page-template', [
'form' => $form,
]);
);
}
Upon a successful file upload, $form->getData()
would return array including
the file field name as a key, and a new instance of UploadedFileInterface
as
its value.
Further operations on the uploaded file
After running
isValid()
on the form instance, you should no longer trust theUploadedFileInterface
instance stored in the PSR-7$request
to perform further operations on the uploaded file. The file may be moved by one of the filters attached to form input, but since the request is immutable, the change will not be reflected in it. Therefore, after validation, always use the file information retrieved from$form->getData()
, not from$request->getUploadedFiles()
.
File Post-Redirect-Get Plugin
When using other standard form inputs (i.e. text
, checkbox
, select
, etc.)
along with file inputs in a form, you can encounter a situation where some
inputs may become invalid and the user must re-select the file and re-upload.
PHP will delete uploaded files from the temporary directory at the end of the
request if it has not been moved away or renamed. Re-uploading a valid file each
time another form input is invalid is inefficient and annoying to users.
One strategy to get around this is to split the form into multiple forms. One form for the file upload inputs and another for the other standard inputs.
When you cannot separate the forms, the File Post-Redirect-Get Plugin can be used to manage the file inputs and save off valid uploads until the entire form is valid.
Changing our earlier example to use the fileprg()
plugin will require two
changes.
RenameUpload filter
First, we need to add a RenameUpload
filter to our form's file input, with
details on where the valid files should be stored:
use Zend\InputFilter;
use Zend\Form\Element;
use Zend\Form\Form;
class UploadForm extends Form
{
public function __construct($name = null, $options = [])
{
parent::__construct($name, $options);
$this->addElements();
$this->addInputFilter();
}
public function addElements()
{
// File Input
$file = new Element\File('image-file');
$file->setLabel('Avatar Image Upload')
$file->setAttribute('id', 'image-file');
$this->add($file);
}
public function addInputFilter()
{
$inputFilter = new InputFilter\InputFilter();
// File Input
$fileInput = new InputFilter\FileInput('image-file');
$fileInput->setRequired(true);
$fileInput->getFilterChain()->attachByName(
'filerenameupload',
[
'target' => './data/tmpuploads/avatar.png',
'randomize' => true,
]
);
$inputFilter->add($fileInput);
$this->setInputFilter($inputFilter);
}
}
The filerenameupload
options above would cause an uploaded file to be
renamed and moved to: ./data/tmpuploads/avatar_4b3403665fea6.png
.
See the RenameUpload filter documentation for more information on its supported options.
Further operations on the uploaded file
If the file is coming in as a PSR-7 payload, the move operation will be performed on the passed
UploadedFileInterface
instance. Therefore, it will contain an expired stream and outdated target file name. After running this filter, do not use the request object to get further details about the uploaded file; use the new instance ofUploadedFileInterface
returned from the filter invocation.
Call the fileprg plugin
Next, we need to update our controller action to use the fileprg
plugin:
public function uploadFormAction()
{
$form = new UploadForm('upload-form');
$tempFile = null;
$prg = $this->fileprg($form);
if ($prg instanceof \Zend\Http\PhpEnvironment\Response) {
return $prg; // Return PRG redirect response
}
if (is_array($prg)) {
if ($form->isValid()) {
$data = $form->getData();
// Form is valid, save the form!
return $this->redirect()->toRoute('upload-form/success');
}
// Form not valid, but file uploads might be valid...
// Get the temporary file information to show the user in the view
$fileErrors = $form->get('image-file')->getMessages();
if (empty($fileErrors)) {
$tempFile = $form->get('image-file')->getValue();
}
}
return [
'form' => $form,
'tempFile' => $tempFile,
];
}
Behind the scenes, the FilePRG
plugin will:
- Run the Form's filters, namely the
RenameUpload
filter, to move the files out of temporary storage. - Store the valid POST data in the session across requests.
- Change the
required
flag of any file inputs that had valid uploads tofalse
. This is so that form re-submissions without uploads will not cause validation errors.
User notifications
In the case of a partially valid form, it is up to the developer whether to notify the user that files have been uploaded or not. For example, you may wish to hide the form input and/or display the file information. These things would be implementation details in the view or in a custom view helper. Just note that neither the
FilePRG
plugin nor theformFile
view helper will do any automatic notifications or view changes when files have been successfully uploaded.
HTML5 Multi-File Uploads
With HTML5, we are able to select multiple files from a single file input using
the multiple
attribute. Not all browsers support multiple file
uploads, but the file input will safely remain
a single file upload for those browsers that do not support the feature.
To enable multiple file uploads in zend-form, set the file element's
multiple
attribute to true:
use Zend\InputFilter;
use Zend\Form\Element;
use Zend\Form\Form;
class UploadForm extends Form
{
public function __construct($name = null, $options = [])
{
parent::__construct($name, $options);
$this->addElements();
$this->addInputFilter();
}
public function addElements()
{
// File Input
$file = new Element\File('image-file');
$file->setLabel('Avatar Image Upload');
$file->setAttribute('id', 'image-file');
$file->setAttribute('multiple', true); // Marking as multiple
$this->add($file);
}
public function addInputFilter()
{
$inputFilter = new InputFilter\InputFilter();
// File Input
$fileInput = new InputFilter\FileInput('image-file');
$fileInput->setRequired(true);
// Define validators and filters as if only one file was being uploaded.
// All files will be run through the same validators and filters
// automatically.
$fileInput->getValidatorChain()
->attachByName('filesize', ['max' => 204800])
->attachByName('filemimetype', ['mimeType' => 'image/png,image/x-png'])
->attachByName('fileimagesize', ['maxWidth' => 100, 'maxHeight' => 100]);
// All files will be renamed, e.g.:
// ./data/tmpuploads/avatar_4b3403665fea6.png,
// ./data/tmpuploads/avatar_5c45147660fb7.png
$fileInput->getFilterChain()->attachByName(
'filerenameupload',
[
'target' => './data/tmpuploads/avatar.png',
'randomize' => true,
]
);
$inputFilter->add($fileInput);
$this->setInputFilter($inputFilter);
}
}
You do not need to do anything special with the validators and filters to
support multiple file uploads. All of the files that are uploaded will have the
same validators and filters run against them automatically (from logic within
FileInput
). Define them as if a single file was being uploaded.
Upload Progress
While pure client-based upload progress meters are starting to become available with HTML5's Progress Events, not all browsers have XMLHttpRequest level 2 support. For upload progress to work in a greater number of browsers (IE9 and below), you must use a server-side progress solution.
Zend\ProgressBar\Upload
provides handlers that can give you the actual state
of a file upload in progress. To use this feature, you need to choose one of the
Upload Progress Handlers
(APC, uploadprogress, or Session) and ensure that your server setup has the
appropriate extension or feature enabled.
Verify your php.ini
session.upload
settings before you begin:
file_uploads = On
post_max_size = 50M
upload_max_filesize = 50M
session.upload_progress.enabled = On
session.upload_progress.freq = "1%"
session.upload_progress.min_freq = "1"
; Also make certain 'upload_tmp_dir' is writable
When uploading a file with a form POST, you must also include the progress identifier in a hidden input. The file upload progress view helpers provides a convenient way to add the hidden input based on your handler type.
<!-- File: upload-form.phtml -->
<?php
$fileElement = $form->get('image-file');
$form->prepare();
echo $this->form()->openTag($form);
echo $this->formFileSessionProgress(); // Must come before the file input!
?>
<div class="form-element">
<?= $this->formLabel($fileElement) ?>
<?= $this->formFile($fileElement) ?>
<?= $this->formElementErrors($fileElement) ?>
</div>
<button>Submit</button>
<?= $this->form()->closeTag() ?>
When rendered, the HTML should look similar to:
<form name="upload-form" id="upload-form" method="post" enctype="multipart/form-data">
<input type="hidden" id="progress_key" name="PHP_SESSION_UPLOAD_PROGRESS" value="12345abcde">
<div class="form-element">
<label for="image-file">Avatar Image Upload</label>
<input type="file" name="image-file" id="image-file">
</div>
<button>Submit</button>
</form>
There are a few different methods for getting progress information to the browser (long vs. short polling). Here we will use short polling since it is simpler and less taxing on server resources, though keep in mind it is not as responsive as long polling.
When our form is submitted via AJAX, the browser will continuously poll the server for upload progress.
The following is an example controller action which provides the progress information:
public function uploadProgressAction()
{
$id = $this->params()->fromQuery('id', null);
$progress = new \Zend\ProgressBar\Upload\SessionProgress();
return new \Zend\View\Model\JsonModel($progress->getProgress($id));
}
// Returns JSON
//{
// "total" : 204800,
// "current" : 10240,
// "rate" : 1024,
// "message" : "10kB / 200kB",
// "done" : false
//}
Performance overhead
This is not the most efficient way of providing upload progress, since each polling request must go through the Zend Framework bootstrap process. A better example would be to use a standalone php file in the public folder that bypasses the MVC bootstrapping and only uses the essential
Zend\ProgressBar
adapters.
Back in our view template, we will add Javascript to perform the AJAX POST of the form data, and to start a timeout interval for the progress polling. To keep the example code relatively short, we are using the jQuery Form plugin to do the AJAX form POST. If your project uses a different JavaScript framework (or none at all), this will hopefully at least illustrate the necessary high-level logic that would need to be performed.
<?php // File: upload-form.phtml
// ...after the form...
?>
<!-- Twitter Bootstrap progress bar styles:
http://twitter.github.com/bootstrap/components.html#progress -->
<div id="progress" class="help-block">
<div class="progress progress-info progress-striped">
<div class="bar"></div>
</div>
<p></p>
</div>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.8.3/jquery.min.js"></script>
<script src="/js/jquery.form.js"></script>
<script>
var progressInterval;
function getProgress() {
// Poll our controller action with the progress id
var url = '/upload-form/upload-progress?id=' + $('#progress_key').val();
$.getJSON(url, function(data) {
if (data.status && !data.status.done) {
var value = Math.floor((data.status.current / data.status.total) * 100);
showProgress(value, 'Uploading...');
} else {
showProgress(100, 'Complete!');
clearInterval(progressInterval);
}
});
}
function startProgress() {
showProgress(0, 'Starting upload...');
progressInterval = setInterval(getProgress, 900);
}
function showProgress(amount, message) {
$('#progress').show();
$('#progress .bar').width(amount + '%');
$('#progress > p').html(message);
if (amount < 100) {
$('#progress .progress')
.addClass('progress-info active')
.removeClass('progress-success');
} else {
$('#progress .progress')
.removeClass('progress-info active')
.addClass('progress-success');
}
}
$(function() {
// Register a 'submit' event listener on the form to perform the AJAX POST
$('#upload-form').on('submit', function(e) {
e.preventDefault();
if ($('#image-file').val() == '') {
// No files selected, abort
return;
}
// Perform the submit
//$.fn.ajaxSubmit.debug = true;
$(this).ajaxSubmit({
beforeSubmit: function(arr, $form, options) {
// Notify backend that submit is via ajax
arr.push({ name: "isAjax", value: "1" });
},
success: function (response, statusText, xhr, $form) {
clearInterval(progressInterval);
showProgress(100, 'Complete!');
// TODO: You'll need to do some custom logic here to handle a successful
// form post, and when the form is invalid with validation errors.
if (response.status) {
// TODO: Do something with a successful form post, like redirect
// window.location.replace(response.redirect);
} else {
// Clear the file input, otherwise the same file gets re-uploaded
// http://stackoverflow.com/a/1043969
var fileInput = $('#image-file');
fileInput.replaceWith( fileInput.val('').clone( true ) );
// TODO: Do something with these errors
// showErrors(response.formErrors);
}
},
error: function(a, b, c) {
// NOTE: This callback is *not* called when the form is invalid.
// It is called when the browser is unable to initiate or complete the ajax submit.
// You will need to handle validation errors in the 'success' callback.
console.log(a, b, c);
}
});
// Start the progress polling
startProgress();
});
});
</script>
And finally, our controller action can be modified to return form status and validation messages in JSON format if we see the 'isAjax' post parameter (which was set in the JavaScript just before submit):
public function uploadFormAction()
{
$form = new UploadForm('upload-form');
$request = $this->getRequest();
if (! $request->isPost()) {
return ['form' => $form];
}
// Make certain to merge the files info!
$post = array_merge_recursive(
$request->getPost()->toArray(),
$request->getFiles()->toArray()
);
$form->setData($post);
if ($form->isValid()) {
$data = $form->getData();
// Form is valid, save the form!
if (! empty($post['isAjax'])) {
return new JsonModel(array(
'status' => true,
'redirect' => $this->url()->fromRoute('upload-form/success'),
'formData' => $data,
));
}
// Fallback for non-JS clients
return $this->redirect()->toRoute('upload-form/success');
}
if (! empty($post['isAjax'])) {
// Send back failure information via JSON
return new JsonModel([
'status' => false,
'formErrors' => $form->getMessages(),
'formData' => $form->getData(),
]);
}
return array('form' => $form);
}
Additional Info
Related documentation:
- Form File Element
- Form File View Helper
- List of File Validators
- List of File Filters
- File Post-Redirect-Get Controller Plugin
- Zend\InputFilter\FileInput
- Upload Progress Handlers
- Upload Progress View Helpers
External resources and blog posts from the community:
- ZF2FileUploadExamples : A ZF2 module with several file upload examples.
Found a mistake or want to contribute to the documentation? Edit this page on GitHub!