NAME

WeBWorK::Upload - store uploads securely across requests.

SYNOPSIS

Given $u, a Mojo::Upload object

my $upload  = WeBWorK::Upload->store($u, $ce->{webworkDirs}{uploadCache});
my $tmpFile = $upload->tmpFile;
my $hash    = $upload->hash;

Later...

my $upload = WeBWorK::Upload->retrieve($tmpFile, $hash, $ce->{webworkDirs}{uploadCache});
my $fh     = $upload->fileHandle;
my $path   = $upload->filePath;

# Get rid of the upload -- $upload is useless after this!
$upload->dispose;

# Or move it somewhere and dispose of it - $upload is also useless after this!
$upload->disposeTo($path);

DESCRIPTION

WeBWorK::Upload provides a method for securely storing uploaded files until such time as they are needed. This is useful for situations in which an upload needs to be handled in a later request. WeBWorK::Upload generates a unique temporary file name and hash which can be used to retrieve the original file.

STORING UPLOADS

Uploads can be stored in an upload cache and later retrieved, given the temporary file name and hash. The hash is used to confirm the authenticity of the temporary file.

Uploads are constructed from Mojo::Upload objects.

store

my $upload = WeBWorK::Upload->store($u, $dir);

Stores the Mojo::Upload $u into the directory specified by $dir.

tmpFile

Return the temporary file name of the upload, or an undefined value if the upload is not valid.

hash

Return the hash of the upload, or an undefined value if the upload is not valid.

RETRIEVING UPLOADS

An upload stored in the upload cache can be retrieved by supplying its temporary file name and hash (accessible from the above tmpFile and hash methods), respectively. The file can then be accessed by name or file handle, moved, and disposed of.

retrieve

my $upload = WeBWorK::Upload->retrieve($tmpFile, $hash, $dir);

Retrieves the upload referenced by $tempFile and $hash and located in $dir.

METHODS

filename

Returns the original name of the uploaded file, or an undefined value if the upload is not valid.

fileHandle

Return a file handle pointing to the uploaded file suitable for reading, or an undefined value if the upload is not valid.

filePath

Return the path to the uploaded file, or an undefined value if the upload is not valid.

If you use this, bear in mind that you must not dispose of the upload (either by moving or deleting the uploaded file or calling the dispose method). If you wish to move the file, use the disposeTo method instead.

dispose

Remove the file from the upload cache.

disposeTo

$upload->diposeTo($path);

Remove the file from the upload cache, and move it to $path. Returns the destination as a Mojo::File object if the upload was successfully moved, or an undefined value if the upload is not valid.