NAME
PAGI::Request::Upload - Uploaded file representation
SYNOPSIS
my $upload = await $req->upload('avatar');
if ($upload && !$upload->is_empty) {
my $filename = $upload->filename;
my $size = $upload->size;
my $content = $upload->slurp;
$upload->move_to('/path/to/save');
}DESCRIPTION
PAGI::Request::Upload represents an uploaded file from a multipart form. Files may be stored in memory (small files) or spooled to a temporary file (large files).
CONSTRUCTOR
new
my $upload = PAGI::Request::Upload->new(
field_name => 'avatar',
filename => 'photo.jpg',
content_type => 'image/jpeg',
data => $bytes, # OR
temp_path => '/tmp/abc123', # for spooled files
size => 12345,
);PROPERTIES
field_name
Form field name.
filename
Original filename from the upload.
basename
Filename without path components (safe for filesystem use).
content_type
MIME type of the uploaded file.
size
File size in bytes.
temp_path
Path to temporary file (if spooled to disk).
PREDICATES
is_empty
True if no data was uploaded.
is_in_memory
True if file data is stored in memory.
is_on_disk
True if file data is spooled to a temp file.
CONTENT METHODS
slurp
my $bytes = $upload->slurp;Read entire file content into memory.
fh
my $fh = $upload->fh;Get a filehandle for reading the upload.
FILE METHODS
move_to
$upload->move_to('/path/to/destination');Move the uploaded file to a destination path. Returns the upload object for chaining.
Note: This is a blocking operation that performs synchronous file I/O. For most uploads this completes quickly:
On-disk uploads use
File::Copy::move()(typically a fast rename)In-memory uploads write data directly to the destination file
For very large files where blocking is a concern, use slurp() or fh() to access the data and handle file I/O yourself with your preferred async file library:
# Non-blocking alternative (bring your own async file library)
my $data = $upload->slurp;
await $my_async_file_writer->write($destination, $data);
# Or stream via filehandle
my $fh = $upload->fh;
while (my $chunk = read($fh, my $buf, 65536)) {
await $my_async_writer->write($buf);
}CLEANUP
Temporary files are automatically deleted when the Upload object is destroyed. If you want to keep the file, use move_to.