DOKK / manpages / debian 12 / libhttp-entity-parser-perl / HTTP::Entity::Parser.3pm.en
HTTP::Entity::Parser(3pm) User Contributed Perl Documentation HTTP::Entity::Parser(3pm)

HTTP::Entity::Parser - PSGI compliant HTTP Entity Parser

    use HTTP::Entity::Parser;
    my $parser = HTTP::Entity::Parser->new;
    $parser->register('application/x-www-form-urlencoded','HTTP::Entity::Parser::UrlEncoded');
    $parser->register('multipart/form-data','HTTP::Entity::Parser::MultiPart');
    $parser->register('application/json','HTTP::Entity::Parser::JSON');
    sub app {
        my $env = shift;
        my ( $params, $uploads) = $parser->parse($env);
    }

HTTP::Entity::Parser is a PSGI-compliant HTTP Entity parser. This module also is compatible with HTTP::Body. Unlike HTTP::Body, HTTP::Entity::Parser reads HTTP entities from PSGI's environment "$env->{'psgi.input'}" and parses it. This module supports application/x-www-form-urlencoded, multipart/form-data and application/json.

Create the instance.
The buffer length that HTTP::Entity::Parser reads from psgi.input. 16384 by default.
Register parser class. 

  $parser->register('application/x-www-form-urlencoded','HTTP::Entity::Parser::UrlEncoded');
  $parser->register('multipart/form-data','HTTP::Entity::Parser::MultiPart');
  $parser->register('application/json','HTTP::Entity::Parser::JSON');

If the request content_type matches the registered type, HTTP::Entity::Parser uses the registered parser class. If content_type does not match any registered type, HTTP::Entity::Parser::OctetStream is used.

parse HTTP entities from PSGI's env. 

  my ( $params:ArrayRef, $uploads:ArrayRef) = $parser->parse($env);

$param is a key-value pair list.

   my ( $params, $uploads) = $parser->parse($env);
   my $body_parameters = Hash::MultiValue->new(@$params);

$uploads is an ArrayRef of HashRef.

   my ( $params, $uploads) = $parser->parse($env);
   warn Dumper($uploads->[0]);
   {
       "name" => "upload", #field name
       "headers" => [
           "Content-Type" => "application/octet-stream",
           "Content-Disposition" => "form-data; name=\"upload\"; filename=\"hello.pl\""
       ],
       "size" => 78, #size of upload content
       "filename" => "hello.png", #original filename in the client
       "tempname" => "/tmp/XXXXX", # path to the temporary file where uploaded file is saved
   }

When used with Plack::Request::Upload:

   my ( $params, $uploads) = $parser->parse($env);
    my $upload_hmv = Hash::MultiValue->new();
    while ( my ($k,$v) = splice @$uploads, 0, 2 ) {
        my %copy = %$v;
        $copy{headers} = HTTP::Headers::Fast->new(@{$v->{headers}});
        $upload_hmv->add($k, Plack::Request::Upload->new(%copy));
    }

Default parser, This parser does not parse entity, always return empty list.
For "application/x-www-form-urlencoded". It is used for HTTP POST without file upload
For "multipart/form-data". It is used for HTTP POST contains file upload.

MultiPart parser use HTTP::MultiPartParser.

For "application/json". This parser decodes JSON body automatically.

It is convenient to use with Ajax forms.

HTTP::Entity::Parser accept PSGI's env and read body from it.

HTTP::Entity::Parser is able to choose parsers by the instance, HTTP::Body requires to modify global variables.

HTTP::Entity::Parser uses this for parse application/x-www-form-urlencoded

Copyright (C) Masahiro Nagano.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Masahiro Nagano <kazeburo@gmail.com>

Tokuhiro Matsuno <tokuhirom@gmail.com>

This module is based on tokuhirom's code, see <https://github.com/plack/Plack/pull/434>

2022-08-28 perl v5.34.0