Request/Common.pm

filter: Statementstmt 96.3% 184 / 191 Branchbran 85.7% 84 / 98 Conditioncond 72.7% 16 / 22 MC/DCmcdc 57.1% 8 / 14 Subroutinesub 100% 19 / 19 Podpod 70.0% 7 / 10 totaltotal 89.8% 318 / 354 CC 60 SCAR 28.2
CC
60
Cov
91%
form_data
30.1
request_type_with_data
16.0
__ANON__
13.3
CRAP 16.8
« Message.pm ↑ Summary Config.pm »
1 package HTTP::Request::Common;
2  
3 3 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 3 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5  
6 3 our $VERSION = '7.04';
7  
8 3 ▶our $DYNAMIC_FILE_UPLOAD ||= 0; # make it defined (don't know why)
Condition50%1/2
our $DYNAMIC_FILE_UPLOAD ||= 0
l!l
03
MC/DC0%0/1
our $DYNAMIC_FILE_UPLOAD ||= 0
our $DYNAMIC_FILE_UPLOAD
Truth table50%1/2
A
A= our $DYNAMIC_FILE_UPLOAD
Aresult
11
00
9 3 our $READ_BUFFER_SIZE = 8192;
10  
11 3 ▶use Exporter 5.57 'import';
Subroutine BEGIN: called CC=1 SCAR=0.0
12  
13 3 our @EXPORT = qw(GET HEAD OPTIONS PATCH POST PUT);
14 3 our @EXPORT_OK = qw($DYNAMIC_FILE_UPLOAD DELETE QUERY);
15  
16 3 require HTTP::Request;
17 3 ▶use Carp();
Subroutine BEGIN: called CC=1 SCAR=0.0
18 3 ▶use File::Spec;
Subroutine BEGIN: called CC=1 SCAR=0.0
19  
20 3 my $CRLF = "\015\012"; # "\r\n" is not portable
21  
22 1 ▶sub GET { _simple_req('GET', @_); }
Subroutine GET: called CC=1 SCAR=0.0
Pod documented
23 3 ▶sub HEAD { _simple_req('HEAD', @_); }
Subroutine HEAD: called CC=1 SCAR=0.0
Pod documented
24 1 ▶sub DELETE { _simple_req('DELETE', @_); }
Subroutine DELETE: called CC=1 SCAR=0.0
25 2 ▶sub OPTIONS { request_type_with_data('OPTIONS', @_); }
Subroutine OPTIONS: called CC=1 SCAR=0.0
Pod documented
26 2 ▶sub PATCH { request_type_with_data('PATCH', @_); }
Subroutine PATCH: called CC=1 SCAR=0.0
Pod documented
27 14 ▶sub POST { request_type_with_data('POST', @_); }
Subroutine POST: called CC=1 SCAR=0.0
Pod documented
28 3 ▶sub PUT { request_type_with_data('PUT', @_); }
Subroutine PUT: called CC=1 SCAR=0.0
Pod documented
29 3 ▶sub QUERY { request_type_with_data('QUERY', @_); }
Subroutine QUERY: called CC=1 SCAR=0.0
Pod documented
30  
31 sub request_type_with_data
32 25 ▶{
Subroutine request_type_with_data: called CC=16 SCAR=27.7
Pod undocumented
33 25 my $type = shift;
34 25 my $url = shift;
35 25 my $req = HTTP::Request->new($type => $url);
36 25 my $content;
37 25 ▶ $content = shift if @_ and ref $_[0];
Branch: 1 branch
BranchTrueFalseTotal
if @_ and ref $_[0] 9 16 25
Condition100%3/3
@_ and ref $_[0]
!ll&&!rl&&r
2149
MC/DC100%2/2
@_ and ref $_[0]
@_ ref $_[0]
Truth table100%3/3
A and B
A= @_B= ref $_[0]
ABresult
0X0
100
111
38 25 my($k, $v);
39 25 ▶ while (($k,$v) = splice(@_, 0, 2)) {
Branch: 1 branch
BranchTrueFalseTotal
if (() = splice(@_, 0, 2)) 30 25 55
40 30 ▶ if (lc($k) eq 'content') {
Branch: 1 branch
BranchTrueFalseTotal
if (lc $k eq 'content') { } 13 17 30
41 13 $content = $v;
42 }
43 else {
44 17 $req->push_header($k, $v);
45 }
46 }
47 25 my $ct = $req->header('Content-Type');
48 25 ▶ unless ($ct) {
Branch: 2 branches
BranchTrueFalseTotal
if ($ct) { } 12 13 25
if (do { $ct eq "form-data" }) 5 7 12
49 13 $ct = 'application/x-www-form-urlencoded';
50 }
51 0 elsif ($ct eq 'form-data') {
52 5 $ct = 'multipart/form-data';
53 }
54  
55 25 ▶ if (ref $content) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $content) 15 10 25
56 15 ▶ if ($ct =~ m,^multipart/form-data\s*(;|$),i) {
Branch: 1 branch
BranchTrueFalseTotal
if ($ct =~ m[^multipart/form-data\s*(;|$)]i) { } 7 8 15
57 7 require HTTP::Headers::Util;
58 7 my @v = HTTP::Headers::Util::split_header_words($ct);
59 7 ▶ Carp::carp("Multiple Content-Type headers") if @v > 1;
Branch: 1 branch
BranchTrueFalseTotal
if @v > 1 0 7 7
60 7 @v = @{$v[0]};
61  
62 7 my $boundary;
63 my $boundary_index;
64 7 ▶ for (my @tmp = @v; @tmp;) {
Branch: 1 branch
BranchTrueFalseTotal
if (@tmp) 8 6 14
65 8 my($k, $v) = splice(@tmp, 0, 2);
66 8 ▶ if ($k eq "boundary") {
Branch: 1 branch
BranchTrueFalseTotal
if ($k eq "boundary") 1 7 8
67 1 $boundary = $v;
68 1 $boundary_index = @v - @tmp - 1;
69 1 last;
70 }
71 }
72  
73 7 ($content, $boundary) = form_data($content, $boundary, $req);
74  
75 7 ▶ if ($boundary_index) {
Branch: 1 branch
BranchTrueFalseTotal
if ($boundary_index) { } 1 6 7
76 1 $v[$boundary_index] = $boundary;
77 }
78 else {
79 6 push(@v, boundary => $boundary);
80 }
81  
82 7 $ct = HTTP::Headers::Util::join_header_words(@v);
83 }
84 else {
85 # We use a temporary URI object to format
86 # the application/x-www-form-urlencoded content.
87 8 require URI;
88 8 my $url = URI->new('http:');
89 8 ▶ $url->query_form(ref($content) eq "HASH" ? %$content : @$content);
Branch: 1 branch
BranchTrueFalseTotal
ref $content eq 'HASH' ? : 5 3 8
90 8 $content = $url->query;
91 }
92 }
93  
94 25 $req->header('Content-Type' => $ct); # might be redundant
95 25 ▶ if (defined($content)) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $content) { } 20 5 25
96 20 ▶ $req->header('Content-Length' =>
Branch: 1 branch
BranchTrueFalseTotal
unless ref $content 19 1 20
97 length($content)) unless ref($content);
98 20 $req->content($content);
99 }
100 else {
101 5 $req->header('Content-Length' => 0);
102 }
103 25 $req;
104 }
105  
106  
107 sub _simple_req
108 5 ▶{
Subroutine _simple_req: called CC=5 SCAR=16.1
109 5 my($method, $url) = splice(@_, 0, 2);
110 5 my $req = HTTP::Request->new($method => $url);
111 5 my($k, $v);
112 5 my $content;
113 5 ▶ while (($k,$v) = splice(@_, 0, 2)) {
Branch: 1 branch
BranchTrueFalseTotal
if (() = splice(@_, 0, 2)) 5 5 10
114 5 ▶ if (lc($k) eq 'content') {
Branch: 1 branch
BranchTrueFalseTotal
if (lc $k eq 'content') { } 2 3 5
115 2 $req->add_content($v);
116 2 $content++;
117 }
118 else {
119 3 $req->push_header($k, $v);
120 }
121 }
122 5 ▶ if ($content && !defined($req->header("Content-Length"))) {
Branch: 1 branch
BranchTrueFalseTotal
if ($content and not defined $req->header("Content-Length")) 1 4 5
Condition100%3/3
$content and not defined $req->header("Content-Length")
!ll&&!rl&&r
311
MC/DC100%2/2
$content and not defined $req->header("Content-Length")
$content not defined $req->header("Content-Length")
Truth table100%3/3
A and not(B)
A= $contentB= not defined $req->header("Content-Length")
ABresult
0X0
100
111
123 1 $req->header("Content-Length", length(${$req->content_ref}));
124 }
125 5 $req;
126 }
127  
128  
129 sub form_data # RFC1867
130 7 ▶{
Subroutine form_data: called CC=28 SCAR=34.0
Pod undocumented
131 7 my($data, $boundary, $req) = @_;
132 7 ▶ my @data = ref($data) eq "HASH" ? %$data : @$data; # copy
Branch: 1 branch
BranchTrueFalseTotal
ref $data eq 'HASH' ? : 0 7 7
133 7 my $fhparts;
134 my @parts;
135 7 ▶ while (my ($k,$v) = splice(@data, 0, 2)) {
Branch: 1 branch
BranchTrueFalseTotal
if (() = splice(@data, 0, 2)) 16 7 23
136 16 ▶ if (!ref($v)) {
Branch: 1 branch
BranchTrueFalseTotal
if (not ref $v) { } 12 4 16
137 12 $k =~ s/([\\\"])/\\$1/g; # escape quotes and backslashes
138 3 ▶ no warnings 'uninitialized';
Subroutine BEGIN: called CC=1 SCAR=0.0
139 12 push(@parts,
140 qq(Content-Disposition: form-data; name="$k"$CRLF$CRLF$v));
141 }
142 else {
143 4 my($file, $usename, @headers) = @$v;
144 4 ▶ unless (defined $usename) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $usename) 3 1 4
145 3 $usename = $file;
146 3 ▶ $usename = (File::Spec->splitpath($usename))[-1] if defined($usename);
Branch: 1 branch
BranchTrueFalseTotal
if defined $usename 2 1 3
147 }
148 4 $k =~ s/([\\\"])/\\$1/g;
149 4 my $disp = qq(form-data; name="$k");
150 4 ▶ if (defined($usename) and length($usename)) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $usename and length $usename) 3 1 4
Condition66%2/3
defined $usename and length $usename
!ll&&!rl&&r
103
MC/DC50%1/2
defined $usename and length $usename
defined $usename length $usename
Truth table66%2/3
A and B
A= defined $usenameB= length $usename
ABresult
0X0
100
111
151 3 $usename =~ s/([\\\"])/\\$1/g;
152 3 $disp .= qq(; filename="$usename");
153 }
154 4 my $content = "";
155 4 my $h = HTTP::Headers->new(@headers);
156 4 ▶ if ($file) {
Branch: 1 branch
BranchTrueFalseTotal
if ($file) 2 2 4
157 2 ▶ open(my $fh, "<", $file) or Carp::croak("Can't open file $file: $!");
Branch: 1 branch
BranchTrueFalseTotal
open my $fh, "<", $file or Carp::croak("Can't open file ${file}: $!") 2 0 2
158 2 binmode($fh);
159 2 ▶ if ($DYNAMIC_FILE_UPLOAD) {
Branch: 1 branch
BranchTrueFalseTotal
if ($HTTP::Request::Common::DYNAMIC_FILE_UPLOAD) { } 1 1 2
160 # will read file later, close it now in order to
161 # not accumulate to many open file handles
162 1 close($fh);
163 1 $content = \$file;
164 }
165 else {
166 1 local($/) = undef; # slurp files
167 1 $content = <$fh>;
168 1 close($fh);
169 }
170 2 ▶ unless ($h->header("Content-Type")) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($h->header("Content-Type")) 2 0 2
171 2 require LWP::MediaTypes;
172 2 LWP::MediaTypes::guess_media_type($file, $h);
173 }
174 }
175 4 ▶ if ($h->header("Content-Disposition")) {
Branch: 1 branch
BranchTrueFalseTotal
if ($h->header("Content-Disposition")) 0 4 4
176 # just to get it sorted first
177 0 $disp = $h->header("Content-Disposition");
178 0 $h->remove_header("Content-Disposition");
179 }
180 4 ▶ if ($h->header("Content")) {
Branch: 1 branch
BranchTrueFalseTotal
if ($h->header("Content")) 2 2 4
181 2 $content = $h->header("Content");
182 2 $h->remove_header("Content");
183 }
184 4 my $head = join($CRLF, "Content-Disposition: $disp",
185 $h->as_string($CRLF),
186 "");
187 4 ▶ if (ref $content) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $content) { } 1 3 4
188 1 push(@parts, [$head, $$content]);
189 1 $fhparts++;
190 }
191 else {
192 3 push(@parts, $head . $content);
193 }
194 }
195 }
196 7 ▶ return ("", "none") unless @parts;
Branch: 1 branch
BranchTrueFalseTotal
unless @parts 1 6 7
197  
198 6 my $content;
199 6 ▶ if ($fhparts) {
Branch: 1 branch
BranchTrueFalseTotal
if ($fhparts) { } 1 5 6
200 1 ▶ $boundary = boundary(10) # hopefully enough randomness
Branch: 1 branch
BranchTrueFalseTotal
unless $boundary 1 0 1
201 unless $boundary;
202  
203 # add the boundaries to the @parts array
204 1 for (1..@parts-1) {
205 4 splice(@parts, $_*2-1, 0, "$CRLF--$boundary$CRLF");
206 }
207 1 unshift(@parts, "--$boundary$CRLF");
208 1 push(@parts, "$CRLF--$boundary--$CRLF");
209  
210 # See if we can generate Content-Length header
211 1 my $length = 0;
212 1 for (@parts) {
213 11 ▶ if (ref $_) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $_) { } 1 10 11
214 1 my ($head, $f) = @$_;
215 1 my $file_size;
216 1 ▶ unless ( -f $f && ($file_size = -s _) ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (-f $f and $file_size = -s _) 0 1 1
Condition33%1/3
-f $f and $file_size = -s _
!ll&&!rl&&r
001
MC/DC0%0/2
-f $f and $file_size = -s _
-f $f $file_size = -s _
Truth table33%1/3
A and B
A= -f $fB= $file_size = -s _
ABresult
0X0
100
111
217 # The file is either a dynamic file like /dev/audio
218 # or perhaps a file in the /proc file system where
219 # stat may return a 0 size even though reading it
220 # will produce data. So we cannot make
221 # a Content-Length header.
222 0 undef $length;
223 0 last;
224 }
225 1 $length += $file_size + length $head;
226 }
227 else {
228 10 $length += length;
229 }
230 }
231 1 ▶ $length && $req->header('Content-Length' => $length);
Branch: 1 branch
BranchTrueFalseTotal
$length and $req->header("Content-Length", $length) 1 0 1
232  
233 # set up a closure that will return content piecemeal
234 7 ▶ $content = sub {
Subroutine __ANON__: called CC=13 SCAR=25.9
235 7 for (;;) {
236 8 ▶ unless (@parts) {
Branch: 1 branch
BranchTrueFalseTotal
unless (@parts) 1 7 8
237 1 ▶ defined $length && $length != 0 &&
Branch: 1 branch
BranchTrueFalseTotal
defined $length and $length != 0 and Carp::croak("length of data sent did not match calculated Content-Length header. Probably because uploaded file changed in size during transfer.") 0 1 1
Condition33%1/3
defined $length and $length != 0
!ll&&!rl&&r
010
MC/DC0%0/2
defined $length and $length != 0
defined $length $length != 0
Truth table33%1/3
A and B
A= defined $lengthB= $length != 0
ABresult
0X0
100
111
238 Carp::croak "length of data sent did not match calculated Content-Length header. Probably because uploaded file changed in size during transfer.";
239 1 return;
240 }
241 7 my $p = shift @parts;
242 7 ▶ unless (ref $p) {
Branch: 1 branch
BranchTrueFalseTotal
unless (ref $p) 2 5 7
243 2 ▶ $p .= shift @parts while @parts && !ref($parts[0]);
Branch: 1 branch
BranchTrueFalseTotal
@parts and not ref $parts[0] and do { $p .= shift(@parts) } 8 2 10
Condition100%3/3
@parts and not ref $parts[0]
!ll&&!rl&&r
118
MC/DC100%2/2
@parts and not ref $parts[0]
@parts not ref $parts[0]
Truth table100%3/3
A and not(B)
A= @partsB= not ref $parts[0]
ABresult
0X0
100
111
244 2 ▶ defined $length && ($length -= length $p);
Branch: 1 branch
BranchTrueFalseTotal
defined $length and $length -= length $p 2 0 2
245 2 return $p;
246 }
247 5 my($buf, $fh) = @$p;
248 5 ▶ unless (ref($fh)) {
Branch: 1 branch
BranchTrueFalseTotal
unless (ref $fh) 1 4 5
249 1 my $file = $fh;
250 1 undef($fh);
251 1 ▶ open($fh, "<", $file) || Carp::croak("Can't open file $file: $!");
Branch: 1 branch
BranchTrueFalseTotal
open $fh, "<", $file or Carp::croak("Can't open file ${file}: $!") 1 0 1
252 1 binmode($fh);
253 }
254 5 my $buflength = length $buf;
255 5 my $n = read($fh, $buf, $READ_BUFFER_SIZE, $buflength);
256 5 ▶ if ($n) {
Branch: 1 branch
BranchTrueFalseTotal
if ($n) { } 4 1 5
257 4 $buflength += $n;
258 4 unshift(@parts, ["", $fh]);
259 }
260 else {
261 1 close($fh);
262 }
263 5 ▶ if ($buflength) {
Branch: 1 branch
BranchTrueFalseTotal
if ($buflength) 4 1 5
264 4 ▶ defined $length && ($length -= $buflength);
Branch: 1 branch
BranchTrueFalseTotal
defined $length and $length -= $buflength 4 0 4
265 4 return $buf
266 }
267 }
268 1 };
269  
270 }
271 else {
272 5 ▶ $boundary = boundary() unless $boundary;
Branch: 1 branch
BranchTrueFalseTotal
unless $boundary 4 1 5
273  
274 5 my $bno = 0;
275 CHECK_BOUNDARY:
276 {
277 5 for (@parts) {
278 11 ▶ if (index($_, $boundary) >= 0) {
Branch: 1 branch
BranchTrueFalseTotal
if (index($_, $boundary) != -1) 0 11 11
279 # must have a better boundary
280 0 $boundary = boundary(++$bno);
281 0 redo CHECK_BOUNDARY;
282 }
283 }
284 5 last;
285 }
286 5 $content = "--$boundary$CRLF" .
287 join("$CRLF--$boundary$CRLF", @parts) .
288 "$CRLF--$boundary--$CRLF";
289 }
290  
291 6 ▶ wantarray ? ($content, $boundary) : $content;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 6 0 6
292 }
293  
294  
295 sub boundary
296 5 ▶{
Subroutine boundary: called CC=2 SCAR=6.9
Pod undocumented
297 5 ▶ my $size = shift || return "xYzZY";
Condition100%2/2
shift() || (return 'xYzZY')
l!l
14
MC/DC100%1/1
shift() || (return 'xYzZY')
shift()
Truth table100%2/2
A
A= shift()
Aresult
11
00
298 1 require MIME::Base64;
299 1 my $b = MIME::Base64::encode(join("", map chr(rand(256)), 1..$size*3), "");
300 1 $b =~ s/[\W]/X/g; # ensure alnum only
301 1 $b;
302 }
303  
304 3 1;
305  
306 =pod
307  
308 =encoding UTF-8
309  
310 =head1 NAME
311  
312 HTTP::Request::Common - Construct common HTTP::Request objects
313  
314 =head1 VERSION
315  
316 version 7.04
317  
318 =head1 SYNOPSIS
319  
320 use HTTP::Request::Common;
321 $ua = LWP::UserAgent->new;
322 $ua->request(GET 'http://www.sn.no/');
323 $ua->request(POST 'http://somewhere/foo', foo => bar, bar => foo);
324 $ua->request(PATCH 'http://somewhere/foo', foo => bar, bar => foo);
325 $ua->request(PUT 'http://somewhere/foo', foo => bar, bar => foo);
326 $ua->request(OPTIONS 'http://somewhere/foo', foo => bar, bar => foo);
327  
328 use HTTP::Request::Common qw(DELETE QUERY);
329 $ua->request(DELETE 'http://somewhere/foo', foo => bar, bar => foo);
330 $ua->request(QUERY 'http://somewhere/foo', foo => bar, bar => foo);
331  
332 =head1 DESCRIPTION
333  
334 This module provides functions that return newly created C<HTTP::Request>
335 objects. These functions are usually more convenient to use than the
336 standard C<HTTP::Request> constructor for the most common requests.
337  
338 Note that L<LWP::UserAgent> has several convenience methods, including
339 C<get>, C<head>, C<delete>, C<post> and C<put>.
340  
341 The following functions are provided:
342  
343 =over 4
344  
345 =item GET $url
346  
347 =item GET $url, Header => Value,...
348  
349 The C<GET> function returns an L<HTTP::Request> object initialized with
350 the "GET" method and the specified URL. It is roughly equivalent to the
351 following call
352  
353 HTTP::Request->new(
354 GET => $url,
355 HTTP::Headers->new(Header => Value,...),
356 )
357  
358 but is less cluttered. What is different is that a header named
359 C<Content> will initialize the content part of the request instead of
360 setting a header field. Note that GET requests should normally not
361 have a content, so this hack makes more sense for the C<PUT>, C<PATCH>
362 and C<POST> functions described below.
363  
364 The C<get(...)> method of L<LWP::UserAgent> exists as a shortcut for
365 C<< $ua->request(GET ...) >>.
366  
367 =item HEAD $url
368  
369 =item HEAD $url, Header => Value,...
370  
371 Like GET() but the method in the request is "HEAD".
372  
373 The C<head(...)> method of L<LWP::UserAgent> exists as a shortcut for
374 C<< $ua->request(HEAD ...) >>.
375  
376 =item DELETE $url
377  
378 =item DELETE $url, Header => Value,...
379  
380 Like C<GET> but the method in the request is C<DELETE>. This function
381 is not exported by default.
382  
383 =item PATCH $url
384  
385 =item PATCH $url, Header => Value,...
386  
387 =item PATCH $url, $form_ref, Header => Value,...
388  
389 =item PATCH $url, Header => Value,..., Content => $form_ref
390  
391 =item PATCH $url, Header => Value,..., Content => $content
392  
393 The same as C<POST> below, but the method in the request is C<PATCH>.
394  
395 =item PUT $url
396  
397 =item PUT $url, Header => Value,...
398  
399 =item PUT $url, $form_ref, Header => Value,...
400  
401 =item PUT $url, Header => Value,..., Content => $form_ref
402  
403 =item PUT $url, Header => Value,..., Content => $content
404  
405 The same as C<POST> below, but the method in the request is C<PUT>
406  
407 =item OPTIONS $url
408  
409 =item OPTIONS $url, Header => Value,...
410  
411 =item OPTIONS $url, $form_ref, Header => Value,...
412  
413 =item OPTIONS $url, Header => Value,..., Content => $form_ref
414  
415 =item OPTIONS $url, Header => Value,..., Content => $content
416  
417 The same as C<POST> below, but the method in the request is C<OPTIONS>
418  
419 This was added in version 6.21, so you should require that in your code:
420  
421 use HTTP::Request::Common 6.21;
422  
423 =item POST $url
424  
425 =item POST $url, Header => Value,...
426  
427 =item POST $url, $form_ref, Header => Value,...
428  
429 =item POST $url, Header => Value,..., Content => $form_ref
430  
431 =item POST $url, Header => Value,..., Content => $content
432  
433 C<OPTIONS>, C<POST>, C<PATCH>, C<PUT> and C<QUERY> all work with the same parameters.
434  
435 %data = ( title => 'something', body => something else' );
436 $ua = LWP::UserAgent->new();
437 $request = HTTP::Request::Common::POST( $url, [ %data ] );
438 $response = $ua->request($request);
439  
440 They take a second optional array or hash reference
441 parameter C<$form_ref>. The content can also be specified
442 directly using the C<Content> pseudo-header, and you may also provide
443 the C<$form_ref> this way.
444  
445 The C<Content> pseudo-header steals a bit of the header field namespace as
446 there is no way to directly specify a header that is actually called
447 "Content". If you really need this you must update the request
448 returned in a separate statement.
449  
450 The C<$form_ref> argument can be used to pass key/value pairs for the
451 form content. By default we will initialize a request using the
452 C<application/x-www-form-urlencoded> content type. This means that
453 you can emulate an HTML E<lt>form> POSTing like this:
454  
455 POST 'http://www.perl.org/survey.cgi',
456 [ name => 'Gisle Aas',
457 email => 'gisle@aas.no',
458 gender => 'M',
459 born => '1964',
460 perc => '3%',
461 ];
462  
463 This will create an L<HTTP::Request> object that looks like this:
464  
465 POST http://www.perl.org/survey.cgi
466 Content-Length: 66
467 Content-Type: application/x-www-form-urlencoded
468  
469 name=Gisle%20Aas&email=gisle%40aas.no&gender=M&born=1964&perc=3%25
470  
471 Multivalued form fields can be specified by either repeating the field
472 name or by passing the value as an array reference.
473  
474 The POST method also supports the C<multipart/form-data> content used
475 for I<Form-based File Upload> as specified in RFC 1867. You trigger
476 this content format by specifying a content type of C<'form-data'> as
477 one of the request headers. If one of the values in the C<$form_ref> is
478 an array reference, then it is treated as a file part specification
479 with the following interpretation:
480  
481 [ $file, $filename, Header => Value... ]
482 [ undef, $filename, Header => Value,..., Content => $content ]
483  
484 The first value in the array ($file) is the name of a file to open.
485 This file will be read and its content placed in the request. The
486 routine will croak if the file can't be opened. Use an C<undef> as
487 $file value if you want to specify the content directly with a
488 C<Content> header. The $filename is the filename to report in the
489 request. If this value is undefined, then the basename of the $file
490 will be used. You can specify an empty string as $filename if you
491 want to suppress sending the filename when you provide a $file value.
492  
493 If a $file is provided by no C<Content-Type> header, then C<Content-Type>
494 and C<Content-Encoding> will be filled in automatically with the values
495 returned by C<LWP::MediaTypes::guess_media_type()>
496  
497 Sending my F<~/.profile> to the survey used as example above can be
498 achieved by this:
499  
500 POST 'http://www.perl.org/survey.cgi',
501 Content_Type => 'form-data',
502 Content => [ name => 'Gisle Aas',
503 email => 'gisle@aas.no',
504 gender => 'M',
505 born => '1964',
506 init => ["$ENV{HOME}/.profile"],
507 ]
508  
509 This will create an L<HTTP::Request> object that almost looks this (the
510 boundary and the content of your F<~/.profile> is likely to be
511 different):
512  
513 POST http://www.perl.org/survey.cgi
514 Content-Length: 388
515 Content-Type: multipart/form-data; boundary="6G+f"
516  
517 --6G+f
518 Content-Disposition: form-data; name="name"
519  
520 Gisle Aas
521 --6G+f
522 Content-Disposition: form-data; name="email"
523  
524 gisle@aas.no
525 --6G+f
526 Content-Disposition: form-data; name="gender"
527  
528 M
529 --6G+f
530 Content-Disposition: form-data; name="born"
531  
532 1964
533 --6G+f
534 Content-Disposition: form-data; name="init"; filename=".profile"
535 Content-Type: text/plain
536  
537 PATH=/local/perl/bin:$PATH
538 export PATH
539  
540 --6G+f--
541  
542 If you set the C<$DYNAMIC_FILE_UPLOAD> variable (exportable) to some TRUE
543 value, then you get back a request object with a subroutine closure as
544 the content attribute. This subroutine will read the content of any
545 files on demand and return it in suitable chunks. This allow you to
546 upload arbitrary big files without using lots of memory. You can even
547 upload infinite files like F</dev/audio> if you wish; however, if
548 the file is not a plain file, there will be no C<Content-Length> header
549 defined for the request. Not all servers (or server
550 applications) like this. Also, if the file(s) change in size between
551 the time the C<Content-Length> is calculated and the time that the last
552 chunk is delivered, the subroutine will C<croak>.
553  
554 The C<post(...)> method of L<LWP::UserAgent> exists as a shortcut for
555 C<< $ua->request(POST ...) >>.
556  
557 =item QUERY $url
558  
559 =item QUERY $url, Header => Value,...
560  
561 =item QUERY $url, $form_ref, Header => Value,...
562  
563 =item QUERY $url, Header => Value,..., Content => $form_ref
564  
565 =item QUERY $url, Header => Value,..., Content => $content
566  
567 The same as C<POST> above, but the method in the request is C<QUERY>,
568 the safe, idempotent method with content defined by
569 L<RFC 10008|https://www.rfc-editor.org/rfc/rfc10008.html>.
570 This function is not exported by default.
571  
572 This was added in version 7.04, so you should require that in your code:
573  
574 use HTTP::Request::Common 7.04 qw(QUERY);
575  
576 =back
577  
578 =head1 SEE ALSO
579  
580 L<HTTP::Request>, L<LWP::UserAgent>
581  
582 Also, there are some examples in L<HTTP::Request/"EXAMPLES"> that you might
583 find useful. For example, batch requests are explained there.
584  
585 =head1 AUTHOR
586  
587 Gisle Aas <gisle@activestate.com>
588  
589 =head1 COPYRIGHT AND LICENSE
590  
591 This software is copyright (c) 1994 by Gisle Aas.
592  
593 This is free software; you can redistribute it and/or modify it under
594 the same terms as the Perl 5 programming language system itself.
595  
596 =cut
597  
598 __END__
« Message.pm ↑ Summary Config.pm »