NAME

CGI::Tiny::Multipart - Tiny multipart/form-data form 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, based on RFC 2388 and RFC 7578.

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.

parse_as_files

  parse_as_files => 1
  parse_as_files => 0

If set to a true value, all form field values will be parsed as file uploads, calling on_file_buffer or storing the contents in a tempfile. If set to a false (but defined) value, all form field values will be returned as content, even file uploads. By default, text field values will be returned as content and file uploads will be parsed by on_file_buffer or stored in tempfiles.

on_file_buffer

  on_file_buffer => sub { my ($bytes, $hashref, $eof) = @_; }

Callback for custom parsing of file upload form fields. If specified, it will be called with each (possibly empty) chunk of file contents that is read from the form as bytes. The hash reference representing this form field is passed as the second argument. The third argument will be true the last time the callback is called for a particular form field.

The hash reference passed to the callback persists between calls for the same form field, and is the same hash reference that will ultimately be returned to represent the form field. It will contain the headers, undecoded name and filename, and size of contents read so far (including the bytes just passed to the callback). Modifying these values may result in unexpected behavior, but other modifications to the hash reference are allowed.

If on_file_buffer is not specified, file uploads will be stored in file as a File::Temp object created with tempfile_args.

  # approximate the default behavior
  on_file_buffer => sub {
    my ($bytes, $hashref, $eof) = @_;
    $hashref->{file} //= File::Temp->new;
    print {$hashref->{file}} $bytes;
    if ($eof) {
      $hashref->{file}->flush;
      seek $hashref->{file}, 0, 0;
    }
  }

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. Not used if a custom on_file_buffer callback is passed.

discard_files

  discard_files => 1

If set to a true value, file upload field contents will be discarded without calling on_file_buffer, and neither content nor file will be provided for those form fields. Note that this discards the contents of form fields with a defined filename regardless of the parse_as_files setting.

Form fields are represented as hash references containing:

headers

Hash reference of form field 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 form field contents in bytes.

content

Form field contents as undecoded bytes, for form fields without a defined filename, or for all form fields if the parse_as_files 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 form field contents, for form fields with a defined filename, or for all form fields if the parse_as_files 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