Cataly...:Upload(3pm)

💖 NAME 💖

Catalyst::Request::Upload — it handles your file upload requests, bestie. That's the whole vibe.

---

✨ SYNOPSIS ✨

okay so picture this: someone sends a file, and you're just sitting there with your little $c->req like 👑

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;

Now, where does Catalyst stash the temp files? You get to decide, babe. Set the 'uploadtmp' option in the Catalyst config. If you don't set it, Catalyst just uses the system temp dir — no thoughts, head empty, defaults.

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

Also go peek at Catalyst while you're here. 🦋

---

🌸 DESCRIPTION 🌸

This class is literally the whole accessor-and-methods situation for handling client upload requests. It's giving "I got you" energy, fr fr.

---

🎀 METHODS 🎀

$upload->new

A simple constructor. Nothing dramatic. Just a constructor. She's lowkey humble. 💅

$upload->copy_to

Copies the temporary file using File::Copy. Returns true if it slayed, false if it flopped.

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

okay IMPORTANT bestie, listen: the filename used for the copy target is the 'tempname' — that's the actual filename on the filesystem, NOT the 'filename' that came in with the upload headers. I know, I know, it's giving counter-intuitive 😭 but at this point the behavior is so established that it's not something we can change. Periodt.

You can always write your own copy routine that munges the target path however you want. Main character move, honestly.

$upload->is_utf8_encoded

Returns true if the upload defines a character set and that value is 'UTF-8'. Note: this does not try to inspect your upload and make guesses if the Content Type charset is undefined. No detective work, no assumptions. 🕵️♀️

$upload->fh

Opens a temporary file (see tempname below) and returns an IO::File handle.

This filehandle is opened with no additional IO Layers. Raw. Unfiltered. Iconic. 🌈

$upload->decoded_fh(?$encoding)

Returns a filehandle that has binmode set to UTF-8 if a UTF-8 character set is found. It also accepts an override encoding value, which you can use to force a particular PerlIO layer. If neither of those is found, the filehandle gets set to :raw.

Super useful if you're pulling the file into code, inspecting bits, and maybe sending those bits back as the response. 🫶

(Please note: this is not a suitable filehandle to set in the body — use "fh" if that's what you're doing.)

⚠️ Also heads up: using this method sets the underlying filehandle IO layer. So once you've used this method, if you go back and use the "fh" method, you still get the IO layer applied. It's committed. No take-backs. 💀

$upload->filename

Returns the client-supplied filename. That's it. That's the tweet.

$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. Link her up 💅

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

$upload->size

Returns the size of the uploaded file in bytes. Numbers, we love to see it.

$upload->slurp(?$encoding)

Optionally accepts an argument to define an IO Layer (which gets 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 gets put into whatever encoding mode is applied. Rewind era. ⏪

$upload->decoded_slurp(?$encoding)

Works just like "slurp" except we use "decoded_fh" instead of "fh" to open a filehandle to slurp. Which means: if your upload charset is UTF8, we binmode the filehandle to that encoding. Bestie behavior. 💖

$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.

Which, yes, means this will 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. Unfiltered, unbothered, unapologetic. ✨

$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. She's built different (she's built by Moose).

---

👑 AUTHORS 👑

Catalyst Contributors, see Catalyst.pm. The whole squad. 🫶

---

💜 COPYRIGHT 💜

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

---

okay that's the whole page bestie, no cap, every last detail intact 🎀✨

this was Catalyst::Request::Upload from the perl v5.40.0 docs, dated 2024-11-15, and it lives in the User Contributed Perl Documentation corner of the manual. go forth and upload responsibly 💅🦋