NAME

       Catalyst::Request::Upload - handles file upload requests

SYNOPSIS

           my $upload = $c->req->upload('field');

           $upload->basename;
           $upload->copy_to;
           $upload->fh;
           $upload->decoded_fh
           $upload->filename;
           $upload->headers;
           $upload->link_to;
           $upload->size;
           $upload->slurp;
           $upload->decoded_slurp;
           $upload->tempname;
           $upload->type;
           $upload->charset;

       To specify where Catalyst should put the temporary files, set the 'uploadtmp' option in
       the Catalyst config. If unset, Catalyst will use the system temp dir.

           __PACKAGE__->config( uploadtmp => '/path/to/tmpdir' );

       See also Catalyst.

DESCRIPTION

       This class provides accessors and methods to handle client upload requests.

METHODS

   $upload->new
       Simple constructor.

   $upload->copy_to
       Copies the temporary file using File::Copy. Returns true for success, false for failure.

            $upload->copy_to('/path/to/target');

       Please note the filename used for the copy target is the 'tempname' that is the actual
       filename on the filesystem, NOT the 'filename' that was part of the upload headers.  This
       might seem counter intuitive but at this point this behavior is so established that its
       not something we can change.

       You can always create your own copy routine that munges the target path as you wish.

   $upload->is_utf8_encoded
       Returns true of the upload defines a character set at that value is 'UTF-8'.  This does
       not try to inspect your upload and make any guesses if the Content Type charset is
       undefined.

   $upload->fh
       Opens a temporary file (see tempname below) and returns an IO::File handle.

       This is a filehandle that is opened with no additional IO Layers.

   $upload->decoded_fh(?$encoding)
       Returns a filehandle that has binmode set to UTF-8 if a UTF-8 character set is found. This
       also accepts an override encoding value that you can use to force a particular PerlIO
       layer.  If neither are found the filehandle is set to :raw.

       This is useful if you are pulling the file into code and inspecting bits and maybe then
       sending those bits back as the response.  (Please note this is not a suitable filehandle
       to set in the body; use "fh" if you are doing that).

       Please note that using this method sets the underlying filehandle IO layer so once you use
       this method if you go back and use the "fh" method you still get the IO layer applied.

   $upload->filename
       Returns the client-supplied filename.

   $upload->headers
       Returns an HTTP::Headers object for the request.

   $upload->link_to
       Creates a hard link to the temporary file. Returns true for success, false for failure.

           $upload->link_to('/path/to/target');

   $upload->size
       Returns the size of the uploaded file in bytes.

   $upload->slurp(?$encoding)
       Optionally accepts an argument to define an IO Layer (which is applied to the filehandle
       via binmode; if no layer is defined the default is set to ":raw".

       Returns a scalar containing the contents of the temporary file.

       Note that this will cause the filehandle pointed to by "$upload->fh" to be reset to the
       start of the file using seek and the file handle to be put into whatever encoding mode is
       applied.

   $upload->decoded_slurp(?$encoding)
       Works just like "slurp" except we use "decoded_fh" instead of "fh" to open a filehandle to
       slurp.  This means if your upload charset is UTF8 we binmode the filehandle to that
       encoding.

   $upload->basename
       Returns basename for "filename".  This filters the name through a regexp "basename =~
       s|[^\w\.-]+|_|g" to make it safe for filesystems that don't like advanced characters.
       This will of course filter UTF8 characters.  If you need the exact basename unfiltered use
       "raw_basename".

   $upload->raw_basename
       Just like "basename" but without filtering the filename for characters that don't always
       write to a filesystem.

   $upload->tempname
       Returns the path to the temporary file.

   $upload->type
       Returns the client-supplied Content-Type.

   $upload->charset
       The character set information part of the content type, if any.  Useful if you need to
       figure out any encodings on the file upload.

   meta
       Provided by Moose

AUTHORS

       Catalyst Contributors, see Catalyst.pm

COPYRIGHT

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