/ 
Uniform-Upload-0.02
/ Uniform::Upload

NAME

Uniform::Upload - Framework-agnostic upload manager and base driver engine

SYNOPSIS

use Uniform::Upload;

# Standalone manager setup
my $upload = Uniform::Upload->new(
    max_size      => '5MB',
    allowed_types => [qw( image/png image/jpeg application/pdf )],
);

# Wrap raw upload payload hashes into validated objects
my $file = $upload->wrap(
    name     => 'avatar',
    filename => 'user_photo.png',
    tmp_path => '/tmp/cpan_upload_12345',
    size     => 2048576,
    type     => 'image/png',
);

if ($file->is_valid) {
    $file->copy_to('/var/uploads/' . $file->sanitized_filename);
} else {
    die "Upload failed validation: " . $file->error;
}

DESCRIPTION

Uniform::Upload provides a unified interface for inspecting, validating, and managing uploaded files across web applications. It acts as both a standalone file upload factory and an abstract base engine for framework-specific extension drivers (such as Uniform::Upload::PAGI or Uniform::Upload::Plack).

METHODS

new

my $upload = Uniform::Upload->new(%options);

Constructs a new manager object. Supported options:

  • max_size

    Maximum file size cap. Accepts raw byte integers or human-readable strings like '2MB' or '500KB' (parsed via Uniform::Utils).

  • allowed_types

    Array reference of allowed MIME type strings (e.g., ['image/png', 'image/jpeg']).

  • file_class

    Package name used to wrap file payloads. Defaults to Uniform::Upload::File.

wrap

my $file = $upload->wrap(%file_args);

Instantiates and returns a new Uniform::Upload::File (or custom file_class) instance initialized with the manager's global validation parameters.

extract

my $files = $upload->extract;

Abstract factory method intended to be overridden by subclass drivers to parse incoming framework request payloads. Croaks if invoked directly on Uniform::Upload.

max_size

Returns the parsed byte cap for uploads, or undef if unrestricted.

allowed_types

Returns the array reference of configured MIME type string constraints.

file_class

Returns the target file wrapper class package name.

INHERITANCE AND SUBCLASSING

Subclass drivers extend Uniform::Upload using object-oriented inheritance via parent and constructor delegation with SUPER::new:

package Uniform::Upload::MyFramework;

use strict;
use warnings;
use parent 'Uniform::Upload';
use Scalar::Util qw(blessed);
use Carp qw(croak);

sub new {
    my ($class, $req, %args) = @_;

    croak "Requires request object" unless blessed($req);

    return $class->SUPER::new(
        in => $req,
        %args,
    );
}

sub extract {
    my ($self) = @_;
    my $req = $self->{in};

    my @files;
    for my $raw ($req->uploads) {
        push @files, $self->wrap(%$raw);
    }
    return \@files;
}

1;

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