1HTTP::Headers(3) User Contributed Perl Documentation HTTP::Headers(3)
2
6 HTTP::Headers - Class encapsulating HTTP Message headers
7
9 version 6.18
10
12 require HTTP::Headers;
13 $h = HTTP::Headers->new;
14 $h->header('Content-Type' => 'text/plain'); # set
16 $ct = $h->header('Content-Type'); # get
17 $h->remove_header('Content-Type'); # delete
18
20 The "HTTP::Headers" class encapsulates HTTP-style message headers. The
21 headers consist of attribute-value pairs also called fields, which may
22 be repeated, and which are printed in a particular order. The field
23 names are cases insensitive.
24 Instances of this class are usually created as member variables of the
26 "HTTP::Request" and "HTTP::Response" classes, internal to the library.
27 The following methods are available:
29 $h = HTTP::Headers->new
31 Constructs a new "HTTP::Headers" object. You might pass some
32 initial attribute-value pairs as parameters to the constructor.
33 E.g.:
34 $h = HTTP::Headers->new(
36 Date => 'Thu, 03 Feb 1994 00:00:00 GMT',
37 Content_Type => 'text/html; version=3.2',
38 Content_Base => 'http://www.perl.org/');
39 The constructor arguments are passed to the "header" method which
41 is described below.
42 $h->clone
44 Returns a copy of this "HTTP::Headers" object.
45 $h->header( $field )
47 $h->header( $field => $value )
48 $h->header( $f1 => $v1, $f2 => $v2, ... )
49 Get or set the value of one or more header fields. The header
50 field name ($field) is not case sensitive. To make the life easier
51 for perl users who wants to avoid quoting before the => operator,
52 you can use '_' as a replacement for '-' in header names.
53 The header() method accepts multiple ($field => $value) pairs,
55 which means that you can update several fields with a single
56 invocation.
57 The $value argument may be a plain string or a reference to an
59 array of strings for a multi-valued field. If the $value is
60 provided as "undef" then the field is removed. If the $value is
61 not given, then that header field will remain unchanged.
62 The old value (or values) of the last of the header fields is
64 returned. If no such field exists "undef" will be returned.
65 A multi-valued field will be returned as separate values in list
67 context and will be concatenated with ", " as separator in scalar
68 context. The HTTP spec (RFC 2616) promises that joining multiple
69 values in this way will not change the semantic of a header field,
70 but in practice there are cases like old-style Netscape cookies
71 (see HTTP::Cookies) where "," is used as part of the syntax of a
72 single field value.
73 Examples:
75 $header->header(MIME_Version => '1.0',
77 User_Agent => 'My-Web-Client/0.01');
78 $header->header(Accept => "text/html, text/plain, image/*");
79 $header->header(Accept => [qw(text/html text/plain image/*)]);
80 @accepts = $header->header('Accept'); # get multiple values
81 $accepts = $header->header('Accept'); # get values as a single string
82 $h->push_header( $field => $value )
84 $h->push_header( $f1 => $v1, $f2 => $v2, ... )
85 Add a new field value for the specified header field. Previous
86 values for the same field are retained.
87 As for the header() method, the field name ($field) is not case
89 sensitive and '_' can be used as a replacement for '-'.
90 The $value argument may be a scalar or a reference to a list of
92 scalars.
93 $header->push_header(Accept => 'image/jpeg');
95 $header->push_header(Accept => [map "image/$_", qw(gif png tiff)]);
96 $h->init_header( $field => $value )
98 Set the specified header to the given value, but only if no
99 previous value for that field is set.
100 The header field name ($field) is not case sensitive and '_' can be
102 used as a replacement for '-'.
103 The $value argument may be a scalar or a reference to a list of
105 scalars.
106 $h->remove_header( $field, ... )
108 This function removes the header fields with the specified names.
109 The header field names ($field) are not case sensitive and '_' can
111 be used as a replacement for '-'.
112 The return value is the values of the fields removed. In scalar
114 context the number of fields removed is returned.
115 Note that if you pass in multiple field names then it is generally
117 not possible to tell which of the returned values belonged to which
118 field.
119 $h->remove_content_headers
121 This will remove all the header fields used to describe the content
122 of a message. All header field names prefixed with "Content-" fall
123 into this category, as well as "Allow", "Expires" and
124 "Last-Modified". RFC 2616 denotes these fields as Entity Header
125 Fields.
126 The return value is a new "HTTP::Headers" object that contains the
128 removed headers only.
129 $h->clear
131 This will remove all header fields.
132 $h->header_field_names
134 Returns the list of distinct names for the fields present in the
135 header. The field names have case as suggested by HTTP spec, and
136 the names are returned in the recommended "Good Practice" order.
137 In scalar context return the number of distinct field names.
139 $h->scan( \&process_header_field )
141 Apply a subroutine to each header field in turn. The callback
142 routine is called with two parameters; the name of the field and a
143 single value (a string). If a header field is multi-valued, then
144 the routine is called once for each value. The field name passed
145 to the callback routine has case as suggested by HTTP spec, and the
146 headers will be visited in the recommended "Good Practice" order.
147 Any return values of the callback routine are ignored. The loop
149 can be broken by raising an exception ("die"), but the caller of
150 scan() would have to trap the exception itself.
151 $h->flatten()
153 Returns the list of pairs of keys and values.
154 $h->as_string
156 $h->as_string( $eol )
157 Return the header fields as a formatted MIME header. Since it
158 internally uses the "scan" method to build the string, the result
159 will use case as suggested by HTTP spec, and it will follow
160 recommended "Good Practice" of ordering the header fields. Long
161 header values are not folded.
162 The optional $eol parameter specifies the line ending sequence to
164 use. The default is "\n". Embedded "\n" characters in header
165 field values will be substituted with this line ending sequence.
166
168 The most frequently used headers can also be accessed through the
169 following convenience methods. Most of these methods can both be used
170 to read and to set the value of a header. The header value is set if
171 you pass an argument to the method. The old header value is always
172 returned. If the given header did not exist then "undef" is returned.
173 Methods that deal with dates/times always convert their value to system
175 time (seconds since Jan 1, 1970) and they also expect this kind of
176 value when the header value is set.
177 $h->date
179 This header represents the date and time at which the message was
180 originated. E.g.:
181 $h->date(time); # set current date
183 $h->expires
185 This header gives the date and time after which the entity should
186 be considered stale.
187 $h->if_modified_since
189 $h->if_unmodified_since
190 These header fields are used to make a request conditional. If the
191 requested resource has (or has not) been modified since the time
192 specified in this field, then the server will return a "304 Not
193 Modified" response instead of the document itself.
194 $h->last_modified
196 This header indicates the date and time at which the resource was
197 last modified. E.g.:
198 # check if document is more than 1 hour old
200 if (my $last_mod = $h->last_modified) {
201 if ($last_mod < time - 60*60) {
202 ...
203 }
204 }
205 $h->content_type
207 The Content-Type header field indicates the media type of the
208 message content. E.g.:
209 $h->content_type('text/html');
211 The value returned will be converted to lower case, and potential
213 parameters will be chopped off and returned as a separate value if
214 in an array context. If there is no such header field, then the
215 empty string is returned. This makes it safe to do the following:
216 if ($h->content_type eq 'text/html') {
218 # we enter this place even if the real header value happens to
219 # be 'TEXT/HTML; version=3.0'
220 ...
221 }
222 $h->content_type_charset
224 Returns the upper-cased charset specified in the Content-Type
225 header. In list context return the lower-cased bare content type
226 followed by the upper-cased charset. Both values will be "undef"
227 if not specified in the header.
228 $h->content_is_text
230 Returns TRUE if the Content-Type header field indicate that the
231 content is textual.
232 $h->content_is_html
234 Returns TRUE if the Content-Type header field indicate that the
235 content is some kind of HTML (including XHTML). This method can't
236 be used to set Content-Type.
237 $h->content_is_xhtml
239 Returns TRUE if the Content-Type header field indicate that the
240 content is XHTML. This method can't be used to set Content-Type.
241 $h->content_is_xml
243 Returns TRUE if the Content-Type header field indicate that the
244 content is XML. This method can't be used to set Content-Type.
245 $h->content_encoding
247 The Content-Encoding header field is used as a modifier to the
248 media type. When present, its value indicates what additional
249 encoding mechanism has been applied to the resource.
250 $h->content_length
252 A decimal number indicating the size in bytes of the message
253 content.
254 $h->content_language
256 The natural language(s) of the intended audience for the message
257 content. The value is one or more language tags as defined by RFC
258 1766. Eg. "no" for some kind of Norwegian and "en-US" for English
259 the way it is written in the US.
260 $h->title
262 The title of the document. In libwww-perl this header will be
263 initialized automatically from the <TITLE>...</TITLE> element of
264 HTML documents. This header is no longer part of the HTTP
265 standard.
266 $h->user_agent
268 This header field is used in request messages and contains
269 information about the user agent originating the request. E.g.:
270 $h->user_agent('Mozilla/5.0 (compatible; MSIE 7.0; Windows NT 6.0)');
272 $h->server
274 The server header field contains information about the software
275 being used by the originating server program handling the request.
276 $h->from
278 This header should contain an Internet e-mail address for the human
279 user who controls the requesting user agent. The address should be
280 machine-usable, as defined by RFC822. E.g.:
281 $h->from('King Kong <king@kong.com>');
283 This header is no longer part of the HTTP standard.
285 $h->referer
287 Used to specify the address (URI) of the document from which the
288 requested resource address was obtained.
289 The "Free On-line Dictionary of Computing" as this to say about the
291 word referer:
292 <World-Wide Web> A misspelling of "referrer" which
294 somehow made it into the {HTTP} standard. A given {web
295 page}'s referer (sic) is the {URL} of whatever web page
296 contains the link that the user followed to the current
297 page. Most browsers pass this information as part of a
298 request.
299 (1998-10-19)
301 By popular demand "referrer" exists as an alias for this method so
303 you can avoid this misspelling in your programs and still send the
304 right thing on the wire.
305 When setting the referrer, this method removes the fragment from
307 the given URI if it is present, as mandated by RFC2616. Note that
308 the removal does not happen automatically if using the header(),
309 push_header() or init_header() methods to set the referrer.
310 $h->www_authenticate
312 This header must be included as part of a "401 Unauthorized"
313 response. The field value consist of a challenge that indicates
314 the authentication scheme and parameters applicable to the
315 requested URI.
316 $h->proxy_authenticate
318 This header must be included in a "407 Proxy Authentication
319 Required" response.
320 $h->authorization
322 $h->proxy_authorization
323 A user agent that wishes to authenticate itself with a server or a
324 proxy, may do so by including these headers.
325 $h->authorization_basic
327 This method is used to get or set an authorization header that use
328 the "Basic Authentication Scheme". In array context it will return
329 two values; the user name and the password. In scalar context it
330 will return "uname:password" as a single string value.
331 When used to set the header value, it expects two arguments. E.g.:
333 $h->authorization_basic($uname, $password);
335 The method will croak if the $uname contains a colon ':'.
337 $h->proxy_authorization_basic
339 Same as authorization_basic() but will set the "Proxy-
340 Authorization" header instead.
341
343 The header field name spelling is normally canonicalized including the
344 '_' to '-' translation. There are some application where this is not
345 appropriate. Prefixing field names with ':' allow you to force a
346 specific spelling. For example if you really want a header field name
347 to show up as "foo_bar" instead of "Foo-Bar", you might set it like
348 this:
349 $h->header(":foo_bar" => 1);
351 These field names are returned with the ':' intact for
353 $h->header_field_names and the $h->scan callback, but the colons do not
354 show in $h->as_string.
355
357 Gisle Aas <gisle@activestate.com>
358
360 This software is copyright (c) 1994-2017 by Gisle Aas.
361 This is free software; you can redistribute it and/or modify it under
363 the same terms as the Perl 5 programming language system itself.
364perl v5.28.1 2018-06-05 HTTP::Headers(3)