/ 
Uniform-Upload-0.02
/ Uniform::Upload::File

NAME

Uniform::Upload::File - Encapsulated file upload wrapper with validation and file management

SYNOPSIS

use Uniform::Upload::File;

my $file = Uniform::Upload::File->new(
    name          => 'attachment',
    filename      => '../../../etc/passwd.jpg',
    tmp_path      => '/tmp/upload_tmp_8812',
    size          => 10240,
    type          => 'image/jpeg',
    max_size      => 1048576,
    allowed_types => ['image/jpeg'],
);

if ($file->is_valid) {
    print $file->sanitized_filename; # Output: passwd.jpg
    $file->copy_to('/var/data/uploads/' . $file->sanitized_filename);
} else {
    warn $file->error;
}

DESCRIPTION

Uniform::Upload::File encapsulates individual file payloads. It executes automated size and MIME type checks upon instantiation, sanitizes user-supplied filenames to prevent path traversal attacks, and handles file movement operations safely.

METHODS

new

my $file = Uniform::Upload::File->new(%args);

Constructs and validates the file wrapper. Populates error if size exceeds max_size or if type does not match allowed_types.

is_valid

Returns 1 if the file passed all validation checks, or 0 if invalid.

error

Returns the validation error message string if invalid, or undef if valid.

name

Returns the form parameter field name associated with the upload.

filename

Returns the raw original filename supplied by the client.

sanitized_filename

my $clean_name = $file->sanitized_filename;

Strips leading directory path structures and replaces unsafe characters (excluding letters, numbers, dots, hyphens, and underscores) with underscores to eliminate path traversal threats.

tmp_path

Returns the path to the buffered temporary file on disk.

size

Returns the file payload size in bytes.

type

Returns the declared MIME type string.

copy_to

$file->copy_to($destination_path);

Copies the temporary file to the destination path. Croaks if called on an invalid file or throws a Uniform::Exceptions exception on filesystem failure.

move_to

$file->move_to($destination_path);

Moves the temporary file to the destination path. Croaks if called on an invalid file or throws a Uniform::Exceptions exception on filesystem failure.

SEE ALSO

AUTHOR

Joshua S. Day <HAX@cpan.org>

LICENSE AND COPYRIGHT

This software is Copyright (c) 2026 by Joshua S. Day[cite: 9].

This is free software, licensed under:

The MIT (X11) License