.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Catalyst::Request::Upload 3pm" .TH Catalyst::Request::Upload 3pm "2020-09-13" "perl v5.30.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Catalyst::Request::Upload \- handles file upload requests .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& my $upload = $c\->req\->upload(\*(Aqfield\*(Aq); \& \& $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; .Ve .PP 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. .PP .Vb 1 \& _\|_PACKAGE_\|_\->config( uploadtmp => \*(Aq/path/to/tmpdir\*(Aq ); .Ve .PP See also Catalyst. .SH "DESCRIPTION" .IX Header "DESCRIPTION" This class provides accessors and methods to handle client upload requests. .SH "METHODS" .IX Header "METHODS" .ie n .SS "$upload\->new" .el .SS "\f(CW$upload\fP\->new" .IX Subsection "$upload->new" Simple constructor. .ie n .SS "$upload\->copy_to" .el .SS "\f(CW$upload\fP\->copy_to" .IX Subsection "$upload->copy_to" Copies the temporary file using File::Copy. Returns true for success, false for failure. .PP .Vb 1 \& $upload\->copy_to(\*(Aq/path/to/target\*(Aq); .Ve .PP Please note the filename used for the copy target is the 'tempname' that is the actual filename on the filesystem, \s-1NOT\s0 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. .PP You can always create your own copy routine that munges the target path as you wish. .ie n .SS "$upload\->is_utf8_encoded" .el .SS "\f(CW$upload\fP\->is_utf8_encoded" .IX Subsection "$upload->is_utf8_encoded" Returns true of the upload defines a character set at that value is '\s-1UTF\-8\s0'. This does not try to inspect your upload and make any guesses if the Content Type charset is undefined. .ie n .SS "$upload\->fh" .el .SS "\f(CW$upload\fP\->fh" .IX Subsection "$upload->fh" Opens a temporary file (see tempname below) and returns an IO::File handle. .PP This is a filehandle that is opened with no additional \s-1IO\s0 Layers. .ie n .SS "$upload\->decoded_fh(?$encoding)" .el .SS "\f(CW$upload\fP\->decoded_fh(?$encoding)" .IX Subsection "$upload->decoded_fh(?$encoding)" Returns a filehandle that has binmode set to \s-1UTF\-8\s0 if a \s-1UTF\-8\s0 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. .PP 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 \f(CW\*(C`fh\*(C'\fR if you are doing that). .PP Please note that using this method sets the underlying filehandle \s-1IO\s0 layer so once you use this method if you go back and use the \f(CW\*(C`fh\*(C'\fR method you still get the \s-1IO\s0 layer applied. .ie n .SS "$upload\->filename" .el .SS "\f(CW$upload\fP\->filename" .IX Subsection "$upload->filename" Returns the client-supplied filename. .ie n .SS "$upload\->headers" .el .SS "\f(CW$upload\fP\->headers" .IX Subsection "$upload->headers" Returns an HTTP::Headers object for the request. .ie n .SS "$upload\->link_to" .el .SS "\f(CW$upload\fP\->link_to" .IX Subsection "$upload->link_to" Creates a hard link to the temporary file. Returns true for success, false for failure. .PP .Vb 1 \& $upload\->link_to(\*(Aq/path/to/target\*(Aq); .Ve .ie n .SS "$upload\->size" .el .SS "\f(CW$upload\fP\->size" .IX Subsection "$upload->size" Returns the size of the uploaded file in bytes. .ie n .SS "$upload\->slurp(?$encoding)" .el .SS "\f(CW$upload\fP\->slurp(?$encoding)" .IX Subsection "$upload->slurp(?$encoding)" Optionally accepts an argument to define an \s-1IO\s0 Layer (which is applied to the filehandle via binmode; if no layer is defined the default is set to \&\*(L":raw\*(R". .PP Returns a scalar containing the contents of the temporary file. .PP Note that this will cause the filehandle pointed to by \f(CW\*(C`$upload\->fh\*(C'\fR to be reset to the start of the file using seek and the file handle to be put into whatever encoding mode is applied. .ie n .SS "$upload\->decoded_slurp(?$encoding)" .el .SS "\f(CW$upload\fP\->decoded_slurp(?$encoding)" .IX Subsection "$upload->decoded_slurp(?$encoding)" Works just like \f(CW\*(C`slurp\*(C'\fR except we use \f(CW\*(C`decoded_fh\*(C'\fR instead of \f(CW\*(C`fh\*(C'\fR to open a filehandle to slurp. This means if your upload charset is \s-1UTF8\s0 we binmode the filehandle to that encoding. .ie n .SS "$upload\->basename" .el .SS "\f(CW$upload\fP\->basename" .IX Subsection "$upload->basename" Returns basename for \f(CW\*(C`filename\*(C'\fR. This filters the name through a regexp \&\f(CW\*(C`basename =~ s|[^\ew\e.\-]+|_|g\*(C'\fR to make it safe for filesystems that don't like advanced characters. This will of course filter \s-1UTF8\s0 characters. If you need the exact basename unfiltered use \f(CW\*(C`raw_basename\*(C'\fR. .ie n .SS "$upload\->raw_basename" .el .SS "\f(CW$upload\fP\->raw_basename" .IX Subsection "$upload->raw_basename" Just like \f(CW\*(C`basename\*(C'\fR but without filtering the filename for characters that don't always write to a filesystem. .ie n .SS "$upload\->tempname" .el .SS "\f(CW$upload\fP\->tempname" .IX Subsection "$upload->tempname" Returns the path to the temporary file. .ie n .SS "$upload\->type" .el .SS "\f(CW$upload\fP\->type" .IX Subsection "$upload->type" Returns the client-supplied Content-Type. .ie n .SS "$upload\->charset" .el .SS "\f(CW$upload\fP\->charset" .IX Subsection "$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. .SS "meta" .IX Subsection "meta" Provided by Moose .SH "AUTHORS" .IX Header "AUTHORS" Catalyst Contributors, see Catalyst.pm .SH "COPYRIGHT" .IX Header "COPYRIGHT" This library is free software. You can redistribute it and/or modify it under the same terms as Perl itself.