1HTTP::Headers(3) User Contributed Perl Documentation HTTP::Headers(3)
2
6 HTTP::Headers - Class encapsulating HTTP Message headers
7
9 version 6.26
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. In
62 addition to being a string, $value may be something that
63 stringifies.
64 The old value (or values) of the last of the header fields is
66 returned. If no such field exists "undef" will be returned.
67 A multi-valued field will be returned as separate values in list
69 context and will be concatenated with ", " as separator in scalar
70 context. The HTTP spec (RFC 2616) promises that joining multiple
71 values in this way will not change the semantic of a header field,
72 but in practice there are cases like old-style Netscape cookies
73 (see HTTP::Cookies) where "," is used as part of the syntax of a
74 single field value.
75 Examples:
77 $header->header(MIME_Version => '1.0',
79 User_Agent => 'My-Web-Client/0.01');
80 $header->header(Accept => "text/html, text/plain, image/*");
81 $header->header(Accept => [qw(text/html text/plain image/*)]);
82 @accepts = $header->header('Accept'); # get multiple values
83 $accepts = $header->header('Accept'); # get values as a single string
84 $h->push_header( $field => $value )
86 $h->push_header( $f1 => $v1, $f2 => $v2, ... )
87 Add a new field value for the specified header field. Previous
88 values for the same field are retained.
89 As for the header() method, the field name ($field) is not case
91 sensitive and '_' can be used as a replacement for '-'.
92 The $value argument may be a scalar or a reference to a list of
94 scalars.
95 $header->push_header(Accept => 'image/jpeg');
97 $header->push_header(Accept => [map "image/$_", qw(gif png tiff)]);
98 $h->init_header( $field => $value )
100 Set the specified header to the given value, but only if no
101 previous value for that field is set.
102 The header field name ($field) is not case sensitive and '_' can be
104 used as a replacement for '-'.
105 The $value argument may be a scalar or a reference to a list of
107 scalars.
108 $h->remove_header( $field, ... )
110 This function removes the header fields with the specified names.
111 The header field names ($field) are not case sensitive and '_' can
113 be used as a replacement for '-'.
114 The return value is the values of the fields removed. In scalar
116 context the number of fields removed is returned.
117 Note that if you pass in multiple field names then it is generally
119 not possible to tell which of the returned values belonged to which
120 field.
121 $h->remove_content_headers
123 This will remove all the header fields used to describe the content
124 of a message. All header field names prefixed with "Content-" fall
125 into this category, as well as "Allow", "Expires" and
126 "Last-Modified". RFC 2616 denotes these fields as Entity Header
127 Fields.
128 The return value is a new "HTTP::Headers" object that contains the
130 removed headers only.
131 $h->clear
133 This will remove all header fields.
134 $h->header_field_names
136 Returns the list of distinct names for the fields present in the
137 header. The field names have case as suggested by HTTP spec, and
138 the names are returned in the recommended "Good Practice" order.
139 In scalar context return the number of distinct field names.
141 $h->scan( \&process_header_field )
143 Apply a subroutine to each header field in turn. The callback
144 routine is called with two parameters; the name of the field and a
145 single value (a string). If a header field is multi-valued, then
146 the routine is called once for each value. The field name passed
147 to the callback routine has case as suggested by HTTP spec, and the
148 headers will be visited in the recommended "Good Practice" order.
149 Any return values of the callback routine are ignored. The loop
151 can be broken by raising an exception ("die"), but the caller of
152 scan() would have to trap the exception itself.
153 $h->flatten()
155 Returns the list of pairs of keys and values.
156 $h->as_string
158 $h->as_string( $eol )
159 Return the header fields as a formatted MIME header. Since it
160 internally uses the "scan" method to build the string, the result
161 will use case as suggested by HTTP spec, and it will follow
162 recommended "Good Practice" of ordering the header fields. Long
163 header values are not folded.
164 The optional $eol parameter specifies the line ending sequence to
166 use. The default is "\n". Embedded "\n" characters in header
167 field values will be substituted with this line ending sequence.
168
170 The most frequently used headers can also be accessed through the
171 following convenience methods. Most of these methods can both be used
172 to read and to set the value of a header. The header value is set if
173 you pass an argument to the method. The old header value is always
174 returned. If the given header did not exist then "undef" is returned.
175 Methods that deal with dates/times always convert their value to system
177 time (seconds since Jan 1, 1970) and they also expect this kind of
178 value when the header value is set.
179 $h->date
181 This header represents the date and time at which the message was
182 originated. E.g.:
183 $h->date(time); # set current date
185 $h->expires
187 This header gives the date and time after which the entity should
188 be considered stale.
189 $h->if_modified_since
191 $h->if_unmodified_since
192 These header fields are used to make a request conditional. If the
193 requested resource has (or has not) been modified since the time
194 specified in this field, then the server will return a "304 Not
195 Modified" response instead of the document itself.
196 $h->last_modified
198 This header indicates the date and time at which the resource was
199 last modified. E.g.:
200 # check if document is more than 1 hour old
202 if (my $last_mod = $h->last_modified) {
203 if ($last_mod < time - 60*60) {
204 ...
205 }
206 }
207 $h->content_type
209 The Content-Type header field indicates the media type of the
210 message content. E.g.:
211 $h->content_type('text/html');
213 The value returned will be converted to lower case, and potential
215 parameters will be chopped off and returned as a separate value if
216 in an array context. If there is no such header field, then the
217 empty string is returned. This makes it safe to do the following:
218 if ($h->content_type eq 'text/html') {
220 # we enter this place even if the real header value happens to
221 # be 'TEXT/HTML; version=3.0'
222 ...
223 }
224 $h->content_type_charset
226 Returns the upper-cased charset specified in the Content-Type
227 header. In list context return the lower-cased bare content type
228 followed by the upper-cased charset. Both values will be "undef"
229 if not specified in the header.
230 $h->content_is_text
232 Returns TRUE if the Content-Type header field indicate that the
233 content is textual.
234 $h->content_is_html
236 Returns TRUE if the Content-Type header field indicate that the
237 content is some kind of HTML (including XHTML). This method can't
238 be used to set Content-Type.
239 $h->content_is_xhtml
241 Returns TRUE if the Content-Type header field indicate that the
242 content is XHTML. This method can't be used to set Content-Type.
243 $h->content_is_xml
245 Returns TRUE if the Content-Type header field indicate that the
246 content is XML. This method can't be used to set Content-Type.
247 $h->content_encoding
249 The Content-Encoding header field is used as a modifier to the
250 media type. When present, its value indicates what additional
251 encoding mechanism has been applied to the resource.
252 $h->content_length
254 A decimal number indicating the size in bytes of the message
255 content.
256 $h->content_language
258 The natural language(s) of the intended audience for the message
259 content. The value is one or more language tags as defined by RFC
260 1766. Eg. "no" for some kind of Norwegian and "en-US" for English
261 the way it is written in the US.
262 $h->title
264 The title of the document. In libwww-perl this header will be
265 initialized automatically from the <TITLE>...</TITLE> element of
266 HTML documents. This header is no longer part of the HTTP
267 standard.
268 $h->user_agent
270 This header field is used in request messages and contains
271 information about the user agent originating the request. E.g.:
272 $h->user_agent('Mozilla/5.0 (compatible; MSIE 7.0; Windows NT 6.0)');
274 $h->server
276 The server header field contains information about the software
277 being used by the originating server program handling the request.
278 $h->from
280 This header should contain an Internet e-mail address for the human
281 user who controls the requesting user agent. The address should be
282 machine-usable, as defined by RFC822. E.g.:
283 $h->from('King Kong <king@kong.com>');
285 This header is no longer part of the HTTP standard.
287 $h->referer
289 Used to specify the address (URI) of the document from which the
290 requested resource address was obtained.
291 The "Free On-line Dictionary of Computing" as this to say about the
293 word referer:
294 <World-Wide Web> A misspelling of "referrer" which
296 somehow made it into the {HTTP} standard. A given {web
297 page}'s referer (sic) is the {URL} of whatever web page
298 contains the link that the user followed to the current
299 page. Most browsers pass this information as part of a
300 request.
301 (1998-10-19)
303 By popular demand "referrer" exists as an alias for this method so
305 you can avoid this misspelling in your programs and still send the
306 right thing on the wire.
307 When setting the referrer, this method removes the fragment from
309 the given URI if it is present, as mandated by RFC2616. Note that
310 the removal does not happen automatically if using the header(),
311 push_header() or init_header() methods to set the referrer.
312 $h->www_authenticate
314 This header must be included as part of a "401 Unauthorized"
315 response. The field value consist of a challenge that indicates
316 the authentication scheme and parameters applicable to the
317 requested URI.
318 $h->proxy_authenticate
320 This header must be included in a "407 Proxy Authentication
321 Required" response.
322 $h->authorization
324 $h->proxy_authorization
325 A user agent that wishes to authenticate itself with a server or a
326 proxy, may do so by including these headers.
327 $h->authorization_basic
329 This method is used to get or set an authorization header that use
330 the "Basic Authentication Scheme". In array context it will return
331 two values; the user name and the password. In scalar context it
332 will return "uname:password" as a single string value.
333 When used to set the header value, it expects two arguments. E.g.:
335 $h->authorization_basic($uname, $password);
337 The method will croak if the $uname contains a colon ':'.
339 $h->proxy_authorization_basic
341 Same as authorization_basic() but will set the "Proxy-
342 Authorization" header instead.
343
345 The header field name spelling is normally canonicalized including the
346 '_' to '-' translation. There are some application where this is not
347 appropriate. Prefixing field names with ':' allow you to force a
348 specific spelling. For example if you really want a header field name
349 to show up as "foo_bar" instead of "Foo-Bar", you might set it like
350 this:
351 $h->header(":foo_bar" => 1);
353 These field names are returned with the ':' intact for
355 $h->header_field_names and the $h->scan callback, but the colons do not
356 show in $h->as_string.
357
359 Gisle Aas <gisle@activestate.com>
360
362 This software is copyright (c) 1994 by Gisle Aas.
363 This is free software; you can redistribute it and/or modify it under
365 the same terms as the Perl 5 programming language system itself.
366perl v5.32.0 2020-09-10 HTTP::Headers(3)