view release on metacpan or  search on metacpan

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

package CGI::Uploader;

use 5.008;
use strict;
use Carp;
use Params::Validate ':all';
use File::Path;
use File::Spec;
use File::Temp 'tempfile';
use Carp::Assert;
use Image::Size;
require Exporter;

our $VERSION = '2.18';

=head1 NAME

CGI::Uploader - Manage CGI uploads using SQL database

=head1 Synopsis

 use CGI::Uploader::Transform::ImageMagick 'gen_thumb';

 my $u = CGI::Uploader->new(
    spec       => {
        # Upload one image named from the form field 'img'
        # and create one thumbnail for it.
        img_1 => {
            gen_files => {
                'img_1_thmb_1' => gen_thumb({ w => 100, h => 100 }),
              }
        },
    },

    updir_url  => 'http://localhost/uploads',
    updir_path => '/home/user/www/uploads',
        temp_dir   => '/home/user/www/uploads',

    dbh        => $dbh,
    query      => $q, # defaults to CGI->new(),
 );

 # ... now do something with $u

=head1 Description

This module is designed to help with the task of managing files uploaded
through a CGI application. The files are stored on the file system, and
the file attributes stored in a SQL database.

=head1 Introduction and Recipes

The L<CGI::Uploader::Cookbook|CGI::Uploader::Cookbook> provides
a slightly more in depth introduction and recipes for a basic BREAD web
application.  (Browse, Read, Edit, Add, Delete).

=head1 Constructor

=head2 new()

 my $u = CGI::Uploader->new(
    spec       => {
         # The first image has 2 different sized thumbnails
           img_1 => {
             gen_files => {
                     'img_1_thmb_1' => gen_thumb({ w => 100, h => 100 }),
                     'img_1_thmb_2' => gen_thumb({ w => 50, h => 50 }),
             }
           },
       },

        # Just upload it
        img_2 => {},
        # Downsize the large image to these maximum dimensions if it's larger
        img_3 => {
            # Besides generating dependent files
            # We can also transform the file itself
            # Here, we shrink the image to be wider than 380
            transform_method => \&gen_thumb,
            # demostrating the old-style param passing
            params => [{ w => 380 }],
        }
    },

    updir_url  => 'http://localhost/uploads',
    updir_path => '/home/user/www/uploads',

    dbh        => $dbh,
    query      => $q, # defaults to CGI->new(),

    up_table   => 'uploads', # defaults to "uploads"
    up_seq     => 'upload_id_seq',  # Required for Postgres
 );

=over 4

=item spec [required]

The specification described the examples above. The keys correspond to form
field names for upload fields.

The values are hash references. The simplest case is an empty hash  reference,
which means to just upload the image and apply no transformations.

#####

Each key in the hash is the corresponds to a file upload field. The values
are hash references used provide options for how to transform the file,
and possibly generate additional files based on it.

Valid keys here are:

=item transform_method