| blob | c7d83da8af2fd8cab0eda5966f83955953f38a95 |
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!-- Reviewed: no -->
3 <sect1 id="zend.file.transfer.introduction">
4 <title>Zend_File_Transfer</title>
6 <para>
7 <classname>Zend_File_Transfer</classname> provides extensive support for file uploads and
8 downloads. It comes with built-in validators for files plus functionality to change files
9 with filters. Protocol adapters allow <classname>Zend_File_Transfer</classname> to expose
10 the same <acronym>API</acronym> for transport protocols like <acronym>HTTP</acronym>, FTP,
11 WEBDAV and more.
12 </para>
14 <note>
15 <title>Limitation</title>
17 <para>
18 The current implementation of <classname>Zend_File_Transfer</classname> is limited to
19 <acronym>HTTP</acronym> Post Uploads. Other adapters supporting downloads and other
20 protocols will be added in future releases. Unimplemented methods will throw an
21 exception. For now, you should use
22 <classname>Zend_File_Transfer_Adapter_Http</classname> directly. As soon as
23 there are multiple adapters available you can use a common interface.
24 </para>
25 </note>
27 <note>
28 <title>Forms</title>
30 <para>
31 When you are using <classname>Zend_Form</classname> you should use the
32 <acronym>API</acronym>s provided by <classname>Zend_Form</classname> and not
33 <classname>Zend_File_Transfer</classname> directly. The file transfer support in
34 <classname>Zend_Form</classname> is implemented with
35 <classname>Zend_File_Transfer</classname>, so the information in this chapter may
36 be useful for advanced users of <classname>Zend_Form</classname>.
37 </para>
38 </note>
40 <para>
41 The usage of <classname>Zend_File_Transfer</classname> is relatively simple. It consists of
42 two parts. The <acronym>HTTP</acronym> form does the upload, while the
43 <classname>Zend_File_Transfer</classname> handles the uploaded files. See the following
44 example:
45 </para>
47 <example id="zend.file.transfer.introduction.example">
48 <title>Simple Form for Uploading Files</title>
50 <para>
51 This example illustrates basic file uploading.
52 The first part is the file form. In our example there is one file to upload.
53 </para>
55 <programlisting language="xml"><![CDATA[
56 <form enctype="multipart/form-data" action="/file/upload" method="POST">
57 <input type="hidden" name="MAX_FILE_SIZE" value="100000" />
58 Choose a file to upload: <input name="uploadedfile" type="file" />
59 <br />
60 <input type="submit" value="Upload File" />
61 </form>
62 ]]></programlisting>
64 <para>
65 For convenience, you can use <link
66 linkend="zend.form.standardElements.file">Zend_Form_Element_File</link> instead of
67 building the <acronym>HTML</acronym> manually.
68 </para>
70 <para>
71 The next step is to create the receiver of the upload. In our example the receiver is
72 located at <filename>/file/upload</filename>. So next we will create the 'file'
73 controller and the <methodname>upload()</methodname> action.
74 </para>
76 <programlisting language="php"><![CDATA[
77 $adapter = new Zend_File_Transfer_Adapter_Http();
79 $adapter->setDestination('C:\temp');
81 if (!$adapter->receive()) {
82 $messages = $adapter->getMessages();
83 echo implode("\n", $messages);
84 }
85 ]]></programlisting>
87 <para>
88 This code listing demonstrates the simplest usage of
89 <classname>Zend_File_Transfer</classname>. A local destination is set with the
90 <methodname>setDestination()</methodname> method, then the
91 <methodname>receive()</methodname> method is called. if there are any upload errors, an
92 error will be returned.
93 </para>
94 </example>
96 <note>
97 <title>Attention</title>
99 <para>
100 This example is suitable only for demonstrating the basic <acronym>API</acronym> of
101 <classname>Zend_File_Transfer</classname>. You should <emphasis>never</emphasis> use
102 this code listing in a production environment, because severe security issues may be
103 introduced. You should always use validators to increase security.
104 </para>
105 </note>
107 <sect2 id="zend.file.transfer.introduction.adapters">
108 <title>Supported Adapters for Zend_File_Transfer</title>
110 <para>
111 <classname>Zend_File_Transfer</classname> is designed to support a variety of adapters
112 and transfer directions. With <classname>Zend_File_Transfer</classname> you can upload,
113 download and even forward (upload one adapter and download with another adapter at the
114 same time) files.
115 </para>
116 </sect2>
118 <sect2 id="zend.file.transfer.introduction.options">
119 <title>Options for Zend_File_Transfer</title>
121 <para>
122 <classname>Zend_File_Transfer</classname> and its adapters support different options.
123 You can set all options either by passing them to the constructor or by calling
124 <methodname>setOptions($options)</methodname>. <methodname>getOptions()</methodname>
125 will return the options that are currently set. The following is a list of all supported
126 options.
127 </para>
129 <itemizedlist>
130 <listitem>
131 <para>
132 <emphasis>ignoreNoFile</emphasis>: If this option is set to
133 <constant>TRUE</constant>, all validators will ignore files that have not been
134 uploaded by the form. The default value is <constant>FALSE</constant> which
135 results in an error if no files were specified.
136 </para>
137 </listitem>
138 </itemizedlist>
139 </sect2>
141 <sect2 id="zend.file.transfer.introduction.checking">
142 <title>Checking Files</title>
144 <para>
145 <classname>Zend_File_Transfer</classname> has several methods that check for various
146 states of the specified file. These are useful if you must process files after they have
147 been uploaded. These methods include:
148 </para>
150 <itemizedlist>
151 <listitem>
152 <para>
153 <emphasis>isValid($files = null)</emphasis>: This method will check if the
154 given files are valid, based on the validators that are attached to the files.
155 If no files are specified, all files will be checked. You can call
156 <methodname>isValid()</methodname> before calling
157 <methodname>receive()</methodname>; in this case,
158 <methodname>receive()</methodname> will not call
159 <methodname>isValid()</methodname> internally again when receiving the file.
160 </para>
161 </listitem>
163 <listitem>
164 <para>
165 <emphasis>isUploaded($files = null)</emphasis>: This method will check if the
166 specified files have been uploaded by the user. This is useful when you have
167 defined one or more optional files. When no files are specified, all files will
168 be checked.
169 </para>
170 </listitem>
172 <listitem>
173 <para>
174 <emphasis>isReceived($files = null)</emphasis>: This method will check if the
175 given files have already been received. When no files are specified, all files
176 will be checked.
177 </para>
178 </listitem>
179 </itemizedlist>
181 <example id="zend.file.transfer.introduction.checking.example">
182 <title>Checking Files</title>
184 <programlisting language="php"><![CDATA[
185 $upload = new Zend_File_Transfer();
187 // Returns all known internal file information
188 $files = $upload->getFileInfo();
190 foreach ($files as $file => $info) {
191 // file uploaded ?
192 if (!$upload->isUploaded($file)) {
193 print "Why havn't you uploaded the file ?";
194 continue;
195 }
197 // validators are ok ?
198 if (!$upload->isValid($file)) {
199 print "Sorry but $file is not what we wanted";
200 continue;
201 }
202 }
204 $upload->receive();
205 ]]></programlisting>
206 </example>
207 </sect2>
209 <sect2 id="zend.file.transfer.introduction.informations">
210 <title>Additional File Informations</title>
212 <para>
213 <classname>Zend_File_Transfer</classname> can return additional information on files.
214 The following methods are available:
215 </para>
217 <itemizedlist>
218 <listitem>
219 <para>
220 <emphasis>getFileName($file = null, $path = true)</emphasis>: This method
221 will return the real file name of a transferred file.
222 </para>
223 </listitem>
225 <listitem>
226 <para>
227 <emphasis>getFileInfo($file = null)</emphasis>: This method will return all
228 internal information for the given file.
229 </para>
230 </listitem>
232 <listitem>
233 <para>
234 <emphasis>getFileSize($file = null)</emphasis>: This method will return the
235 real filesize for the given file.
236 </para>
237 </listitem>
239 <listitem>
240 <para>
241 <emphasis>getHash($hash = 'crc32', $files = null)</emphasis>: This method
242 returns a hash of the content of a given transferred file.
243 </para>
244 </listitem>
246 <listitem>
247 <para>
248 <emphasis>getMimeType($files = null)</emphasis>: This method returns the
249 mimetype of a given transferred file.
250 </para>
251 </listitem>
252 </itemizedlist>
254 <para>
255 <methodname>getFileName()</methodname> accepts the name of the element as first
256 parameter. If no name is given, all known filenames will be returned in an array. If the
257 file is a multifile, you will also get an array. If there is only a single file a string
258 will be returned.
259 </para>
261 <para>
262 By default file names will be returned with the complete path. If you only need the file
263 name without path, you can set the second parameter, <varname>$path</varname>, which
264 will truncate the file path when set to <constant>FALSE</constant>.
265 </para>
267 <example id="zend.file.transfer.introduction.informations.example1">
268 <title>Getting the Filename</title>
270 <programlisting language="php"><![CDATA[
271 $upload = new Zend_File_Transfer();
272 $upload->receive();
274 // Returns the file names from all files
275 $names = $upload->getFileName();
277 // Returns the file names from the 'foo' form element
278 $names = $upload->getFileName('foo');
279 ]]></programlisting>
280 </example>
282 <note>
283 <para>
284 Note that the file name can change after you receive the file, because all filters
285 will be applied once the file is received. So you should always call
286 <methodname>getFileName()</methodname> after the files have been received.
287 </para>
288 </note>
290 <para>
291 <methodname>getFileSize()</methodname> returns per default the real filesize in SI
292 notation which means you will get <emphasis>2kB</emphasis> instead of
293 <emphasis>2048</emphasis>. If you need only the plain size set the
294 <property>useByteString</property> option to <constant>FALSE</constant>.
295 </para>
297 <example id="zend.file.transfer.introduction.informations.example.getfilesize">
298 <title>Getting the size of a file</title>
300 <programlisting language="php"><![CDATA[
301 $upload = new Zend_File_Transfer();
302 $upload->receive();
304 // Returns the sizes from all files as array if more than one file was uploaded
305 $size = $upload->getFileSize();
307 // Switches of the SI notation to return plain numbers
308 $upload->setOption(array('useByteString' => false));
309 $size = $upload->getFileSize();
310 ]]></programlisting>
311 </example>
313 <note>
314 <title>Client given filesize</title>
316 <para>
317 Note that the filesize which is given by the client is not seen as save input.
318 Therefor the real size of the file will be detected and returned instead of the
319 filesize sent by the client.
320 </para>
321 </note>
323 <para>
324 <methodname>getHash()</methodname> accepts the name of a hash algorithm as first
325 parameter. For a list of known algorithms refer to
326 <ulink url="http://php.net/hash_algos">PHP's hash_algos method</ulink>. If you don't
327 specify an algorithm, the <emphasis>crc32</emphasis> algorithm will be used by default.
328 </para>
330 <example id="zend.file.transfer.introduction.informations.example2">
331 <title>Getting the hash of a file</title>
333 <programlisting language="php"><![CDATA[
334 $upload = new Zend_File_Transfer();
335 $upload->receive();
337 // Returns the hashes from all files as array if more than one file was uploaded
338 $hash = $upload->getHash('md5');
340 // Returns the hash for the 'foo' form element
341 $names = $upload->getHash('crc32', 'foo');
342 ]]></programlisting>
343 </example>
345 <note>
346 <title>Return value</title>
348 <para>
349 Note that if the given file or form name contains more than one file, the returned
350 value will be an array.
351 </para>
352 </note>
354 <para>
355 <methodname>getMimeType()</methodname> returns the mimetype of a file. If more than one
356 file was uploaded it returns an array, otherwise a string.
357 </para>
359 <example id="zend.file.transfer.introduction.informations.getmimetype">
360 <title>Getting the mimetype of a file</title>
362 <programlisting language="php"><![CDATA[
363 $upload = new Zend_File_Transfer();
364 $upload->receive();
366 $mime = $upload->getMimeType();
368 // Returns the mimetype for the 'foo' form element
369 $names = $upload->getMimeType('foo');
370 ]]></programlisting>
371 </example>
373 <note>
374 <title>Client given mimetype</title>
376 <para>
377 Note that the mimetype which is given by the client is not seen as save input.
378 Therefor the real mimetype of the file will be detected and returned instead of the
379 mimetype sent by the client.
380 </para>
381 </note>
383 <warning>
384 <title>Possible exception</title>
386 <para>
387 Note that this method uses the fileinfo extension if it is available. If this
388 extension can not be found, it uses the mimemagic extension. When no extension was
389 found it raises an exception.
390 </para>
391 </warning>
393 <warning>
394 <title>Original data within $_FILES</title>
396 <para>
397 Due to security reasons also the original data within $_FILES will be overridden
398 as soon as <classname>Zend_File_Transfer</classname> is initiated. When you want
399 to omit this behaviour and have the original data simply set the
400 <property>detectInfos</property> option to <constant>FALSE</constant> at initiation.
401 </para>
403 <para>
404 This option will have no effect after you initiated
405 <classname>Zend_File_Transfer</classname>.
406 </para>
407 </warning>
408 </sect2>
410 <sect2 id="zend.file.transfer.introduction.uploadprogress">
411 <title>Progress for file uploads</title>
413 <para>
414 <classname>Zend_File_Transfer</classname> can give you the actual state of a fileupload
415 in progress. To use this feature you need either the <acronym>APC</acronym> extension
416 which is provided with most default <acronym>PHP</acronym> installations, or the
417 <classname>UploadProgress</classname> extension. Both extensions are detected and used
418 automatically. To be able to get the progress you need to meet some prerequisites.
419 </para>
421 <para>
422 First, you need to have either <acronym>APC</acronym> or
423 <classname>UploadProgress</classname> to be enabled. Note that you can disable this
424 feature of <acronym>APC</acronym> within your <filename>php.ini</filename>.
425 </para>
427 <para>
428 Second, you need to have the proper hidden fields added in the form which sends the
429 files. When you use <classname>Zend_Form_Element_File</classname> this hidden fields are
430 automatically added by <classname>Zend_Form</classname>.
431 </para>
433 <para>
434 When the above two points are provided then you are able to get the actual progress of
435 the file upload by using the <methodname>getProgress()</methodname> method. Actually
436 there are 2 official ways to handle this.
437 </para>
439 <sect3 id="zend.file.transfer.introduction.uploadprogress.progressadapter">
440 <title>Using a progressbar adapter</title>
442 <para>
443 You can use the convinient <emphasis>Zend_ProgressBar</emphasis> to get the actual
444 progress and can display it in a simple manner to your user.
445 </para>
447 <para>
448 To archive this, you have to add the wished
449 <emphasis>Zend_ProgressBar_Adapter</emphasis> to
450 <methodname>getProgress()</methodname> when you are calling it the first time. For
451 details about the right adapter to use, look into the chapter <link
452 linkend="zend.progressbar.adapters">Zend_ProgressBar Standard Adapters</link>.
453 </para>
455 <example id="zend.file.transfer.introduction.uploadprogress.progressadapter.example1">
456 <title>Using the progressbar adapter to retrieve the actual state</title>
458 <programlisting language="php"><![CDATA[
459 $adapter = new Zend_ProgressBar_Adapter_Console();
460 $upload = Zend_File_Transfer_Adapter_Http::getProgress($adapter);
462 $upload = null;
463 while (!$upload['done']) {
464 $upload = Zend_File_Transfer_Adapter_Http:getProgress($upload);
465 }
466 ]]></programlisting>
467 </example>
469 <para>
470 The complete handling is done by <methodname>getProgress()</methodname> for you in
471 the background.
472 </para>
473 </sect3>
475 <sect3 id="zend.file.transfer.introduction.uploadprogress.manually">
476 <title>Using getProgress() manually</title>
478 <para>
479 You can also work manually with <methodname>getProgress()</methodname> without the
480 usage of <classname>Zend_ProgressBar</classname>.
481 </para>
483 <para>
484 Call <methodname>getProgress()</methodname> without settings. It will return you an
485 array with several keys. They differ according to the used <acronym>PHP</acronym>
486 extension. But the following keys are given independently of the extension:
487 </para>
489 <itemizedlist>
490 <listitem>
491 <para>
492 <emphasis>id</emphasis>: The ID of this upload. This ID identifies the
493 upload within the extension. It is filled automatically. You should never
494 change or give this value yourself.
495 </para>
496 </listitem>
498 <listitem>
499 <para>
500 <emphasis>total</emphasis>: The total filesize of the uploaded files in
501 bytes as integer.
502 </para>
503 </listitem>
505 <listitem>
506 <para>
507 <emphasis>current</emphasis>: The current uploaded filesize in bytes
508 as integer.
509 </para>
510 </listitem>
512 <listitem>
513 <para>
514 <emphasis>rate</emphasis>: The average upload speed in bytes per second
515 as integer.
516 </para>
517 </listitem>
519 <listitem>
520 <para>
521 <emphasis>done</emphasis>: Returns <constant>TRUE</constant> when the upload
522 is finished and <constant>FALSE</constant> otherwise.
523 </para>
524 </listitem>
526 <listitem>
527 <para>
528 <emphasis>message</emphasis>: The actual message. Either the progress as
529 text in the form <emphasis>10kB / 200kB</emphasis>, or a helpful message
530 in the case of a problem. Problems could be, that there is no upload in
531 progress, that there was a failure while retrieving the data for the
532 progress, or that the upload has been canceled.
533 </para>
534 </listitem>
536 <listitem>
537 <para>
538 <emphasis>progress</emphasis>: This optional key takes a instance of
539 <classname>Zend_ProgressBar_Adapter</classname> or
540 <classname>Zend_ProgressBar</classname> and allows to get the actual upload
541 state within a progressbar.
542 </para>
543 </listitem>
545 <listitem>
546 <para>
547 <emphasis>session</emphasis>: This optional key takes the name of a session
548 namespace which will be used within <classname>Zend_ProgressBar</classname>.
549 When this key is not given it defaults to
550 <classname>Zend_File_Transfer_Adapter_Http_ProgressBar</classname>.
551 </para>
552 </listitem>
553 </itemizedlist>
555 <para>
556 All other returned keys are provided directly from the extensions and will not be
557 checked.
558 </para>
560 <para>
561 The following example shows a possible manual usage:
562 </para>
564 <example id="zend.file.transfer.introduction.uploadprogress.manually.example1">
565 <title>Manual usage of the file progress</title>
567 <programlisting language="php"><![CDATA[
568 $upload = Zend_File_Transfer_Adapter_Http::getProgress();
570 while (!$upload['done']) {
571 $upload = Zend_File_Transfer_Adapter_Http:getProgress($upload);
572 print "\nActual progress:".$upload['message'];
573 // do whatever you need
574 }
575 ]]></programlisting>
576 </example>
577 </sect3>
578 </sect2>
579 </sect1>
580 <!--
581 vim:se ts=4 sw=4 tw=80 et:
582 -->