HTTP::Request::Common(3pm)

1HTTP::Request::Common(3U)ser Contributed Perl DocumentatiHoTnTP::Request::Common(3)
2
3
4

NAME

6       HTTP::Request::Common - Construct common HTTP::Request objects
7

VERSION

9       version 6.18
10

SYNOPSIS

12         use HTTP::Request::Common;
13         $ua = LWP::UserAgent->new;
14         $ua->request(GET 'http://www.sn.no/');
15         $ua->request(POST 'http://somewhere/foo', [foo => bar, bar => foo]);
16         $ua->request(PATCH 'http://somewhere/foo', [foo => bar, bar => foo]);
17         $ua->request(PUT 'http://somewhere/foo', [foo => bar, bar => foo]);
18

DESCRIPTION

20       This module provides functions that return newly created
21       "HTTP::Request" objects.  These functions are usually more convenient
22       to use than the standard "HTTP::Request" constructor for the most
23       common requests.
24
25       Note that LWP::UserAgent has several convenience methods, including
26       "get", "head", "delete", "post" and "put".
27
28       The following functions are provided:
29
30       GET $url
31       GET $url, Header => Value,...
32           The "GET" function returns an HTTP::Request object initialized with
33           the "GET" method and the specified URL.  It is roughly equivalent
34           to the following call
35
36             HTTP::Request->new(
37                GET => $url,
38                HTTP::Headers->new(Header => Value,...),
39             )
40
41           but is less cluttered.  What is different is that a header named
42           "Content" will initialize the content part of the request instead
43           of setting a header field.  Note that GET requests should normally
44           not have a content, so this hack makes more sense for the "PUT",
45           "PATCH"
46            and "POST" functions described below.
47
48           The "get(...)" method of LWP::UserAgent exists as a shortcut for
49           "$ua->request(GET ...)".
50
51       HEAD $url
52       HEAD $url, Header => Value,...
53           Like GET() but the method in the request is "HEAD".
54
55           The "head(...)"  method of LWP::UserAgent exists as a shortcut for
56           "$ua->request(HEAD ...)".
57
58       DELETE $url
59       DELETE $url, Header => Value,...
60           Like "GET" but the method in the request is "DELETE".  This
61           function is not exported by default.
62
63       PATCH $url
64       PATCH $url, Header => Value,...
65       PATCH $url, $form_ref, Header => Value,...
66       PATCH $url, Header => Value,..., Content => $form_ref
67       PATCH $url, Header => Value,..., Content => $content
68           The same as "POST" below, but the method in the request is "PATCH".
69
70       PUT $url
71       PUT $url, Header => Value,...
72       PUT $url, $form_ref, Header => Value,...
73       PUT $url, Header => Value,..., Content => $form_ref
74       PUT $url, Header => Value,..., Content => $content
75           The same as "POST" below, but the method in the request is "PUT"
76
77       POST $url
78       POST $url, Header => Value,...
79       POST $url, $form_ref, Header => Value,...
80       POST $url, Header => Value,..., Content => $form_ref
81       POST $url, Header => Value,..., Content => $content
82           "POST", "PATCH" and "PUT" all work with the same parameters.
83
84             %data = ( title => 'something', body => something else' );
85             $ua = LWP::UserAgent->new();
86             $request = HTTP::Request::Common::POST( $url, [ %data ] );
87             $response = $ua->request($request);
88
89           They take a second optional array or hash reference parameter
90           $form_ref.  The content can also be specified directly using the
91           "Content" pseudo-header, and you may also provide the $form_ref
92           this way.
93
94           The "Content" pseudo-header steals a bit of the header field
95           namespace as there is no way to directly specify a header that is
96           actually called "Content".  If you really need this you must update
97           the request returned in a separate statement.
98
99           The $form_ref argument can be used to pass key/value pairs for the
100           form content.  By default we will initialize a request using the
101           "application/x-www-form-urlencoded" content type.  This means that
102           you can emulate an HTML <form> POSTing like this:
103
104             POST 'http://www.perl.org/survey.cgi',
105                  [ name   => 'Gisle Aas',
106                    email  => 'gisle@aas.no',
107                    gender => 'M',
108                    born   => '1964',
109                    perc   => '3%',
110                  ];
111
112           This will create an HTTP::Request object that looks like this:
113
114             POST http://www.perl.org/survey.cgi
115             Content-Length: 66
116             Content-Type: application/x-www-form-urlencoded
117
118             name=Gisle%20Aas&email=gisle%40aas.no&gender=M&born=1964&perc=3%25
119
120           Multivalued form fields can be specified by either repeating the
121           field name or by passing the value as an array reference.
122
123           The POST method also supports the "multipart/form-data" content
124           used for Form-based File Upload as specified in RFC 1867.  You
125           trigger this content format by specifying a content type of
126           'form-data' as one of the request headers.  If one of the values in
127           the $form_ref is an array reference, then it is treated as a file
128           part specification with the following interpretation:
129
130             [ $file, $filename, Header => Value... ]
131             [ undef, $filename, Header => Value,..., Content => $content ]
132
133           The first value in the array ($file) is the name of a file to open.
134           This file will be read and its content placed in the request.  The
135           routine will croak if the file can't be opened.  Use an "undef" as
136           $file value if you want to specify the content directly with a
137           "Content" header.  The $filename is the filename to report in the
138           request.  If this value is undefined, then the basename of the
139           $file will be used.  You can specify an empty string as $filename
140           if you want to suppress sending the filename when you provide a
141           $file value.
142
143           If a $file is provided by no "Content-Type" header, then
144           "Content-Type" and "Content-Encoding" will be filled in
145           automatically with the values returned by
146           "LWP::MediaTypes::guess_media_type()"
147
148           Sending my ~/.profile to the survey used as example above can be
149           achieved by this:
150
151             POST 'http://www.perl.org/survey.cgi',
152                  Content_Type => 'form-data',
153                  Content      => [ name  => 'Gisle Aas',
154                                    email => 'gisle@aas.no',
155                                    gender => 'M',
156                                    born   => '1964',
157                                    init   => ["$ENV{HOME}/.profile"],
158                                  ]
159
160           This will create an HTTP::Request object that almost looks this
161           (the boundary and the content of your ~/.profile is likely to be
162           different):
163
164             POST http://www.perl.org/survey.cgi
165             Content-Length: 388
166             Content-Type: multipart/form-data; boundary="6G+f"
167
168             --6G+f
169             Content-Disposition: form-data; name="name"
170
171             Gisle Aas
172             --6G+f
173             Content-Disposition: form-data; name="email"
174
175             gisle@aas.no
176             --6G+f
177             Content-Disposition: form-data; name="gender"
178
179             M
180             --6G+f
181             Content-Disposition: form-data; name="born"
182
183             1964
184             --6G+f
185             Content-Disposition: form-data; name="init"; filename=".profile"
186             Content-Type: text/plain
187
188             PATH=/local/perl/bin:$PATH
189             export PATH
190
191             --6G+f--
192
193           If you set the $DYNAMIC_FILE_UPLOAD variable (exportable) to some
194           TRUE value, then you get back a request object with a subroutine
195           closure as the content attribute.  This subroutine will read the
196           content of any files on demand and return it in suitable chunks.
197           This allow you to upload arbitrary big files without using lots of
198           memory.  You can even upload infinite files like /dev/audio if you
199           wish; however, if the file is not a plain file, there will be no
200           "Content-Length" header defined for the request.  Not all servers
201           (or server applications) like this.  Also, if the file(s) change in
202           size between the time the "Content-Length" is calculated and the
203           time that the last chunk is delivered, the subroutine will "Croak".
204
205           The "post(...)"  method of LWP::UserAgent exists as a shortcut for
206           "$ua->request(POST ...)".
207

AUTHOR

215       Gisle Aas <gisle@activestate.com>
216

COPYRIGHT AND LICENSE

218       This software is copyright (c) 1994-2017 by Gisle Aas.
219
220       This is free software; you can redistribute it and/or modify it under
221       the same terms as the Perl 5 programming language system itself.
222
223
224
225perl v5.30.0                      2019-07-26          HTTP::Request::Common(3)

NAME

VERSION

SYNOPSIS

DESCRIPTION

SEE ALSO

AUTHOR

COPYRIGHT AND LICENSE