vendor/zendframework/zend-progressbar/doc/book/zend.progress-bar.upload.md

   1 # File Upload Handlers
   2
   3 ## Introduction
   4
   5 `Zend\ProgressBar\Upload` provides handlers that can give you the actual state of a file upload in
   6 progress. To use this feature you need to choose one of the upload progress handlers (APC,
   7 uploadprogress, or Session) and ensure that your server setup has the appropriate extension or
   8 feature enabled. All of the progress handlers use the same interface.
   9
  10 When uploading a file with a form POST, you must also include the progress identifier in a hidden
  11 input. The \[File Upload Progress View Helpers\](zend.form.view.helper.file) provide a convenient
  12 way to add the hidden input based on your handler type.
  13
  14 ## Methods of Reporting Progress
  15
  16 There are two methods for reporting the current upload progress status. By either using a
  17 ProgressBar Adapter, or by using the returned status array manually.
  18
  19 ### Using a ProgressBar Adapter
  20
  21 A `Zend\ProgressBar` adapter can be used to display upload progress to your users.
  22
  23 ```php
  24 $adapter  = new \Zend\ProgressBar\Adapter\JsPush();
  25 $progress = new \Zend\ProgressBar\Upload\SessionProgress();
  26
  27 $filter   = new \Zend\I18n\Filter\Alnum(false, 'en_US');
  28 $id       = $filter->filter($_GET['id']);
  29
  30 $status   = null;
  31 while (empty($status['done'])) {
  32     $status = $progress->getProgress($id);
  33 }
  34 ```
  35
  36 Each time the `getProgress()` method is called, the ProgressBar adapter will be updated.
  37
  38 ### Using the Status Array
  39
  40 You can also work manually with `getProgress()` without using a `Zend\ProgressBar` adapter.
  41
  42 The `getProgress()` will return you an array with several keys. They will sometimes differ based on
  43 the specific Upload handler used, but the following keys are always standard:
  44
  45 - `total`: The total file size of the uploaded file(s) in bytes as integer.
  46 - `current`: The current uploaded file size in bytes as integer.
  47 - `rate`: The average upload speed in bytes per second as integer.
  48 - `done`: Returns `TRUE` when the upload is finished and `FALSE` otherwise.
  49 - `message`: A status message. Either the progress as text in the form "10kB / 200kB", or a helpful
  50 error message in the case of a problem. Problems such as: no upload in progress, failure while
  51 retrieving the data for the progress, or that the upload has been canceled.
  52
  53 All other returned keys are provided directly from the specific handler.
  54
  55 An example of using the status array manually:
  56
  57 ```php
  58 // In a Controller...
  59
  60 public function sessionProgressAction()
  61 {
  62     $id = $this->params()->fromQuery('id', null);
  63     $progress = new \Zend\ProgressBar\Upload\SessionProgress();
  64     return new \Zend\View\Model\JsonModel($progress->getProgress($id));
  65 }
  66
  67 // Returns JSON
  68 //{
  69 //    "total"    : 204800,
  70 //    "current"  : 10240,
  71 //    "rate"     : 1024,
  72 //    "message"  : "10kB / 200kB",
  73 //    "done"     : false
  74 //}
  75 ```
  76
  77 ## Standard Handlers
  78
  79 `Zend\ProgressBar\Upload` comes with the following three upload handlers:
  80
  81 > -   \[Zend\\Progressbar\\Upload\\ApcProgress\](zend.progress-bar.upload.apc-progress)
  82 - \[Zend\\ProgressBar\\Upload\\SessionProgress\](zend.progress-bar.upload.session-progress)
  83 - \[Zend\\Progressbar\\Upload\\UploadProgress\](zend.progress-bar.upload.upload-progress)
  84
  85 orphan
  86
  87 ### APC Progress Handler
  88
  89 The `Zend\ProgressBar\Upload\ApcProgress` handler uses the [APC
  90 extension](http://php.net/manual/en/book.apc.php) for tracking upload progress.
  91
  92 > ## Note
  93 The [APC extension](http://php.net/manual/en/book.apc.php) is required.
  94
  95 This handler is best used with the
  96 \[FormFileApcProgress\](zend.form.view.helper.form-file-apc-progress) view helper, to provide a
  97 hidden element with the upload progress identifier.
  98
  99 orphan
 100
 101 ### Session Progress Handler
 102
 103 The `Zend\ProgressBar\Upload\SessionProgress` handler uses the PHP 5.4 [Session
 104 Progress](http://php.net/manual/en/session.upload-progress.php) feature for tracking upload
 105 progress.
 106
 107 > ## Note
 108 PHP 5.4 is required.
 109
 110 This handler is best used with the
 111 \[FormFileSessionProgress\](zend.form.view.helper.form-file-session-progress) view helper, to
 112 provide a hidden element with the upload progress identifier.
 113
 114 orphan
 115
 116 ### Upload Progress Handler
 117
 118 The `Zend\ProgressBar\Upload\UploadProgress` handler uses the [PECL Uploadprogress
 119 extension](http://pecl.php.net/package/uploadprogress) for tracking upload progress.
 120
 121 > ## Note
 122 The [PECL Uploadprogress extension](http://pecl.php.net/package/uploadprogress) is required.
 123
 124 This handler is best used with the
 125 \[FormFileUploadProgress\](zend.form.view.helper.form-file-upload-progress) view helper, to provide
 126 a hidden element with the upload progress identifier.