view release on metacpan or  search on metacpan

lib/CGI/Upload.pm  view on Meta::CPAN

=head1 METHODS

The following methods are available through this module for use in CGI scripts 
and can be exported into the calling namespace upon request.

=over 4

=item B<new>

This object constructor method creates and returns a new B<CGI::Upload> object.  
In previously versions of B<CGI::Upload>, a mandatory argument of the B<CGI> 
object to be used was required.  This is no longer necessary due to the 
singleton nature of B<CGI> objects.

As an experiment, you can now use any kind of CGI.pm like module. The requirements
are that it has to support the ->param method and the ->upload method returning a
file handle. You can use this feature in two ways, either providing the name of
the module or an already existing object. In the former case, CGI::Upload will try
to I<require> the correct module and will I<croak> if cannot load that module.
It has been tested with CGI.pm and CGI::Simple. 

We tested it with CGI::Simple 0.075. 

It is known to break with version 0.071 of CGI::Simple so we issue our own die in such case. 

Examples:

 use CGI::Upload;
 CGI::Upload->new({ query => "CGI::Simple"});

or

 use CGI::Upload;
 use CGI::Simple;
 $CGI::Simple::DISABLE_UPLOADS = 0;   # you have to set this before creating the instance
 my $q = CGI::Simple->new;
 CGI::Upload->new({ query => $q});

=item B<query>

Returns the B<CGI> object used within the B<CGI::Upload> class.  

=item B<file_handle('field')>

This method returns the file handle to the temporary file containing the file 
uploaded through the form input field named 'field'.  This temporary file is 
generated using the B<new_tmpfile> method of B<IO::File> and is anonymous in 
nature, where possible.

=item B<file_name('field')>

This method returns the file name of the file uploaded through the form input 
field named 'field' - This file name does not reflect the local temporary 
filename of the uploaded file, but that for the file supplied by the client web 
browser.

=item B<file_type('field')>

This method returns the file type of the file uploaded as specified by the 
filename extension - Please note that this does not necessarily reflect the 
nature of the file uploaded, but allows CGI scripts to perform cursory 
validation of the file type of the uploaded file.

=item B<mime_magic('/path/to/mime.types')>

This method sets and/or returns the external magic mime types file to be used 
for the identification of files via the B<mime_type> method.  By default, MIME 
identification is based upon internal mime types defined within the 
B<File::MMagic> module.

See L<File::MMagic> for further details.

=item B<mime_type('field')>

This method returns the MIME type of the file uploaded through the form input 
field named 'field' as determined by file magic numbers.  This is the best 
means by which to validate the nature of the uploaded file.

See L<File::MMagic> for further details.

=back

=head1 BUGS

Please report bugs on RT: L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=CGI-Upload>

=head1 TODO

Explain why there is no 100% tests coverage...

Give inteligent error message when user forgets to add  enctype="multipart/form-data" in the upload form.

Add better MIME magic support (see request on RT)

Test if multiple file uploads are supported and fix this if they are not.

Apache::Request support

CGI::Minimal support

Example code from  Mark Stosberg (CGI::Uploader):

  if ($q->isa('CGI::Simple') ) {
           $fh = $q->upload($filename); 
           $mt = $q->upload_info($filename, 'mime' );

           if (!$fh && $q->cgi_error) {
                   warn $q->cgi_error && return undef;
           }
   }
   elsif ( $q->isa('Apache::Request') ) {
            my $upload = $q->upload($file_field);
                $fh = $upload->fh;
                $mt = $upload->type;
   }
   # default to CGI.pm behavior
   else {
           $fh = $q->upload($file_field);
           $mt = $q->uploadInfo($fh)->{'Content-Type'} if $q->uploadInfo($fh);

           if (!$fh && $q->cgi_error) {