| blob | 10add4370af4ec844add8c3a934a73a8787bd207 |
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!-- Reviewed: no -->
3 <sect1 id="zend.file.transfer.validators">
4 <title>Validators for Zend_File_Transfer</title>
6 <para>
7 <classname>Zend_File_Transfer</classname> is delivered with several file-related validators
8 which can be used to increase security and prevent possible attacks. Note that these
9 validators are only as effective as how effectively you apply them. All validators provided
10 with <classname>Zend_File_Transfer</classname> can be found in the
11 <classname>Zend_Validator</classname> component and are named
12 <classname>Zend_Validate_File_*</classname>. The following validators are available:
13 </para>
15 <itemizedlist>
16 <listitem>
17 <para>
18 <classname>Count</classname>: This validator checks for the number of files. A
19 minimum and maximum range can be specified. An error will be thrown if either limit
20 is crossed.
21 </para>
22 </listitem>
24 <listitem>
25 <para>
26 <classname>Crc32</classname>: This validator checks for the crc32 hash value of the
27 content from a file. It is based on the <classname>Hash</classname> validator and
28 provides a convenient and simple validator that only supports Crc32.
29 </para>
30 </listitem>
32 <listitem>
33 <para>
34 <classname>ExcludeExtension</classname>: This validator checks the extension of
35 files. It will throw an error when an given file has a defined extension. With this
36 validator, you can exclude defined extensions from being validated.
37 </para>
38 </listitem>
40 <listitem>
41 <para>
42 <classname>ExcludeMimeType</classname>: This validator validates the
43 <acronym>MIME</acronym> type of files. It can also validate <acronym>MIME</acronym>
44 types and will throw an error if the <acronym>MIME</acronym> type of specified file
45 matches.
46 </para>
47 </listitem>
49 <listitem>
50 <para>
51 <classname>Exists</classname>: This validator checks for the existence of files. It
52 will throw an error when a specified file does not exist.
53 </para>
54 </listitem>
56 <listitem>
57 <para>
58 <classname>Extension</classname>: This validator checks the extension of files. It
59 will throw an error when a specified file has an undefined extension.
60 </para>
61 </listitem>
63 <listitem>
64 <para>
65 <classname>FilesSize</classname>: This validator checks the size of validated files.
66 It remembers internally the size of all checked files and throws an error when the
67 sum of all specified files exceed the defined size. It also provides minimum and
68 maximum values.
69 </para>
70 </listitem>
72 <listitem>
73 <para>
74 <classname>ImageSize</classname>: This validator checks the size of image. It
75 validates the width and height and enforces minimum and maximum dimensions.
76 </para>
77 </listitem>
79 <listitem>
80 <para>
81 <classname>IsCompressed</classname>: This validator checks whether the file is
82 compressed. It is based on the <classname>MimeType</classname> validator and
83 validates for compression archives like zip or arc. You can also limit it to other
84 archives.
85 </para>
86 </listitem>
88 <listitem>
89 <para>
90 <classname>IsImage</classname>: This validator checks whether the file is an image.
91 It is based on the <classname>MimeType</classname> validator and validates for image
92 files like jpg or gif. You can also limit it to other image types.
93 </para>
94 </listitem>
96 <listitem>
97 <para>
98 <classname>Hash</classname>: This validator checks the hash value of the content
99 from a file. It supports multiple algorithms.
100 </para>
101 </listitem>
103 <listitem>
104 <para>
105 <classname>Md5</classname>: This validator checks for the md5 hash value of the
106 content from a file. It is based on the <classname>Hash</classname> validator and
107 provides a convenient and simple validator that only supports Md5.
108 </para>
109 </listitem>
111 <listitem>
112 <para>
113 <classname>MimeType</classname>: This validator validates the
114 <acronym>MIME</acronym> type of files. It can also validate <acronym>MIME</acronym>
115 types and will throw an error if the <acronym>MIME</acronym> type of a specified
116 file does not match.
117 </para>
118 </listitem>
120 <listitem>
121 <para>
122 <classname>NotExists</classname>: This validator checks for the existence of files.
123 It will throw an error when an given file does exist.
124 </para>
125 </listitem>
127 <listitem>
128 <para>
129 <classname>Sha1</classname>: This validator checks for the sha1 hash value of the
130 content from a file. It is based on the <classname>Hash</classname> validator and
131 provides a convenient and simple validator that only supports sha1.
132 </para>
133 </listitem>
135 <listitem>
136 <para>
137 <classname>Size</classname>: This validator is able to check files for its file
138 size. It provides a minimum and maximum size range and will throw an error when
139 either of these thesholds are crossed.
140 </para>
141 </listitem>
143 <listitem>
144 <para>
145 <classname>Upload</classname>: This validator is internal. It checks if an upload
146 has resulted in an error. You must not set it, as it's automatically set by
147 <classname>Zend_File_Transfer</classname> itself. So you do not use this validator
148 directly. You should only know that it exists.
149 </para>
150 </listitem>
152 <listitem>
153 <para>
154 <classname>WordCount</classname>: This validator is able to check the number of
155 words within files. It provides a minimum and maximum count and will throw an error
156 when either of these thresholds are crossed.
157 </para>
158 </listitem>
159 </itemizedlist>
161 <sect2 id="zend.file.transfer.validators.usage">
162 <title>Using Validators with Zend_File_Transfer</title>
164 <para>
165 Putting validators to work is quite simple. There are several methods for adding and
166 manipulating validators:
167 </para>
169 <itemizedlist>
170 <listitem>
171 <para>
172 <methodname>isValid($files = null)</methodname>: Checks the specified files
173 using all validators. <varname>$files</varname> may be either a real filename,
174 the element's name or the name of the temporary file.
175 </para>
176 </listitem>
178 <listitem>
179 <para>
180 <methodname>addValidator($validator, $breakChainOnFailure, $options = null,
181 $files = null)</methodname>: Adds the specified validator to the validator
182 stack (optionally only to the file(s) specified).
183 <varname>$validator</varname> may be either an actual validator
184 instance or a short name specifying the validator type (e.g., 'Count').
185 </para>
186 </listitem>
188 <listitem>
189 <para>
190 <methodname>addValidators(array $validators, $files =
191 null)</methodname>: Adds the specified validators to the stack of
192 validators. Each entry may be either a validator
193 type/options pair or an array with the key 'validator'
194 specifying the validator. All other options will be
195 considered validator options for instantiation.
196 </para>
197 </listitem>
199 <listitem>
200 <para>
201 <methodname>setValidators(array $validators, $files =
202 null)</methodname>: Overwrites any existing validators with
203 the validators specified. The validators should follow the
204 syntax for <methodname>addValidators()</methodname>.
205 </para>
206 </listitem>
208 <listitem>
209 <para>
210 <methodname>hasValidator($name)</methodname>: Indicates whether a
211 validator has been registered.
212 </para>
213 </listitem>
215 <listitem>
216 <para>
217 <methodname>getValidator($name)</methodname>: Returns a previously
218 registered validator.
219 </para>
220 </listitem>
222 <listitem>
223 <para>
224 <methodname>getValidators($files = null)</methodname>: Returns
225 registered validators. If <varname>$files</varname> is specified,
226 returns validators for that particular file or set of
227 files.
228 </para>
229 </listitem>
231 <listitem>
232 <para>
233 <methodname>removeValidator($name)</methodname>: Removes a previously
234 registered validator.
235 </para>
236 </listitem>
238 <listitem>
239 <para>
240 <methodname>clearValidators()</methodname>: Clears all
241 registered validators.
242 </para>
243 </listitem>
244 </itemizedlist>
246 <example id="zend.file.transfer.validators.usage.example">
247 <title>Add Validators to a File Transfer Object</title>
249 <programlisting language="php"><![CDATA[
250 $upload = new Zend_File_Transfer();
252 // Set a file size with 20000 bytes
253 $upload->addValidator('Size', false, 20000);
255 // Set a file size with 20 bytes minimum and 20000 bytes maximum
256 $upload->addValidator('Size', false, array('min' => 20, 'max' => 20000));
258 // Set a file size with 20 bytes minimum and 20000 bytes maximum and
259 // a file count in one step
260 $upload->setValidators(array(
261 'Size' => array('min' => 20, 'max' => 20000),
262 'Count' => array('min' => 1, 'max' => 3),
263 ));
264 ]]></programlisting>
265 </example>
267 <example id="zend.file.transfer.validators.usage.exampletwo">
268 <title>Limit Validators to Single Files</title>
270 <para>
271 <methodname>addValidator()</methodname>, <methodname>addValidators()</methodname>,
272 and <methodname>setValidators()</methodname> each accept a final
273 <varname>$files</varname> argument. This argument can be used to
274 specify a particular file or array of files on which to set the
275 given validator.
276 </para>
278 <programlisting language="php"><![CDATA[
279 $upload = new Zend_File_Transfer();
281 // Set a file size with 20000 bytes and limits it only to 'file2'
282 $upload->addValidator('Size', false, 20000, 'file2');
283 ]]></programlisting>
284 </example>
286 <para>
287 Normally, you should use the <methodname>addValidators()</methodname> method, which
288 can be called multiple times.
289 </para>
291 <example id="zend.file.transfer.validators.usage.examplemultiple">
292 <title>Add Multiple Validators</title>
294 <para>
295 Often it's simpler just to call <methodname>addValidator()</methodname> multiple
296 times with one call for each validator. This also increases readability and makes
297 your code more maintainable. All methods provide a fluent interface, so you can
298 couple the calls as shown below:
299 </para>
301 <programlisting language="php"><![CDATA[
302 $upload = new Zend_File_Transfer();
304 // Set a file size with 20000 bytes
305 $upload->addValidator('Size', false, 20000)
306 ->addValidator('Count', false, 2)
307 ->addValidator('Filessize', false, 25000);
308 ]]></programlisting>
309 </example>
311 <note>
312 <para>
313 Note that setting the same validator
314 multiple times is allowed, but doing so can lead to issues when using
315 different options for the same validator.
316 </para>
317 </note>
319 <para>
320 Last but not least, you can simply check the files using
321 <methodname>isValid()</methodname>.
322 </para>
324 <example id="zend.file.transfer.validators.usage.exampleisvalid">
325 <title>Validate the Files</title>
327 <para>
328 <methodname>isValid()</methodname> accepts the file name of the uploaded or
329 downloaded file, the temporary file name and or the name of the form element. If
330 no parameter or null is given all files will be validated
331 </para>
333 <programlisting language="php"><![CDATA[
334 $upload = new Zend_File_Transfer();
336 // Set a file size with 20000 bytes
337 $upload->addValidator('Size', false, 20000)
338 ->addValidator('Count', false, 2)
339 ->addValidator('Filessize', false, 25000);
341 if ($upload->isValid()) {
342 print "Validation failure";
343 }
344 ]]></programlisting>
345 </example>
347 <note>
348 <para>
349 Note that <methodname>isValid()</methodname> will be called automatically when you
350 receive the files and have not called it previously.
351 </para>
352 </note>
354 <para>
355 When validation has failed it is a good idea to get information about the
356 problems found. To get this information, you can use the methods
357 <methodname>getMessages()</methodname> which returns all validation messages as array,
358 <methodname>getErrors()</methodname> which returns all error codes, and
359 <methodname>hasErrors()</methodname> which returns <constant>TRUE</constant> as soon as
360 a validation error has been found.
361 </para>
362 </sect2>
364 <sect2 id="zend.file.transfer.validators.count">
365 <title>Count Validator</title>
367 <para>
368 The <classname>Count</classname> validator checks for the number of files which are
369 provided. It supports the following option keys:
370 </para>
372 <itemizedlist>
373 <listitem>
374 <para>
375 <property>min</property>: Sets the minimum number of files to transfer.
376 </para>
378 <note>
379 <para>
380 When using this option you must give the minimum number of files when
381 calling this validator the first time; otherwise you will get an error in
382 return.
383 </para>
384 </note>
386 <para>
387 With this option you can define the minimum number of files you expect to
388 receive.
389 </para>
390 </listitem>
392 <listitem>
393 <para>
394 <property>max</property>: Sets the maximum number of files to transfer.
395 </para>
397 <para>
398 With this option you can limit the number of files which are accepted but also
399 detect a possible attack when more files are given than defined in your form.
400 </para>
401 </listitem>
402 </itemizedlist>
404 <para>
405 If you initiate this validator with a string or integer, the value will be used as
406 <property>max</property>. Or you can also use the methods
407 <methodname>setMin()</methodname> and <methodname>setMax()</methodname> to set both
408 options afterwards and <methodname>getMin()</methodname> and
409 <methodname>getMax()</methodname> to retrieve the actual set values.
410 </para>
412 <example id="zend.file.transfer.validators.count.example">
413 <title>Using the Count Validator</title>
415 <programlisting language="php"><![CDATA[
416 $upload = new Zend_File_Transfer();
418 // Limit the amount of files to maximum 2
419 $upload->addValidator('Count', false, 2);
421 // Limit the amount of files to maximum 5 and minimum 1 file
422 $upload->addValidator('Count', false, array('min' =>1, 'max' => 5));
423 ]]></programlisting>
424 </example>
426 <note>
427 <para>
428 Note that this validator stores the number of checked files internally. The file
429 which exceeds the maximum will be returned as error.
430 </para>
431 </note>
432 </sect2>
434 <sect2 id="zend.file.transfer.validators.crc32">
435 <title>Crc32 Validator</title>
437 <para>
438 The <classname>Crc32</classname> validator checks the content of a transferred file by
439 hashing it. This validator uses the hash extension from <acronym>PHP</acronym> with the
440 crc32 algorithm. It supports the following options:
441 </para>
443 <itemizedlist>
444 <listitem>
445 <para>
446 <property>*</property>: Sets any key or use a numeric array. The values will be
447 used as hash to validate against.
448 </para>
450 <para>
451 You can set multiple hashes by using different keys. Each will be checked and
452 the validation will fail only if all values fail.
453 </para>
454 </listitem>
455 </itemizedlist>
457 <example id="zend.file.transfer.validators.crc32.example">
458 <title>Using the Crc32 Validator</title>
460 <programlisting language="php"><![CDATA[
461 $upload = new Zend_File_Transfer();
463 // Checks whether the content of the uploaded file has the given hash
464 $upload->addValidator('Crc32', false, '3b3652f');
466 // Limits this validator to two different hashes
467 $upload->addValidator('Crc32', false, array('3b3652f', 'e612b69'));
468 ]]></programlisting>
469 </example>
470 </sect2>
472 <sect2 id="zend.file.transfer.validators.excludeextension">
473 <title>ExcludeExtension Validator</title>
475 <para>
476 The <classname>ExcludeExtension</classname> validator checks the file extension of the
477 specified files. It supports the following options:
478 </para>
480 <itemizedlist>
481 <listitem>
482 <para>
483 <property>*</property>: Sets any key or use a numeric array. The values will be
484 used to check whether the given file does not use this file extension.
485 </para>
486 </listitem>
488 <listitem>
489 <para>
490 <property>case</property>: Sets a boolean indicating whether validation should
491 be case-sensitive. The default is not case sensitive. Note that this key can be
492 applied to for all available extensions.
493 </para>
494 </listitem>
495 </itemizedlist>
497 <para>
498 This validator accepts multiple extensions, either as a comma-delimited string, or as
499 an array. You may also use the methods <methodname>setExtension()</methodname>,
500 <methodname>addExtension()</methodname>, and <methodname>getExtension()</methodname>
501 to set and retrieve extensions.
502 </para>
504 <para>
505 In some cases it is useful to match in a case-sensitive fashion. So the constructor
506 allows a second parameter called <varname>$case</varname> which, if set to
507 <constant>TRUE</constant>, validates the extension by comparing it with the specified
508 values in a case-sensitive fashion.
509 </para>
511 <example id="zend.file.transfer.validators.excludeextension.example">
512 <title>Using the ExcludeExtension Validator</title>
514 <programlisting language="php"><![CDATA[
515 $upload = new Zend_File_Transfer();
517 // Do not allow files with extension php or exe
518 $upload->addValidator('ExcludeExtension', false, 'php,exe');
520 // Do not allow files with extension php or exe, but use array notation
521 $upload->addValidator('ExcludeExtension', false, array('php', 'exe'));
523 // Check in a case-sensitive fashion
524 $upload->addValidator('ExcludeExtension',
525 false,
526 array('php', 'exe', 'case' => true));
527 $upload->addValidator('ExcludeExtension',
528 false,
529 array('php', 'exe', 'case' => true));
530 ]]></programlisting>
531 </example>
533 <note>
534 <para>
535 Note that this validator only checks the file extension. It does not check the
536 file's <acronym>MIME</acronym> type.
537 </para>
538 </note>
539 </sect2>
541 <sect2 id="zend.file.transfer.validators.excludemimetype">
542 <title>ExcludeMimeType Validator</title>
544 <para>
545 The <classname>ExcludeMimeType</classname> validator checks the <acronym>MIME</acronym>
546 type of transferred files. It supports the following options:
547 </para>
549 <itemizedlist>
550 <listitem>
551 <para>
552 <property>*</property>: Sets any key individually or use a numeric array. Sets
553 the <acronym>MIME</acronym> type to validate against.
554 </para>
556 <para>
557 With this option you can define the <acronym>MIME</acronym> type of files that
558 are not to be accepted.
559 </para>
560 </listitem>
562 <listitem>
563 <para>
564 <property>headerCheck</property>: If set to <constant>TRUE</constant> this
565 option will check the <acronym>HTTP</acronym> Information for the file type when
566 the <emphasis>fileInfo</emphasis> or <emphasis>mimeMagic</emphasis> extensions
567 can not be found. The default value for this option is
568 <constant>FALSE</constant>.
569 </para>
570 </listitem>
571 </itemizedlist>
573 <para>
574 This validator accepts multiple <acronym>MIME</acronym> types, either as a
575 comma-delimited string, or as an array. You may also use the methods
576 <methodname>setMimeType()</methodname>, <methodname>addMimeType()</methodname>, and
577 <methodname>getMimeType()</methodname> to set and retrieve the <acronym>MIME</acronym>
578 types.
579 </para>
581 <example id="zend.file.transfer.validators.excludemimetype.example">
582 <title>Using the ExcludeMimeType Validator</title>
584 <programlisting language="php"><![CDATA[
585 $upload = new Zend_File_Transfer();
587 // Does not allow MIME type of gif images for all files
588 $upload->addValidator('ExcludeMimeType', false, 'image/gif');
590 // Does not allow MIME type of gif and jpg images for all given files
591 $upload->addValidator('ExcludeMimeType', false, array('image/gif',
592 'image/jpeg');
594 // Does not allow MIME type of the group images for all given files
595 $upload->addValidator('ExcludeMimeType', false, 'image');
596 ]]></programlisting>
597 </example>
599 <para>
600 The above example shows that it is also possible to disallow groups of
601 <acronym>MIME</acronym> types. For example, to disallow all images, just use 'image' as
602 the <acronym>MIME</acronym> type. This can be used for all groups of
603 <acronym>MIME</acronym> types like 'image', 'audio', 'video', 'text', etc.
604 </para>
606 <note>
607 <para>
608 Note that disallowing groups of <acronym>MIME</acronym> types will disallow all
609 members of this group even if this is not intentional. When you disallow 'image' you
610 will disallow all types of images like 'image/jpeg' or 'image/vasa'. When you are
611 not sure if you want to disallow all types, you should disallow only specific
612 <acronym>MIME</acronym> types instead of complete groups.
613 </para>
614 </note>
615 </sect2>
617 <sect2 id="zend.file.transfer.validators.exists">
618 <title>Exists Validator</title>
620 <para>
621 The <classname>Exists</classname> validator checks for the existence of specified
622 files. It supports the following options:
623 </para>
625 <itemizedlist>
626 <listitem>
627 <para>
628 <property>*</property>: Sets any key or use a numeric array to check if the
629 specific file exists in the given directory.
630 </para>
631 </listitem>
632 </itemizedlist>
634 <para>
635 This validator accepts multiple directories, either as a comma-delimited string, or as
636 an array. You may also use the methods <methodname>setDirectory()</methodname>,
637 <methodname>addDirectory()</methodname>, and <methodname>getDirectory()</methodname>
638 to set and retrieve directories.
639 </para>
641 <example id="zend.file.transfer.validators.exists.example">
642 <title>Using the Exists Validator</title>
644 <programlisting language="php"><![CDATA[
645 $upload = new Zend_File_Transfer();
647 // Add the temp directory to check for
648 $upload->addValidator('Exists', false, '\temp');
650 // Add two directories using the array notation
651 $upload->addValidator('Exists',
652 false,
653 array('\home\images', '\home\uploads'));
654 ]]></programlisting>
655 </example>
657 <note>
658 <para>
659 Note that this validator checks whether the specified file exists in all of the
660 given directories. The validation will fail if the file does not exist in any of the
661 given directories.
662 </para>
663 </note>
664 </sect2>
666 <sect2 id="zend.file.transfer.validators.extension">
667 <title>Extension Validator</title>
669 <para>
670 The <classname>Extension</classname> validator checks the file extension of the
671 specified files. It supports the following options:
672 </para>
674 <itemizedlist>
675 <listitem>
676 <para>
677 <property>*</property>: Sets any key or use a numeric array to check whether the
678 specified file has this file extension.
679 </para>
680 </listitem>
682 <listitem>
683 <para>
684 <property>case</property>: Sets whether validation should be done in a
685 case-sensitive fashion. The default is no case sensitivity. Note the this key is
686 used for all given extensions.
687 </para>
688 </listitem>
689 </itemizedlist>
691 <para>
692 This validator accepts multiple extensions, either as a comma-delimited string, or as an
693 array. You may also use the methods <methodname>setExtension()</methodname>,
694 <methodname>addExtension()</methodname>, and <methodname>getExtension()</methodname> to
695 set and retrieve extension values.
696 </para>
698 <para>
699 In some cases it is useful to test in a case-sensitive fashion. Therefore the
700 constructor takes a second parameter <varname>$case</varname>, which, if set to
701 <constant>TRUE</constant>, will validate the extension in a case-sensitive fashion.
702 </para>
704 <example id="zend.file.transfer.validators.extension.example">
705 <title>Using the Extension Validator</title>
707 <programlisting language="php"><![CDATA[
708 $upload = new Zend_File_Transfer();
710 // Limit the extensions to jpg and png files
711 $upload->addValidator('Extension', false, 'jpg,png');
713 // Limit the extensions to jpg and png files but use array notation
714 $upload->addValidator('Extension', false, array('jpg', 'png'));
716 // Check case sensitive
717 $upload->addValidator('Extension', false, array('mo', 'png', 'case' => true));
718 if (!$upload->isValid('C:\temp\myfile.MO')) {
719 print 'Not valid because MO and mo do not match with case sensitivity;
720 }
721 ]]></programlisting>
722 </example>
724 <note>
725 <para>
726 Note that this validator only checks the file extension. It does not check the
727 file's <acronym>MIME</acronym> type.
728 </para>
729 </note>
730 </sect2>
732 <sect2 id="zend.file.transfer.validators.filessize">
733 <title>FilesSize Validator</title>
735 <para>
736 The <classname>FilesSize</classname> validator checks for the aggregate size of all
737 transferred files. It supports the following options:
738 </para>
740 <itemizedlist>
741 <listitem>
742 <para>
743 <property>min</property>: Sets the minimum aggregate file size.
744 This option defines the minimum aggregate file size to be transferred.
745 </para>
746 </listitem>
748 <listitem>
749 <para>
750 <property>max</property>: Sets the maximum aggregate file size.
751 </para>
753 <para>
754 This option limits the aggregate file size of all transferred files, but not the
755 file size of individual files.
756 </para>
757 </listitem>
759 <listitem>
760 <para>
761 <property>bytestring</property>: Defines whether a failure is to return a
762 user-friendly number or the plain file size.
763 </para>
765 <para>
766 This option defines whether the user sees '10864' or '10MB'. The default value
767 is <constant>TRUE</constant>, so '10MB' is returned if you did not specify
768 otherwise.
769 </para>
770 </listitem>
771 </itemizedlist>
773 <para>
774 You can initialize this validator with a string, which will then be used to set the
775 <property>max</property> option. You can also use the methods
776 <methodname>setMin()</methodname> and <methodname>setMax()</methodname> to set both
777 options after construction, along with <methodname>getMin()</methodname> and
778 <methodname>getMax()</methodname> to retrieve the values that have been set previously.
779 </para>
781 <para>
782 The size itself is also accepted in SI notation as handled by most operating systems.
783 That is, instead of specifying <emphasis>20000 bytes</emphasis>,
784 <emphasis>20kB</emphasis> may be given. All file sizes are converted using 1024 as the
785 base value. The following Units are accepted: <emphasis>kB</emphasis>,
786 <emphasis>MB</emphasis>, <emphasis>GB</emphasis>, <emphasis>TB</emphasis>,
787 <emphasis>PB</emphasis> and <emphasis>EB</emphasis>. Note that 1kB is equal to 1024
788 bytes, 1MB is equal to 1024kB, and so on.
789 </para>
791 <example id="zend.file.transfer.validators.filessize.example">
792 <title>Using the FilesSize Validator</title>
794 <programlisting language="php"><![CDATA[
795 $upload = new Zend_File_Transfer();
797 // Limit the size of all files to be uploaded to 40000 bytes
798 $upload->addValidator('FilesSize', false, 40000);
800 // Limit the size of all files to be uploaded to maximum 4MB and mimimum 10kB
801 $upload->addValidator('FilesSize',
802 false,
803 array('min' => '10kB', 'max' => '4MB'));
805 // As before, but returns the plain file size instead of a user-friendly string
806 $upload->addValidator('FilesSize',
807 false,
808 array('min' => '10kB',
809 'max' => '4MB',
810 'bytestring' => false));
811 ]]></programlisting>
812 </example>
814 <note>
815 <para>
816 Note that this validator internally stores the file size of checked files. The file
817 which exceeds the size will be returned as an error.
818 </para>
819 </note>
820 </sect2>
822 <sect2 id="zend.file.transfer.validators.imagesize">
823 <title>ImageSize Validator</title>
825 <para>
826 The <classname>ImageSize</classname> validator checks the size of image files.
827 It supports the following options:
828 </para>
830 <itemizedlist>
831 <listitem>
832 <para>
833 <property>minheight</property>: Sets the minimum image height.
834 </para>
835 </listitem>
837 <listitem>
838 <para>
839 <property>maxheight</property>: Sets the maximum image height.
840 </para>
841 </listitem>
843 <listitem>
844 <para>
845 <property>minwidth</property>: Sets the minimum image width.
846 </para>
847 </listitem>
849 <listitem>
850 <para>
851 <property>maxwidth</property>: Sets the maximum image width.
852 </para>
853 </listitem>
854 </itemizedlist>
856 <para>
857 The methods <methodname>setImageMin()</methodname> and
858 <methodname>setImageMax()</methodname> also set both minimum and maximum values, while
859 the methods <methodname>getMin()</methodname> and <methodname>getMax()</methodname>
860 return the currently set values.
861 </para>
863 <para>
864 For your convenience there are also the <methodname>setImageWidth()</methodname> and
865 <methodname>setImageHeight()</methodname> methods, which set the minimum and maximum
866 height and width of the image file. They, too, have corresponding
867 <methodname>getImageWidth()</methodname> and <methodname>getImageHeight()</methodname>
868 methods to retrieve the currently set values.
869 </para>
871 <para>
872 To bypass validation of a particular dimension, the relevent option simply should not be
873 set.
874 </para>
876 <example id="zend.file.transfer.validators.imagesize.example">
877 <title>Using the ImageSize Validator</title>
879 <programlisting language="php"><![CDATA[
880 $upload = new Zend_File_Transfer();
882 // Limit the size of a image to a height of 100-200 and a width of
883 // 40-80 pixel
884 $upload->addValidator('ImageSize', false,
885 array('minwidth' => 40,
886 'maxwidth' => 80,
887 'minheight' => 100,
888 'maxheight' => 200)
889 );
891 // Reset the width for validation
892 $upload->setImageWidth(array('minwidth' => 20, 'maxwidth' => 200));
893 ]]></programlisting>
894 </example>
895 </sect2>
897 <sect2 id="zend.file.transfer.validators.iscompressed">
898 <title>IsCompressed Validator</title>
900 <para>
901 The <classname>IsCompressed</classname> validator checks if a transferred file is a
902 compressed archive, such as zip or arc. This validator is based on the
903 <classname>MimeType</classname> validator and supports the same methods and options.
904 You may also limit this validator to particular compression types with the methods
905 described there.
906 </para>
908 <example id="zend.file.transfer.validators.iscompressed.example">
909 <title>Using the IsCompressed Validator</title>
911 <programlisting language="php"><![CDATA[
912 $upload = new Zend_File_Transfer();
914 // Checks is the uploaded file is a compressed archive
915 $upload->addValidator('IsCompressed', false);
917 // Limits this validator to zip files only
918 $upload->addValidator('IsCompressed', false, array('application/zip'));
920 // Limits this validator to zip files only using simpler notation
921 $upload->addValidator('IsCompressed', false, 'zip');
922 ]]></programlisting>
923 </example>
925 <note>
926 <para>
927 Note that there is no check if you set a <acronym>MIME</acronym> type that is not a
928 archive. For example, it would be possible to define gif files to be accepted by
929 this validator. Using the 'MimeType' validator for files which are not archived will
930 result in more readable code.
931 </para>
932 </note>
933 </sect2>
935 <sect2 id="zend.file.transfer.validators.isimage">
936 <title>IsImage Validator</title>
938 <para>
939 The <classname>IsImage</classname> validator checks if a transferred file is a image
940 file, such as gif or jpeg. This validator is based on the
941 <classname>MimeType</classname> validator and supports the same methods and options.
942 You can limit this validator to particular image types with the methods described there.
943 </para>
945 <example id="zend.file.transfer.validators.isimage.example">
946 <title>Using the IsImage Validator</title>
948 <programlisting language="php"><![CDATA[
949 $upload = new Zend_File_Transfer();
951 // Checks whether the uploaded file is a image file
952 $upload->addValidator('IsImage', false);
954 // Limits this validator to gif files only
955 $upload->addValidator('IsImage', false, array('application/gif'));
957 // Limits this validator to jpeg files only using a simpler notation
958 $upload->addValidator('IsImage', false, 'jpeg');
959 ]]></programlisting>
960 </example>
962 <note>
963 <para>
964 Note that there is no check if you set a <acronym>MIME</acronym> type that is not an
965 image. For example, it would be possible to define zip files to be accepted by this
966 validator. Using the 'MimeType' validator for files which are not images will result
967 in more readable code.
968 </para>
969 </note>
970 </sect2>
972 <sect2 id="zend.file.transfer.validators.hash">
973 <title>Hash Validator</title>
975 <para>
976 The <classname>Hash</classname> validator checks the content of a transferred file by
977 hashing it. This validator uses the hash extension from <acronym>PHP</acronym>. It
978 supports the following options:
979 </para>
981 <itemizedlist>
982 <listitem>
983 <para>
984 <property>*</property>: Takes any key or use a numeric array. Sets the hash to
985 validate against.
986 </para>
988 <para>
989 You can set multiple hashes by passing them as an array. Each file is checked,
990 and the validation will fail only if all files fail validation.
991 </para>
992 </listitem>
994 <listitem>
995 <para>
996 <property>algorithm</property>: Sets the algorithm to use for hashing the
997 content.
998 </para>
1000 <para>
1001 You can set multiple algorithm by calling the <methodname>addHash()</methodname>
1002 method multiple times.
1003 </para>
1004 </listitem>
1005 </itemizedlist>
1007 <example id="zend.file.transfer.validators.hash.example">
1008 <title>Using the Hash Validator</title>
1010 <programlisting language="php"><![CDATA[
1011 $upload = new Zend_File_Transfer();
1013 // Checks if the content of the uploaded file contains the given hash
1014 $upload->addValidator('Hash', false, '3b3652f');
1016 // Limits this validator to two different hashes
1017 $upload->addValidator('Hash', false, array('3b3652f', 'e612b69'));
1019 // Sets a different algorithm to check against
1020 $upload->addValidator('Hash',
1021 false,
1022 array('315b3cd8273d44912a7',
1023 'algorithm' => 'md5'));
1024 ]]></programlisting>
1025 </example>
1027 <note>
1028 <para>
1029 This validator supports about 34 different hash algorithms. The most common include
1030 'crc32', 'md5' and 'sha1'. A comprehesive list of supports hash algorithms can be
1031 found at the <ulink url="http://php.net/hash_algos">hash_algos method</ulink> on the
1032 <ulink url="http://php.net">php.net site</ulink>.
1033 </para>
1034 </note>
1035 </sect2>
1037 <sect2 id="zend.file.transfer.validators.md5">
1038 <title>Md5 Validator</title>
1040 <para>
1041 The <classname>Md5</classname> validator checks the content of a transferred file by
1042 hashing it. This validator uses the hash extension for <acronym>PHP</acronym> with the
1043 md5 algorithm. It supports the following options:
1044 </para>
1046 <itemizedlist>
1047 <listitem>
1048 <para>
1049 <property>*</property>: Takes any key or use a numeric array.
1050 </para>
1052 <para>
1053 You can set multiple hashes by passing them as an array. Each file is checked,
1054 and the validation will fail only if all files fail validation.
1055 </para>
1056 </listitem>
1057 </itemizedlist>
1059 <example id="zend.file.transfer.validators.md5.example">
1060 <title>Using the Md5 Validator</title>
1062 <programlisting language="php"><![CDATA[
1063 $upload = new Zend_File_Transfer();
1065 // Checks if the content of the uploaded file has the given hash
1066 $upload->addValidator('Md5', false, '3b3652f336522365223');
1068 // Limits this validator to two different hashes
1069 $upload->addValidator('Md5',
1070 false,
1071 array('3b3652f336522365223',
1072 'eb3365f3365ddc65365'));
1073 ]]></programlisting>
1074 </example>
1075 </sect2>
1077 <sect2 id="zend.file.transfer.validators.mimetype">
1078 <title>MimeType Validator</title>
1080 <para>
1081 The <classname>MimeType</classname> validator checks the <acronym>MIME</acronym> type of
1082 transferred files. It supports the following options:
1083 </para>
1085 <itemizedlist>
1086 <listitem>
1087 <para>
1088 <property>*</property>: Sets any key or use a numeric array. Sets the
1089 <acronym>MIME</acronym> type to validate against.
1090 </para>
1092 <para>
1093 Defines the <acronym>MIME</acronym> type of files to be accepted.
1094 </para>
1095 </listitem>
1097 <listitem>
1098 <para>
1099 <property>headerCheck</property>: If set to <constant>TRUE</constant> this
1100 option will check the <acronym>HTTP</acronym> Information for the file type when
1101 the <emphasis>fileInfo</emphasis> or <emphasis>mimeMagic</emphasis> extensions
1102 can not be found. The default value for this option is
1103 <constant>FALSE</constant>.
1104 </para>
1105 </listitem>
1107 <listitem>
1108 <para>
1109 <property>magicfile</property>: The magicfile to be used.
1110 </para>
1112 <para>
1113 With this option you can define which magicfile to use. When it's not set or
1114 empty, the MAGIC constant will be used instead. This option is available since
1115 Zend Framework 1.7.1.
1116 </para>
1117 </listitem>
1118 </itemizedlist>
1120 <para>
1121 This validator accepts multiple <acronym>MIME</acronym> type, either as a
1122 comma-delimited string, or as an array. You may also use the methods
1123 <methodname>setMimeType()</methodname>, <methodname>addMimeType()</methodname>, and
1124 <methodname>getMimeType()</methodname> to set and retrieve <acronym>MIME</acronym>
1125 type.
1126 </para>
1128 <para>
1129 You can also set the magicfile which shall be used by fileinfo with the 'magicfile'
1130 option. Additionally there are convenient <methodname>setMagicFile()</methodname> and
1131 <methodname>getMagicFile()</methodname> methods which allow later setting and retrieving
1132 of the magicfile parameter. This methods are available since Zend Framework 1.7.1.
1133 </para>
1135 <example id="zend.file.transfer.validators.mimetype.example">
1136 <title>Using the MimeType Validator</title>
1138 <programlisting language="php"><![CDATA[
1139 $upload = new Zend_File_Transfer();
1141 // Limit the MIME type of all given files to gif images
1142 $upload->addValidator('MimeType', false, 'image/gif');
1144 // Limit the MIME type of all given files to gif and jpeg images
1145 $upload->addValidator('MimeType', false, array('image/gif', 'image/jpeg');
1147 // Limit the MIME type of all given files to the group images
1148 $upload->addValidator('MimeType', false, 'image');
1150 // Use a different magicfile
1151 $upload->addValidator('MimeType',
1152 false,
1153 array('image',
1154 'magicfile' => '/path/to/magicfile.mgx'));
1155 ]]></programlisting>
1156 </example>
1158 <para>
1159 The above example shows that it is also possible to limit the accepted
1160 <acronym>MIME</acronym> type to a group of <acronym>MIME</acronym> types. To allow all
1161 images just use 'image' as <acronym>MIME</acronym> type. This can be used for all groups
1162 of <acronym>MIME</acronym> types like 'image', 'audio', 'video', 'text, and so on.
1163 </para>
1165 <note>
1166 <para>
1167 Note that allowing groups of <acronym>MIME</acronym> types will accept all members
1168 of this group even if your application does not support them. When you allow 'image'
1169 you will also get 'image/xpixmap' or 'image/vasa' which could be problematic. When
1170 you are not sure if your application supports all types you should better allow only
1171 defined <acronym>MIME</acronym> types instead of the complete group.
1172 </para>
1173 </note>
1175 <note>
1176 <para>
1177 This component will use the <classname>FileInfo</classname> extension if it is
1178 available. If it's not, it will degrade to the
1179 <methodname>mime_content_type()</methodname> function. And if the function call
1180 fails it will use the <acronym>MIME</acronym> type which is given by
1181 <acronym>HTTP</acronym>.
1182 </para>
1184 <para>
1185 You should be aware of possible security problems when you have whether
1186 <classname>FileInfo</classname> nor <methodname>mime_content_type()</methodname>
1187 available. The <acronym>MIME</acronym> type given by <acronym>HTTP</acronym> is not
1188 secure and can be easily manipulated.
1189 </para>
1190 </note>
1191 </sect2>
1193 <sect2 id="zend.file.transfer.validators.notexists">
1194 <title>NotExists Validator</title>
1196 <para>
1197 The <classname>NotExists</classname> validator checks for the existence of the provided
1198 files. It supports the following options:
1199 </para>
1201 <itemizedlist>
1202 <listitem>
1203 <para>
1204 <property>*</property>: Set any key or use a numeric array. Checks whether the
1205 file exists in the given directory.
1206 </para>
1207 </listitem>
1208 </itemizedlist>
1210 <para>
1211 This validator accepts multiple directories either as a comma-delimited string, or as an
1212 array. You may also use the methods <methodname>setDirectory()</methodname>,
1213 <methodname>addDirectory()</methodname>, and <methodname>getDirectory()</methodname> to
1214 set and retrieve directories.
1215 </para>
1217 <example id="zend.file.transfer.validators.notexists.example">
1218 <title>Using the NotExists Validator</title>
1220 <programlisting language="php"><![CDATA[
1221 $upload = new Zend_File_Transfer();
1223 // Add the temp directory to check
1224 $upload->addValidator('NotExists', false, '\temp');
1226 // Add two directories using the array notation
1227 $upload->addValidator('NotExists', false,
1228 array('\home\images',
1229 '\home\uploads')
1230 );
1231 ]]></programlisting>
1232 </example>
1234 <note>
1235 <para>
1236 Note that this validator checks if the file does not exist in all of the provided
1237 directories. The validation will fail if the file does exist in any of the given
1238 directories.
1239 </para>
1240 </note>
1241 </sect2>
1243 <sect2 id="zend.file.transfer.validators.sha1">
1244 <title>Sha1 Validator</title>
1246 <para>
1247 The <classname>Sha1</classname> validator checks the content of a transferred file by
1248 hashing it. This validator uses the hash extension for <acronym>PHP</acronym> with the
1249 sha1 algorithm. It supports the following options:
1250 </para>
1252 <itemizedlist>
1253 <listitem>
1254 <para>
1255 <property>*</property>: Takes any key or use a numeric array.
1256 </para>
1258 <para>
1259 You can set multiple hashes by passing them as an array. Each file is checked,
1260 and the validation will fail only if all files fail validation.
1261 </para>
1262 </listitem>
1263 </itemizedlist>
1265 <example id="zend.file.transfer.validators.sha1.example">
1266 <title>Using the sha1 Validator</title>
1268 <programlisting language="php"><![CDATA[
1269 $upload = new Zend_File_Transfer();
1271 // Checks if the content of the uploaded file has the given hash
1272 $upload->addValidator('sha1', false, '3b3652f336522365223');
1274 // Limits this validator to two different hashes
1275 $upload->addValidator('Sha1',
1276 false, array('3b3652f336522365223',
1277 'eb3365f3365ddc65365'));
1278 ]]></programlisting>
1279 </example>
1280 </sect2>
1282 <sect2 id="zend.file.transfer.validators.size">
1283 <title>Size Validator</title>
1285 <para>
1286 The <classname>Size</classname> validator checks for the size of a single file. It
1287 supports the following options:
1288 </para>
1290 <itemizedlist>
1291 <listitem>
1292 <para>
1293 <property>min</property>: Sets the minimum file size.
1294 </para>
1295 </listitem>
1297 <listitem>
1298 <para>
1299 <property>max</property>: Sets the maximum file size.
1300 </para>
1301 </listitem>
1303 <listitem>
1304 <para>
1305 <property>bytestring</property>: Defines whether a failure is returned with a
1306 user-friendly number, or with the plain file size.
1307 </para>
1309 <para>
1310 With this option you can define if the user gets '10864' or '10MB'. Default
1311 value is <constant>TRUE</constant> which returns '10MB'.
1312 </para>
1313 </listitem>
1314 </itemizedlist>
1316 <para>
1317 You can initialize this validator with a string, which will then be used to set the
1318 <property>max</property> option. You can also use the methods
1319 <methodname>setMin()</methodname> and <methodname>setMax()</methodname> to set both
1320 options after construction, along with <methodname>getMin()</methodname> and
1321 <methodname>getMax()</methodname> to retrieve the values that have been set previously.
1322 </para>
1324 <para>
1325 The size itself is also accepted in SI notation as handled by most operating systems.
1326 That is, instead of specifying <emphasis>20000 bytes</emphasis>,
1327 <emphasis>20kB</emphasis> may be given. All file sizes are converted using 1024 as the
1328 base value. The following Units are accepted: <emphasis>kB</emphasis>,
1329 <emphasis>MB</emphasis>, <emphasis>GB</emphasis>, <emphasis>TB</emphasis>,
1330 <emphasis>PB</emphasis> and <emphasis>EB</emphasis>. Note that 1kB is equal to 1024
1331 bytes, 1MB is equal to 1024kB, and so on.
1332 </para>
1334 <example id="zend.file.transfer.validators.size.example">
1335 <title>Using the Size Validator</title>
1337 <programlisting language="php"><![CDATA[
1338 $upload = new Zend_File_Transfer();
1340 // Limit the size of a file to 40000 bytes
1341 $upload->addValidator('Size', false, 40000);
1343 // Limit the size a given file to maximum 4MB and mimimum 10kB
1344 // Also returns the plain number in case of an error
1345 // instead of a user-friendly number
1346 $upload->addValidator('Size',
1347 false,
1348 array('min' => '10kB',
1349 'max' => '4MB',
1350 'bytestring' => false));
1351 ]]></programlisting>
1352 </example>
1353 </sect2>
1355 <sect2 id="zend.file.transfer.validators.wordcount">
1356 <title>WordCount Validator</title>
1358 <para>
1359 The <classname>WordCount</classname> validator checks for the number of words within
1360 provided files. It supports the following option keys:
1361 </para>
1363 <itemizedlist>
1364 <listitem>
1365 <para>
1366 <property>min</property>: Sets the minimum number of words to be found.
1367 </para>
1368 </listitem>
1370 <listitem>
1371 <para>
1372 <property>max</property>: Sets the maximum number of words to be found.
1373 </para>
1374 </listitem>
1375 </itemizedlist>
1377 <para>
1378 If you initiate this validator with a string or integer, the value will be used as
1379 <property>max</property>. Or you can also use the methods
1380 <methodname>setMin()</methodname> and <methodname>setMax()</methodname> to set both
1381 options afterwards and <methodname>getMin()</methodname> and
1382 <methodname>getMax()</methodname> to retrieve the actual set values.
1383 </para>
1385 <example id="zend.file.transfer.validators.wordcount.example">
1386 <title>Using the WordCount Validator</title>
1388 <programlisting language="php"><![CDATA[
1389 $upload = new Zend_File_Transfer();
1391 // Limit the amount of words within files to maximum 2000
1392 $upload->addValidator('WordCount', false, 2000);
1394 // Limit the amount of words within files to maximum 5000 and minimum 1000 words
1395 $upload->addValidator('WordCount', false, array('min' => 1000, 'max' => 5000));
1396 ]]></programlisting>
1397 </example>
1398 </sect2>
1399 </sect1>
1400 <!--
1401 vim:se ts=4 sw=4 tw=80 et:
1402 -->