HTTP::Entity::Parser(3pm)

1HTTP::Entity::Parser(3pUms)er Contributed Perl DocumentatHiToTnP::Entity::Parser(3pm)
2
3
4

NAME

6       HTTP::Entity::Parser - PSGI compliant HTTP Entity Parser
7

SYNOPSIS

9           use HTTP::Entity::Parser;
10
11           my $parser = HTTP::Entity::Parser->new;
12           $parser->register('application/x-www-form-urlencoded','HTTP::Entity::Parser::UrlEncoded');
13           $parser->register('multipart/form-data','HTTP::Entity::Parser::MultiPart');
14           $parser->register('application/json','HTTP::Entity::Parser::JSON');
15
16           sub app {
17               my $env = shift;
18               my ( $params, $uploads) = $parser->parse($env);
19           }
20

DESCRIPTION

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

METHODS

30       new( buffer_length => $length:Intger)
31           Create the instance.
32
33           buffer_length
34               The buffer length that HTTP::Entity::Parser reads from
35               psgi.input. 16384 by default.
36
37       register($content_type:String, $class:String, $opts:HashRef)
38           Register parser class.
39
40             $parser->register('application/x-www-form-urlencoded','HTTP::Entity::Parser::UrlEncoded');
41             $parser->register('multipart/form-data','HTTP::Entity::Parser::MultiPart');
42             $parser->register('application/json','HTTP::Entity::Parser::JSON');
43
44           If the request content_type matches the registered type,
45           HTTP::Entity::Parser uses the registered parser class. If
46           content_type does not match any registered type,
47           HTTP::Entity::Parser::OctetStream is used.
48
49       parse($env:HashRef)
50           parse HTTP entities from PSGI's env.
51
52             my ( $params:ArrayRef, $uploads:ArrayRef) = $parser->parse($env);
53
54           $param is a key-value pair list.
55
56              my ( $params, $uploads) = $parser->parse($env);
57              my $body_parameters = Hash::MultiValue->new(@$params);
58
59           $uploads is an ArrayRef of HashRef.
60
61              my ( $params, $uploads) = $parser->parse($env);
62              warn Dumper($uploads->[0]);
63              {
64                  "name" => "upload", #field name
65                  "headers" => [
66                      "Content-Type" => "application/octet-stream",
67                      "Content-Disposition" => "form-data; name=\"upload\"; filename=\"hello.pl\""
68                  ],
69                  "size" => 78, #size of upload content
70                  "filename" => "hello.png", #original filename in the client
71                  "tempname" => "/tmp/XXXXX", # path to the temporary file where uploaded file is saved
72              }
73
74           When used with Plack::Request::Upload:
75
76              my ( $params, $uploads) = $parser->parse($env);
77               my $upload_hmv = Hash::MultiValue->new();
78               while ( my ($k,$v) = splice @$uploads, 0, 2 ) {
79                   my %copy = %$v;
80                   $copy{headers} = HTTP::Headers::Fast->new(@{$v->{headers}});
81                   $upload_hmv->add($k, Plack::Request::Upload->new(%copy));
82               }
83

PARSERS

85       OctetStream
86           Default parser, This parser does not parse entity, always return
87           empty list.
88
89       UrlEncoded
90           For "application/x-www-form-urlencoded". It is used for HTTP POST
91           without file upload
92
93       MultiPart
94           For "multipart/form-data". It is used for HTTP POST contains file
95           upload.
96
97           MultiPart parser use HTTP::MultiPartParser.
98
99       JSON
100           For "application/json". This parser decodes JSON body
101           automatically.
102
103           It is convenient to use with Ajax forms.
104

WHAT'S DIFFERENT FROM HTTP::Body

106       HTTP::Entity::Parser accept PSGI's env and read body from it.
107
108       HTTP::Entity::Parser is able to choose parsers by the instance,
109       HTTP::Body requires to modify global variables.
110

LICENSE

120       Copyright (C) Masahiro Nagano.
121
122       This library is free software; you can redistribute it and/or modify it
123       under the same terms as Perl itself.
124

AUTHOR

126       Masahiro Nagano <kazeburo@gmail.com>
127
128       Tokuhiro Matsuno <tokuhirom@gmail.com>
129
130       This module is based on tokuhirom's code, see
131       <https://github.com/plack/Plack/pull/434>
132
133
134
135perl v5.38.0                      2023-07-20         HTTP::Entity::Parser(3pm)