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.37
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         $ua->request(OPTIONS 'http://somewhere/foo', foo => bar, bar => foo);
19

DESCRIPTION

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

AUTHOR

224       Gisle Aas <gisle@activestate.com>
225

COPYRIGHT AND LICENSE

227       This software is copyright (c) 1994 by Gisle Aas.
228
229       This is free software; you can redistribute it and/or modify it under
230       the same terms as the Perl 5 programming language system itself.
231
232
233
234perl v5.36.0                      2022-08-17          HTTP::Request::Common(3)

NAME

VERSION

SYNOPSIS

DESCRIPTION

SEE ALSO

AUTHOR

COPYRIGHT AND LICENSE