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, the only mandatory argument to which is a CGI.pm object. This is in part because only a single CGI.pm object can be initiated within a given CGI script.

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