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.44
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           This was added in version 6.21, so you should require that in your
87           code:
88
89            use HTTP::Request::Common 6.21;
90
91       POST $url
92       POST $url, Header => Value,...
93       POST $url, $form_ref, Header => Value,...
94       POST $url, Header => Value,..., Content => $form_ref
95       POST $url, Header => Value,..., Content => $content
96           "POST", "PATCH" and "PUT" all work with the same parameters.
97
98             %data = ( title => 'something', body => something else' );
99             $ua = LWP::UserAgent->new();
100             $request = HTTP::Request::Common::POST( $url, [ %data ] );
101             $response = $ua->request($request);
102
103           They take a second optional array or hash reference parameter
104           $form_ref.  The content can also be specified directly using the
105           "Content" pseudo-header, and you may also provide the $form_ref
106           this way.
107
108           The "Content" pseudo-header steals a bit of the header field
109           namespace as there is no way to directly specify a header that is
110           actually called "Content".  If you really need this you must update
111           the request returned in a separate statement.
112
113           The $form_ref argument can be used to pass key/value pairs for the
114           form content.  By default we will initialize a request using the
115           "application/x-www-form-urlencoded" content type.  This means that
116           you can emulate an HTML <form> POSTing like this:
117
118             POST 'http://www.perl.org/survey.cgi',
119                  [ name   => 'Gisle Aas',
120                    email  => 'gisle@aas.no',
121                    gender => 'M',
122                    born   => '1964',
123                    perc   => '3%',
124                  ];
125
126           This will create an HTTP::Request object that looks like this:
127
128             POST http://www.perl.org/survey.cgi
129             Content-Length: 66
130             Content-Type: application/x-www-form-urlencoded
131
132             name=Gisle%20Aas&email=gisle%40aas.no&gender=M&born=1964&perc=3%25
133
134           Multivalued form fields can be specified by either repeating the
135           field name or by passing the value as an array reference.
136
137           The POST method also supports the "multipart/form-data" content
138           used for Form-based File Upload as specified in RFC 1867.  You
139           trigger this content format by specifying a content type of
140           'form-data' as one of the request headers.  If one of the values in
141           the $form_ref is an array reference, then it is treated as a file
142           part specification with the following interpretation:
143
144             [ $file, $filename, Header => Value... ]
145             [ undef, $filename, Header => Value,..., Content => $content ]
146
147           The first value in the array ($file) is the name of a file to open.
148           This file will be read and its content placed in the request.  The
149           routine will croak if the file can't be opened.  Use an "undef" as
150           $file value if you want to specify the content directly with a
151           "Content" header.  The $filename is the filename to report in the
152           request.  If this value is undefined, then the basename of the
153           $file will be used.  You can specify an empty string as $filename
154           if you want to suppress sending the filename when you provide a
155           $file value.
156
157           If a $file is provided by no "Content-Type" header, then
158           "Content-Type" and "Content-Encoding" will be filled in
159           automatically with the values returned by
160           LWP::MediaTypes::guess_media_type()
161
162           Sending my ~/.profile to the survey used as example above can be
163           achieved by this:
164
165             POST 'http://www.perl.org/survey.cgi',
166                  Content_Type => 'form-data',
167                  Content      => [ name  => 'Gisle Aas',
168                                    email => 'gisle@aas.no',
169                                    gender => 'M',
170                                    born   => '1964',
171                                    init   => ["$ENV{HOME}/.profile"],
172                                  ]
173
174           This will create an HTTP::Request object that almost looks this
175           (the boundary and the content of your ~/.profile is likely to be
176           different):
177
178             POST http://www.perl.org/survey.cgi
179             Content-Length: 388
180             Content-Type: multipart/form-data; boundary="6G+f"
181
182             --6G+f
183             Content-Disposition: form-data; name="name"
184
185             Gisle Aas
186             --6G+f
187             Content-Disposition: form-data; name="email"
188
189             gisle@aas.no
190             --6G+f
191             Content-Disposition: form-data; name="gender"
192
193             M
194             --6G+f
195             Content-Disposition: form-data; name="born"
196
197             1964
198             --6G+f
199             Content-Disposition: form-data; name="init"; filename=".profile"
200             Content-Type: text/plain
201
202             PATH=/local/perl/bin:$PATH
203             export PATH
204
205             --6G+f--
206
207           If you set the $DYNAMIC_FILE_UPLOAD variable (exportable) to some
208           TRUE value, then you get back a request object with a subroutine
209           closure as the content attribute.  This subroutine will read the
210           content of any files on demand and return it in suitable chunks.
211           This allow you to upload arbitrary big files without using lots of
212           memory.  You can even upload infinite files like /dev/audio if you
213           wish; however, if the file is not a plain file, there will be no
214           "Content-Length" header defined for the request.  Not all servers
215           (or server applications) like this.  Also, if the file(s) change in
216           size between the time the "Content-Length" is calculated and the
217           time that the last chunk is delivered, the subroutine will "Croak".
218
219           The post(...)  method of LWP::UserAgent exists as a shortcut for
220           "$ua->request(POST ...)".
221

AUTHOR

229       Gisle Aas <gisle@activestate.com>
230

COPYRIGHT AND LICENSE

232       This software is copyright (c) 1994 by Gisle Aas.
233
234       This is free software; you can redistribute it and/or modify it under
235       the same terms as the Perl 5 programming language system itself.
236
237
238
239perl v5.36.0                      2023-01-20          HTTP::Request::Common(3)

NAME

VERSION

SYNOPSIS

DESCRIPTION

SEE ALSO

AUTHOR

COPYRIGHT AND LICENSE