NAME

CGI::UploadEasy - Facilitate file uploads

SYNOPSIS

    use CGI::UploadEasy;
    my $ue = CGI::UploadEasy->new(-uploaddir => '/path/to/upload/dir');
    my $cgi = $ue->cgiobject;
    my $info = $ue->fileinfo;

DESCRIPTION

CGI::UploadEasy is a wrapper around, and relies heavily on, CGI.pm. Its purpose is to provide a simple interface to the upload functionality of CGI.pm.

At creation of the CGI::UploadEasy object, the module saves one or more files from a file upload request in the upload directory, and information about uploaded files is made available via the fileinfo() method. CGI::UploadEasy performs a number of tests, which limit the risk that you encounter difficulties when developing a file upload application.

Methods

my $ue = CGI::UploadEasy->new( -uploaddir => $dir [ , -maxsize => $kibibytes, ... ] )

The new() constructor takes hash style arguments. The following arguments are recognized:

-uploaddir

Specifying the upload directory is mandatory.

-tempdir

To control which directory will be used for temporary files, set the -tempdir argument.

-maxsize

Specifies the maximum size in KiB (kibibytes) of a POST request data set. Default limit is 1,000 KiB. To disable this ceiling for POST requests, set a negative -maxsize value.

$ue->cgiobject

Returns a reference to the CGI object that CGI::UploadEasy uses internally, which gives access to all the CGI.pm methods.

If you prefer the function-oriented style, you can import a set of methods instead. Example:

    use CGI qw/:standard/;
    print header;

$ue->fileinfo

Returns a reference to a 'hash of hashes' with info about uploaded files. The info may be of use for a result page and/or an email notification, and it lets you use e.g. MIME type and file size as criteria for how to further process the files.

$ue->otherparam

The otherparam() method returns a list of parameter names besides the names of the file select controls that were used for file uploads. To access the values, use CGI.pm's param() method.

EXAMPLE

This script handles a file upload request by saving a number of files in the upload directory and printing the related info:

    #!/usr/bin/perl -T
    use strict;
    use warnings;
    use CGI::UploadEasy;
    use Data::Dumper;
    my $ue = CGI::UploadEasy->new(-uploaddir => '/path/to/upload/dir');
    my $info = $ue->fileinfo;
    my $cgi = $ue->cgiobject;
    print $cgi->header('text/plain');
    print Dumper $info;

CAVEATS

Since CGI::UploadEasy is meant for file uploads, it requires that the request data is multipart/form-data encoded. An application/x-www-form-urlencoded POST request will cause a fatal error.

No CGI object may be created before the CGI::UploadEasy object has been created, or else the upload will fail. Likewise, if you import method names from CGI.pm, be careful not to call any CGI functions before the creation of the CGI::UploadEasy object.

AUTHOR, COPYRIGHT AND LICENSE

  Copyright (c) 2005-2009 Gunnar Hjalmarsson
  http://www.gunnar.cc/cgi-bin/contact.pl

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

SEE ALSO

CGI.pm