Data::FormValidator::Constraints::Upload - Validate File Uploads

       Mark Stosberg, <mark@summersault.com>

       Copyright 2003-2005 by Mark Stosberg

       This library is free software; you can redistribute it and/or modify it under  the  same  terms  as  Perl
       itself.

perl v5.34.0                                       2022-06-12             Data::FormValid...traints::Upload(3pm)

Note: This is a new module is a new addition to Data::FormValidator and is should be considered "Beta".

       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.

       To use any of them, the input data passed to Data::FormValidator must be a CGI.pm object.

       file_format
           This  function  checks  the format of the file, based on the MIME type if it's available, and a case-
           insensitive version of the file extension otherwise. By default, it tries to validate JPEG,  GIF  and
           PNG images. The params are:

            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!] );

           Calling  this  function sets some meta data which can be retrieved through the "meta()" method of the
           Data::FormValidator::Results object.  The meta data added is "extension" and "mime_type".

           The MIME 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 MIME type from the browser if one has
           been  provided.  Otherwise,  we  give up. The extension we return is based on the MIME type we found,
           rather than trusting the one that was uploaded.

           NOTE: if we have to fall back to using the MIME type provided by the browser, we access it  from  the
           original  input  data  and  not the filtered 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).

       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:

            reference to max file size in bytes

               file_max_bytes(1024), # 1 k

           Calling  this  function sets some meta data which can be retrieved through the "meta()" method of the
           Data::FormValidator::Results object.  The meta data added is "bytes".

       image_max_dimensions
           This function checks to make sure an uploaded image is no longer than some  maximum  dimensions.  The
           params are:

            reference to max pixel width
            reference to max pixel height

               image_max_dimensions(200,200),

           Calling  this  function sets some meta data which can be retrieved through the "meta()" method of the
           Data::FormValidator::Results object.  The meta data added is "width" and "height".

       image_min_dimensions
           This function checks to make sure an uploaded image is  longer  than  some  minimum  dimensions.  The
           params are:

            reference to min pixel width
            reference to min pixel height

               image_min_dimensions(100,100),

           Calling  this  function sets some meta data which can be retrieved through the "meta()" method of the
           Data::FormValidator::Results object.  The meta data added is "width" and "height".

   BACKWARDSCOMPATIBILITY
       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:

           validator_packages => [qw(Data::FormValidator::Constraints::Upload)],
           constraints => {
               image_name => [
                   {
                       constraint_method => 'image_max_dimensions',
                       params => [\200,\200],
                   }
                ],
           }

       I told you it was more awkward. That was before I grokked the magic of closures, which is what drives the
       current interface.

       Data::FormValidator::Constraints::Upload - Validate File Uploads

       FileMetadata, Data::FormValidator, CGI, perl

           # 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),
                ],
           }