NAME

CGI::Upload - CGI class for handling browser file uploads

SYNOPSIS

use CGI;
use CGI::Upload;

my $cgi = CGI->new;
my $upload = CGI::Upload->new( $cgi );

my $file_name = $upload->file_name( 'field_name' );
my $file_type = $upload->file_type( 'field_name' );

$upload->mime_magic( '/path/to/mime.types' );
my $mime_type = $upload->mime_type( 'field_name' );

my $file_handle = $upload->file_handle( 'field_name' );

DESCRIPTION

This module has been written to provide a simple and secure manner by which to handle files uploaded in multipart/form-data requests through a web browser. The primary advantage which this module offers over existing modules is the single interface providing the most often required information regarding files uploaded through multipart/form-data requests.

Building on CGI and File::MMagic, this module offers a very tidy and succinct interface for handling of file uploads.

METHODS

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

new( $cgi )

This method creates and returns a new CGI::Upload object. In previously versions of CGI::Upload, a mandatory argument of the CGI.pm object to be used was required. This is no longer necessary with initiation of a new CGI.pm object within the CGI::Upload constructor if one is not passed as an argument to the constructor. This created CGI.pm is subsequently available via the query method.

Remember that only a single CGI.pm object can be initiated within a given CGI script.

query()

Returns the CGI.pm object used for the CGI::Upload class. If a CGI.pm object was passed to the CGI::Upload constructor, it is this object which is returned by this method.

file_handle( 'field_name' )

This method returns the file handle to a temporary file containing the file uploaded through the form input field named 'field_name'.

file_name( 'field_name' )

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

file_type( 'field_name' )

This method returns the file type of the file uploaded as indicated by the file extension - This does not necessarily reflect the nature of the file uploaded, but allows CGI scripts to perform cursory validation on the file uploaded.

mime_magic( '/path/to/mime.types' )

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

See File::MMagic for further details.

mime_type( 'field_name' )

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

See File::MMagic for further details.

SEE ALSO

CGI, File::MMagic, HTTP::File

COPYRIGHT

Copyright 2002, Rob Casey, rob@cowsnet.com.au

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

AUTHOR

Rob Casey, rob@cowsnet.com.au