.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Data::FormValidator::Constraints::Upload 3pm"
.TH Data::FormValidator::Constraints::Upload 3pm "2017-10-24" "perl v5.26.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Data::FormValidator::Constraints::Upload \- Validate File Uploads
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&    # Be sure to use a CGI.pm or CGI::Simple object as the form
\&    # input when using this constraint
\&    my $q = CGI\->new;
\&
\&    use Data::FormValidator::Constraints::Upload qw(
\&            file_format
\&            file_max_bytes
\&            image_max_dimensions
\&            image_min_dimensions
\&    );
\&    my $dfv = Data::FormValidator\->check($q,$my_profile);
\&
\&    # In a Data::FormValidator Profile:
\&    constraint_methods => {
\&        image_name => [
\&            file_format(),
\&            file_max_bytes(10),
\&            image_max_dimensions(200,200),
\&            image_min_dimensions(100,100),
\&         ],
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBNote:\fR This is a new module is a new addition to Data::FormValidator and is
should be considered \*(L"Beta\*(R".
.PP
These module is meant to be used in conjunction with the Data::FormValidator
module to automate the task of validating uploaded files. The following
validation routines are supplied.
.PP
To use any of them, the input data passed to Data::FormValidator must
be a \s-1CGI\s0.pm object.
.IP "file_format" 4
.IX Item "file_format"
This function checks the format of the file, based on the \s-1MIME\s0 type if it's
available, and a case-insensitive version of the file extension otherwise. By
default, it tries to validate \s-1JPEG, GIF\s0 and \s-1PNG\s0 images. The params are:
.Sp
.Vb 2
\& optional hash reference of parameters. A key named I<mime_types> points to
\& array references of valid values.
\&
\&   file_format( mime_types => [qw!image/jpeg image/gif image/png!] );
.Ve
.Sp
Calling this function sets some meta data which can be retrieved through
the \f(CW\*(C`meta()\*(C'\fR method of the Data::FormValidator::Results object.
The meta data added is \f(CW\*(C`extension\*(C'\fR and \f(CW\*(C`mime_type\*(C'\fR.
.Sp
The \s-1MIME\s0 type of the file will first be tried to figured out by using the
<File::MMagic> module to examine the file. If that doesn't turn up a result,
we'll use a \s-1MIME\s0 type from the browser if one has been provided. Otherwise, we
give up. The extension we return is based on the \s-1MIME\s0 type we found, rather
than trusting the one that was uploaded.
.Sp
\&\fB\s-1NOTE:\s0\fR if we have to fall back to using the \s-1MIME\s0 type provided by the
browser, we access it from the original \fIinput\fR data and not the
\&\fIfiltered\fR data.  This should only cause issue when you have used a filter
to alter the type of file that was uploaded (e.g. image conversion).
.IP "file_max_bytes" 4
.IX Item "file_max_bytes"
This function checks the maximum size of an uploaded file. By default,
it checks to make sure files are smaller than 1 Meg. The params are:
.Sp
.Vb 1
\& reference to max file size in bytes
\&
\&    file_max_bytes(1024), # 1 k
.Ve
.Sp
Calling this function sets some meta data which can be retrieved through
the \f(CW\*(C`meta()\*(C'\fR method of the Data::FormValidator::Results object.
The meta data added is \f(CW\*(C`bytes\*(C'\fR.
.IP "image_max_dimensions" 4
.IX Item "image_max_dimensions"
This function checks to make sure an uploaded image is no longer than
some maximum dimensions. The params are:
.Sp
.Vb 2
\& reference to max pixel width
\& reference to max pixel height
\&
\&    image_max_dimensions(200,200),
.Ve
.Sp
Calling this function sets some meta data which can be retrieved through
the \f(CW\*(C`meta()\*(C'\fR method of the Data::FormValidator::Results object.
The meta data added is \f(CW\*(C`width\*(C'\fR and \f(CW\*(C`height\*(C'\fR.
.IP "image_min_dimensions" 4
.IX Item "image_min_dimensions"
This function checks to make sure an uploaded image is longer than
some minimum dimensions. The params are:
.Sp
.Vb 2
\& reference to min pixel width
\& reference to min pixel height
\&
\&    image_min_dimensions(100,100),
.Ve
.Sp
Calling this function sets some meta data which can be retrieved through
the \f(CW\*(C`meta()\*(C'\fR method of the Data::FormValidator::Results object.
The meta data added is \f(CW\*(C`width\*(C'\fR and \f(CW\*(C`height\*(C'\fR.
.SS "\s-1BACKWARDS COMPATIBILITY\s0"
.IX Subsection "BACKWARDS COMPATIBILITY"
An older more awkward interface to the constraints in this module is still supported.
To use it, you have to load the package with 'validator_packages', and call each
constraint in a hashref style, passing the parameters by reference. It looks
like this:
.PP
.Vb 9
\&    validator_packages => [qw(Data::FormValidator::Constraints::Upload)],
\&    constraints => {
\&        image_name => [
\&            {
\&                constraint_method => \*(Aqimage_max_dimensions\*(Aq,
\&                params => [\e200,\e200],
\&            }
\&         ],
\&    }
.Ve
.PP
I told you it was more awkward. That was before I grokked the magic of closures, which
is what drives the current interface.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
FileMetadata, Data::FormValidator, \s-1CGI\s0, perl
.SH "AUTHOR"
.IX Header "AUTHOR"
Mark Stosberg, <mark@summersault.com>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright 2003\-2005 by Mark Stosberg
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.