NAME

FU::MultipartFormData - Parse multipart/form-data

SYNOPSIS

my $fields = FU::MultipartFormData->parse($content_type_header, $request_body);

for my $f (@$fields) {
    print "%s   %d\n", $f->name, $f->length;

    $f->save('file.png') if $f->name eq 'image';
}

DESCRIPTION

This is a tiny module to parse an HTTP request body encoded as multipart/form-data, which is typically used to handle file uploads.

The entire request body is assumed to be in memory as a Perl string, but this module makes an attempt to avoid any further copies of data values.

Parsing

Returns an array of field objects from the given $header, which must be a valid value for the Content-Type request header, and the given $body, which must hold the request body as a byte string. An error is thrown if the header is not valid or parsing failed.

This module is pretty lousy and does not fully comform to any HTTP standards, but it does happen to be able to parse POST data from any browser that I've tried.

Field Object

Each field is parsed into a field object that supports the following methods:

name

Returns the field name as a Perl Unicode string.

filename

Returns the filename as a Perl Unicode string, or undef if no filename was provided.

mime

Returns the mime type extracted from the field's Content-Type header, or undef if none was present.

charset

Returns the charset extracted from the field's Content-Type header, or undef if none was present.

length

Returns the byte length of the field value.

data

Returns a copy of the field value as a byte string. You'll want to avoid using this on large fields.

value

Returns a copy of the field value as a Unicode string. Uses utf8_decode() from FU::Util, so also throws an error if the value contains control characters.

substr($off, $len)

Equivalent to calling substr() on the string returned by data, but avoids a copy of the entire field value.

syswrite($fh)

Write the field value to $fh using Perl's syswrite(), returns undef on error or the number of bytes written on success.

Can be used to write uploaded file data to a file or send it over a socket or pipe, without making a full in-memory copy of the data.

save($fn)

Save the field value to the file $fn, throws an error on failure.

describe

Returns a human-readable string to describe this field. Mainly for debugging purposes, the exact format is subject to change.

COPYRIGHT

MIT.

AUTHOR

Yorhel <projects@yorhel.nl>