NAME

CGI::Tiny::Multipart - Tiny multipart/form-data parser

SYNOPSIS

use CGI::Tiny::Multipart qw(extract_multipart_boundary parse_multipart_form_data);

my $boundary = extract_multipart_boundary($content_type) // die "Failed to parse multipart boundary";
my $parts = parse_multipart_form_data($fh, $content_length, $boundary) // die "Malformed multipart/form-data content";

DESCRIPTION

CGI::Tiny::Multipart is a tiny multipart/form-data parser for CGI::Tiny.

FUNCTIONS

The following functions are exported on request.

extract_multipart_boundary

my $boundary = extract_multipart_boundary($content_type);

Extracts the multipart boundary from a Content-Type header. Returns undef if the boundary was not found.

parse_multipart_form_data

my $parts = parse_multipart_form_data($fh, $content_length, $boundary, \%options);
my $parts = parse_multipart_form_data(\$bytes, length($bytes), $boundary, \%options);

Parses multipart/form-data request content into an ordered array reference, or returns undef if the request content is malformed and cannot be parsed. The input parameter may be a filehandle, which will have binmode applied to remove any translation layers, or a scalar reference to a string containing the request content. Bytes will be read from the input up to the specified $content_length.

The following options may be specified in an optional hashref parameter:

buffer_size

buffer_size => 262144

Buffer size (number of bytes to read at once) for reading the request body from an input filehandle. Defaults to 262144 (256 KiB). A value of 0 will use the default value.

tempfile_args

tempfile_args => [TEMPLATE => 'tempXXXXX', SUFFIX => '.dat']

Arguments to pass to the File::Temp constructor when creating tempfiles for file uploads. By default no arguments are passed.

tempfiles

tempfiles => 1
tempfiles => 0

If set to a true value, all form field values will be stored in tempfiles instead of memory, not just file uploads. If set to a false (but defined) value, all form fields values will be stored in memory, even file uploads. By default, text field values will be stored in memory and file uploads will be stored in tempfiles.

discard_files

discard_files => 1

If set to a true value, file upload field contents will be discarded, and neither content nor file will be provided for those form fields.

Form fields are represented as hash references containing:

headers

Hash reference of part headers. Header names are represented in lowercase.

name

Form field name from Content-Disposition header, undecoded.

filename

Filename from Content-Disposition header if present, undecoded.

size

Size of part contents in bytes.

content

Part contents as undecoded bytes, for parts without a defined filename, or for all parts if the tempfiles option was set to a false value. File uploads are stored in a temporary file instead by default.

file

File::Temp object referencing temporary file containing the part contents, for parts with a defined filename, or for all parts if the tempfiles option was set to a true value.

BUGS

Report any issues on the public bugtracker.

AUTHOR

Dan Book <dbook@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2021 by Dan Book.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)

SEE ALSO

HTTP::Body::MultiPart