Navigation

File Uploading

Zend Framework provides support for file uploading by using features in Zend\Form, 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.

Note

If the reader has experience with file uploading in Zend Framework v1.x, he/she will notice some major differences. Zend_File\Transfer has been deprecated in favor of using the standard ZF2 Zend\Form and Zend\InputFilter features.

Note

The file upload features described here are specifically for forms using the POST method. Zend Framework itself does not currently provide specific support for handling uploads via the PUT method, but it is possible with PHP. See the PUT Method Support in the PHP documentation for more information.

Standard 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.

The Form and InputFilter

Here we define a Zend\Form\Element\File input in a Form class named UploadForm.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
// File: UploadForm.php

use Zend\Form\Element;
use Zend\Form\Form;

class UploadForm extends Form
{
    public function __construct($name = null, $options = array())
    {
        parent::__construct($name, $options);
        $this->addElements();
    }

    public function addElements()
    {
        // File Input
        $file = new Element\File('image-file');
        $file->setLabel('Avatar Image Upload')
             ->setAttribute('id', 'image-file');
        $this->add($file);
    }
}

The File element provides some automatic features that happen behind the scenes:

  • The form’s enctype will automatically be set to multipart/form-data when the form prepare() 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 other types of 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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
// File: upload-form.phtml
<?php $form->prepare(); // The correct enctype is set here ?>
<?php echo $this->form()->openTag($form); ?>

    <div class="form-element">
        <?php $fileElement = $form->get('image-file'); ?>
        <?php echo $this->formLabel($fileElement); ?>
        <?php echo $this->formFile($fileElement); ?>
        <?php echo $this->formElementErrors($fileElement); ?>
    </div>

    <button>Submit</button>

<?php echo $this->form()->closeTag(); ?>

When rendered, the HTML should look similar to:

1
2
3
4
5
6
7
8
<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

For the final step, we will 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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// File: MyController.php

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 array('form' => $form);
}

Upon a successful file upload, $form->getData() would return:

1
2
3
4
5
6
7
8
9
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)
    }
}

Note

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.

This is due to how the file information is mapped in the $_FILES array:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
// 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.

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 Controller 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.

  1. Adding a RenameUpload filter to our form’s file input, with details on where the valid files should be stored:

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
    // File: UploadForm.php

use Zend\InputFilter;
use Zend\Form\Element;
use Zend\Form\Form;

class UploadForm extends Form
{
    public function __construct($name = null, $options = array())
    {
        parent::__construct($name, $options);
        $this->addElements();
        $this->addInputFilter();
    }

    public function addElements()
    {
        // File Input
        $file = new Element\File('image-file');
        $file->setLabel('Avatar Image Upload')
             ->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',
            array(
                '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.

  2. And, changing the Controller action to use the fileprg plugin:

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
    // File: MyController.php

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
    } elseif (is_array($prg)) {
        if ($form->isValid()) {
            $data = $form->getData();
            // Form is valid, save the form!
            return $this->redirect()->toRoute('upload-form/success');
        } else {
            // 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 array(
        '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 to false. This is so that form re-submissions without uploads will not cause validation errors.

Note

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 the formFile 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 Framework, just set the file element’s multiple attribute to true:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
// File: UploadForm.php

use Zend\InputFilter;
use Zend\Form\Element;
use Zend\Form\Form;

class UploadForm extends Form
{
    public function __construct($name = null, $options = array())
    {
        parent::__construct($name, $options);
        $this->addElements();
        $this->addInputFilter();
    }

    public function addElements()
    {
        // File Input
        $file = new Element\File('image-file');
        $file->setLabel('Avatar Image Upload')
             ->setAttribute('id', 'image-file')
             ->setAttribute('multiple', true);   // That's it
        $this->add($file);
    }

    public function addInputFilter()
    {
        $inputFilter = new InputFilter\InputFilter();

        // File Input
        $fileInput = new InputFilter\FileInput('image-file');
        $fileInput->setRequired(true);

        // You only need to 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',      array('max' => 204800))
            ->attachByName('filemimetype',  array('mimeType' => 'image/png,image/x-png'))
            ->attachByName('fileimagesize', array('maxWidth' => 100, 'maxHeight' => 100));

        // All files will be renamed, i.e.:
        //   ./data/tmpuploads/avatar_4b3403665fea6.png,
        //   ./data/tmpuploads/avatar_5c45147660fb7.png
        $fileInput->getFilterChain()->attachByName(
            'filerenameupload',
            array(
                '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). You only need to define them as if one 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.

Note

For this example we will use PHP 5.4‘s Session progress handler

PHP 5.4 is required and you may need to verify these php.ini settings for it to work:

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 provide a convenient way to add the hidden input based on your handler type.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
// File: upload-form.phtml
<?php $form->prepare(); ?>
<?php echo $this->form()->openTag($form); ?>
    <?php echo $this->formFileSessionProgress(); // Must come before the file input! ?>

    <div class="form-element">
        <?php $fileElement = $form->get('image-file'); ?>
        <?php echo $this->formLabel($fileElement); ?>
        <?php echo $this->formFile($fileElement); ?>
        <?php echo $this->formElementErrors($fileElement); ?>
    </div>

    <button>Submit</button>

<?php echo $this->form()->closeTag(); ?>

When rendered, the HTML should look similar to:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
<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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
// File: MyController.php

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
//}

Warning

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 the 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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
// 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):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
// File: MyController.php

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!
            if (!empty($post['isAjax'])) {
                return new JsonModel(array(
                    'status'   => true,
                    'redirect' => $this->url()->fromRoute('upload-form/success'),
                    'formData' => $data,
                ));
            } else {
                // Fallback for non-JS clients
                return $this->redirect()->toRoute('upload-form/success');
            }
        } else {
            if (!empty($post['isAjax'])) {
                 // Send back failure information via JSON
                 return new JsonModel(array(
                     'status'     => false,
                     'formErrors' => $form->getMessages(),
                     'formData'   => $form->getData(),
                 ));
            }
        }
    }

    return array('form' => $form);
}

Additional Info

Related documentation:

External resources and blog posts from the community:

Table Of Contents

Previous topic

Form Collections

Next topic

Advanced use of forms

This Page

Note: You need to stay logged into your GitHub account to contribute to the documentation.

Navigation

© Copyright 2013, Zend Technologies Ltd.. Created using Sphinx 1.1.3.
Edit this document

Edit this document

The source code of this file is hosted on GitHub. Everyone can update and fix errors in this document with few clicks - no downloads needed.

  1. Login with your GitHub account.
  2. Go to File Uploading on GitHub.
  3. Edit file contents using GitHub's text editor in your web browser
  4. Fill in the Commit message text box at the end of the page telling why you did the changes. Press Propose file change button next to it when done.
  5. On Send a pull request page you don't need to fill in text anymore. Just press Send pull request button.
  6. Your changes are now queued for review under project's Pull requests tab on GitHub.