NAME
Uniform::Upload::File - Value object wrapping a single uploaded file's metadata and operations
SYNOPSIS
Instances of this class are not normally constructed directly. They are returned by "file" in Uniform::Upload, which lazily wraps the raw upload metadata a driver subclass collected:
my $file = $upload->file('avatar_field');
$file->max_size('2M');
$file->allowed_types(['image/jpeg', 'image/png']);
$file->sanitize_filename;
$file->save_to('/var/www/uploads/');DESCRIPTION
Uniform::Upload::File wraps the raw tempname/filename/size/type tuple produced by a framework's upload handling and provides a uniform, chainable interface for validating, sanitizing, and persisting the file. All validation and I/O methods throw Uniform::Exceptions on failure rather than returning false, and return $self on success so calls can be chained.
METHODS
new( \%meta )
Constructs a new instance from a hashref of raw metadata. Recognized keys are tempname, filename, size, and type; any that are missing default to undef (or 0 for size). This is normally called for you by "file" in Uniform::Upload, not directly by application code.
size
Returns the file's size in bytes, as reported by the upload metadata.
type
Returns the file's MIME type, as reported by the upload metadata.
filename
Returns the file's current filename. This reflects whatever was passed in at construction time, unless it has since been overwritten by "sanitize_filename" (which save_to also calls internally).
max_size( $limit )
Validates that "size" does not exceed $limit. Size string parsing is delegated to "parse_size_limit" in Uniform::Utils: $limit may be a human-readable size string such as '2M', '500K', or '1G' (kilobytes/megabytes/gigabytes, 1024-based), or a plain number of bytes. Throws a ValidationError if $limit is missing or unparsable (raised by "parse_size_limit" in Uniform::Utils), or if the limit is exceeded (raised here). Returns $self on success.
allowed_types( \@mime_types )
Validates that "type" exactly matches one of the strings in \@mime_types. Throws a ValidationError if the arrayref is missing/empty, or if the file's type is not in the list. Returns $self on success.
sanitize_filename
Rewrites "filename" in place to a safe, flat filename: cross-platform path separators are normalized, any directory component is stripped (via File::Basename), null bytes are removed, and remaining characters outside [a-zA-Z0-9._-] are collapsed to hyphens. If sanitization would produce an empty or meaningless name, it falls back to 'uploaded_file'. Returns $self. Safe to call on a file with no filename set (a no-op in that case).
save_to( $destination )
Copies the file from its temporary source path to $destination. Always calls "sanitize_filename" first, so the copied file is written under a safe name regardless of whether the caller sanitized it beforehand — note this means "filename" may be mutated as a side effect of calling save_to.
If $destination ends in a path separator, or is an existing directory, the file is written inside it under its (now-sanitized) filename; otherwise $destination is treated as the full target path. Throws a ValidationError if $destination is missing, an IOError if the temporary source file no longer exists, and an IOError if the copy itself fails. Returns $self on success.
SEE ALSO
Uniform::Upload, Uniform::Exceptions, Uniform::Utils
AUTHOR
Joshua S. Day <HAX@cpan.org>
LICENSE
MIT License. Copyright (c) 2026 Joshua S. Day.