NAME

Uniform::Upload - Extensible, framework-agnostic base specification layer for multi-part file uploads

SYNOPSIS

This is an abstract base module. It should not be used directly. Instead, implement or install a framework-specific driver subclass (e.g. Uniform::Upload::PSGI):

package Uniform::Upload::PSGI;
use parent 'Uniform::Upload';

sub new {
    my ($class, $env) = @_;
    my $self = bless { files => {} }, $class;

    # ... Framework specific file metadata extraction logic ...
    # $self->{files}->{$field} = \%file_meta;

    return $self;
}

DESCRIPTION

Uniform::Upload provides a unified, object-oriented specification interface for validating and storing incoming multi-part form file uploads. By isolating framework semantics, application file handling logic remains completely portable.

Subclasses are responsible for populating $self->{files}, a hashref keyed by form field name, with the raw upload metadata their framework provides (typically a hashref containing tempname, filename, size, and type — see "new" in Uniform::Upload::File). Everything else — lazy wrapping, validation, and persistence — is handled by this class and Uniform::Upload::File.

METHODS

has_file( $field_name )

Returns 1 if an upload payload exists for the specified multi-part form key, otherwise returns 0. Also returns 0 (rather than throwing) if $field_name is undefined.

file( $field_name )

Returns a Uniform::Upload::File object instance wrapping the targeted input parameters. The underlying raw hashref is wrapped lazily on first access and the wrapped object is cached in place, so subsequent calls for the same field return the same instance.

Throws an exception via Uniform::Exceptions, as follows:

• type ValidationError if $field_name is undefined or an empty string.

• type NotFoundError if no upload payload exists for $field_name (i.e. has_file would return false for it).

SEE ALSO

Uniform::Upload::File, Uniform::Exceptions

AUTHOR

Joshua S. Day <HAX@cpan.org>

LICENSE

MIT License. Copyright (c) 2026 Joshua S. Day.