README
1NAME
2
3 HTTP::Simple - Simple procedural interface to HTTP::Tiny
4
5SYNOPSIS
6
7 perl -MHTTP::Simple -e'getprint(shift)' 'https://example.com'
8
9 use HTTP::Simple;
10
11 my $content = get 'https://example.com';
12
13 if (mirror('https://example.com', '/path/to/file.html') == 304) { ... }
14
15 if (is_success(getprint 'https://example.com')) { ... }
16
17 postform('https://example.com', {foo => ['bar', 'baz']});
18
19 postjson('https://example.com', [{bar => 'baz'}]);
20
21 postfile('https://example.com', '/path/to/file.png');
22
23DESCRIPTION
24
25 This module is a wrapper of HTTP::Tiny that provides simplified
26 functions for performing HTTP requests in a similar manner to
27 LWP::Simple, but with slightly more useful error handling. For full
28 control of the request process and response handling, use HTTP::Tiny
29 directly.
30
31 IO::Socket::SSL is required for HTTPS requests with HTTP::Tiny.
32
33 Request methods that return the body content of the response will
34 return a byte string suitable for directly printing, but that may need
35 to be decoded for text operations.
36
37 The HTTP::Tiny object used by these functions to make requests can be
38 accessed as $HTTP::Simple::UA (for example, to configure the timeout,
39 or replace it with a compatible object like HTTP::Tinyish).
40
41 The JSON encoder used by the JSON functions can be accessed as
42 $HTTP::Simple::JSON, and defaults to a Cpanel::JSON::XS object if
43 Cpanel::JSON::XS 4.11+ is installed, and otherwise a JSON::PP object.
44 If replaced with a new object, it should have UTF-8 encoding/decoding
45 enabled (usually the utf8 option). If it is set to a string, it will be
46 used as a module name that is expected to have decode_json and
47 encode_json functions.
48
49FUNCTIONS
50
51 All functions are exported by default. Functions can also be requested
52 individually or with the tags :request, :status, or :all.
53
54 get
55
56 my $contents = get($url);
57
58 Retrieves the document at the given URL with a GET request and returns
59 it as a byte string. Throws an exception on connection or HTTP errors.
60
61 getjson
62
63 my $data = getjson($url);
64
65 Retrieves the JSON document at the given URL with a GET request and
66 decodes it from JSON to a Perl structure. Throws an exception on
67 connection, HTTP, or JSON errors.
68
69 head
70
71 my $headers = head($url);
72
73 Retrieves the headers at the given URL with a HEAD request and returns
74 them as a hash reference. Header field names are normalized to lower
75 case, and values may be an array reference if the header is repeated.
76 Throws an exception on connection or HTTP errors.
77
78 getprint
79
80 my $status = getprint($url);
81
82 Retrieves the document at the given URL with a GET request and prints
83 it as it is received. Returns the HTTP status code. Throws an exception
84 on connection errors.
85
86 getstore
87
88 my $status = getstore($url, $path);
89
90 Retrieves the document at the given URL with a GET request and stores
91 it to the given file path. Returns the HTTP status code. Throws an
92 exception on connection or filesystem errors.
93
94 mirror
95
96 my $status = mirror($url, $path);
97
98 Retrieves the document at the given URL with a GET request and mirrors
99 it to the given file path, using the If-Modified-Since headers to
100 short-circuit if the file exists and is new enough, and the
101 Last-Modified header to set its modification time. Returns the HTTP
102 status code. Throws an exception on connection, HTTP, or filesystem
103 errors.
104
105 postform
106
107 my $contents = postform($url, $form);
108
109 Sends a POST request to the given URL with the given hash or array
110 reference of form data serialized to application/x-www-form-urlencoded.
111 Returns the response body as a byte string. Throws an exception on
112 connection or HTTP errors.
113
114 postjson
115
116 my $contents = postjson($url, $data);
117
118 Sends a POST request to the given URL with the given data structure
119 encoded to JSON. Returns the response body as a byte string. Throws an
120 exception on connection, HTTP, or JSON errors.
121
122 postfile
123
124 my $contents = postfile($url, $path);
125 my $contents = postfile($url, $path, $content_type);
126
127 Sends a POST request to the given URL, streaming the contents of the
128 given file. The content type is passed as application/octet-stream if
129 not specified. Returns the response body as a byte string. Throws an
130 exception on connection, HTTP, or filesystem errors.
131
132 is_info
133
134 my $bool = is_info($status);
135
136 Returns true if the status code indicates an informational response
137 (1xx).
138
139 is_success
140
141 my $bool = is_success($status);
142
143 Returns true if the status code indicates a successful response (2xx).
144
145 is_redirect
146
147 my $bool = is_redirect($status);
148
149 Returns true if the status code indicates a redirection response (3xx).
150
151 is_error
152
153 my $bool = is_error($status);
154
155 Returns true if the status code indicates an error response (4xx or
156 5xx).
157
158 is_client_error
159
160 my $bool = is_client_error($status);
161
162 Returns true if the status code indicates a client error response
163 (4xx).
164
165 is_server_error
166
167 my $bool = is_server_error($status);
168
169 Returns true if the status code indicates a server error response
170 (5xx).
171
172BUGS
173
174 Report any issues on the public bugtracker.
175
176AUTHOR
177
178 Dan Book <dbook@cpan.org>
179
180COPYRIGHT AND LICENSE
181
182 This software is Copyright (c) 2019 by Dan Book.
183
184 This is free software, licensed under:
185
186 The Artistic License 2.0 (GPL Compatible)
187
188SEE ALSO
189
190 LWP::Simple, HTTP::Tinyish, ojo
191
192
