view release on metacpan or  search on metacpan

lib/CGI.pod  view on Meta::CPAN

Note that you must use ->upload or ->param to get the file-handle to pass into
uploadInfo as internally this is represented as a File::Temp object (which is
what will be returned by ->upload or ->param). When using ->Vars you will get
the literal filename rather than the File::Temp object, which will not return
anything when passed to uploadInfo. So don't use ->Vars.

When uploading multiple files, call ->param() in list context to
retrieve a list of filehandles that you can use when calling ->uploadInfo.

    my @filehandles = $q->param('uploaded_file');

    for my $fh (@filehandles) {
      my $info = $q->uploadInfo($fh);
      ...
    }

If you are using a machine that recognizes "text" and "binary" data modes, be
sure to understand when and how to use them (see the Camel book). Otherwise
you may find that binary files are corrupted during file uploads.

=head3 Accessing the temp files directly

When processing an uploaded file, CGI.pm creates a temporary file on your hard
disk and passes you a file handle to that file. After you are finished with the
file handle, CGI.pm unlinks (deletes) the temporary file. If you need to you
can access the temporary file directly. You can access the temp file for a file
upload by passing the file handle to the tmpFileName() method:

    my $filehandle  = $q->upload( 'uploaded_file' );
    my $tmpfilename = $q->tmpFileName( $filehandle );

As with ->uploadInfo, using the reference returned by ->upload or ->param is
preferred, although unlike ->uploadInfo, plain filenames also work if possible
for backwards compatibility.

The temporary file will be deleted automatically when your program exits unless
you manually rename it or set $CGI::UNLINK_TMP_FILES to 0. On some operating
systems (such as Windows NT), you will need to close the temporary file's
filehandle before your program exits. Otherwise the attempt to delete the
temporary file will fail.

=head3 Changes in temporary file handling (v4.05+)

CGI.pm had its temporary file handling significantly refactored, this logic is
now all deferred to File::Temp (which is wrapped in a compatibility object,
CGI::File::Temp - B<DO NOT USE THIS PACKAGE DIRECTLY>). As a consequence the
PRIVATE_TEMPFILES variable has been removed along with deprecation of the
private_tempfiles routine and B<complete> removal of the CGITempFile package.
The $CGITempFile::TMPDIRECTORY is no longer used to set the temp directory,
refer to the perldoc for File::Temp if you want to override the default
settings in that package (the TMPDIR env variable is still available on some
platforms). For Windows platforms the temporary directory order remains
as before: TEMP > TMP > WINDIR ( > TMPDIR ) so if you have any of these in
use in existing scripts they should still work.

The Fh package still exists but does nothing, the CGI::File::Temp class is
a subclass of both File::Temp and the empty Fh package, so if you have any
code that checks that the filehandle isa Fh this should still work.

When you get the internal file handle you will receive a File::Temp object,
this should be transparent as File::Temp isa IO::Handle and isa IO::Seekable
meaning it behaves as previously. If you are doing anything out of the ordinary
with regards to temp files you should test your code before deploying this
update and refer to the File::Temp documentation for more information.

=head3 Handling interrupted file uploads

There are occasionally problems involving parsing the uploaded file. This
usually happens when the user presses "Stop" before the upload is finished. In
this case, CGI.pm will return undef for the name of the uploaded file and set
I<cgi_error()> to the string "400 Bad request (malformed multipart POST)". This
error message is designed so that you can incorporate it into a status code to
be sent to the browser. Example:

    my $file = $q->upload( 'uploaded_file' );
    if ( !$file && $q->cgi_error ) {
        print $q->header( -status => $q->cgi_error );
        exit 0;
    }

=head3 Progress bars for file uploads and avoiding temp files

CGI.pm gives you low-level access to file upload management through a file
upload hook. You can use this feature to completely turn off the temp file
storage of file uploads, or potentially write your own file upload progress
meter.

This is much like the UPLOAD_HOOK facility available in L<Apache::Request>,
with the exception that the first argument to the callback is an
L<Apache::Upload> object, here it's the remote filename.

    my $q = CGI->new( \&hook [,$data [,$use_tempfile]] );

    sub hook {
        my ( $filename, $buffer, $bytes_read, $data ) = @_;
        print "Read $bytes_read bytes of $filename\n";
    }

The C<< $data >> field is optional; it lets you pass configuration information
(e.g. a database handle) to your hook callback.

The C<< $use_tempfile >> field is a flag that lets you turn on and off
CGI.pm's use of a temporary disk-based file during file upload. If you
set this to a FALSE value (default true) then
C<<< $q->param('uploaded_file') >>> will still return a typeglob that can be
used to access a filehandle and the filename of the uploaded file,
however the filehandle will be a handle to an empty file. Existence of
your hook causes CGI.pm to bypass writing to that filehandle (which is
probably what you intended when you set C<< $use_tempfile >> off).

The C<< uploadInfo() >> method can be used on the typeglob returned to
you when you called C<<< $q->param('upload_file') >>> to return
information about the uploaded file(s). For multiple file uploads, use
the C< param() > method in list context to retrieve all of the
typeglobs.

    my (@filehandles) = $cgi->param('upfile');

    foreach my $fh (@filehandles) {
      my $info = $cgi->uploadInfo($fh);
      ...