- Introduction
- The Apache Request Object
- The HTTP Request Message
- The Client Request
- Accessing Client Request Headers
- Accessing HTML Form Fields
- Reading POSTed Data Manually
- Manipulating Cookies
- Handling File Uploads
- Setting Server Response Headers
- Controlling Caching Behavior
- Sending Server Response Headers
- Setting the Response Status
- Setting Error Headers
- Manipulating Headers with Multiple Like Fields
- Using Subrequests
- Setting Headers for Subrequests
- Short-Circuiting Subrequests
- Getting or Setting the Request Method
- Accessing the Request Object from XS
This chapter is from the book
This chapter is from the book
This chapter is from the book
Setting Server Response Headers
You want to set the outgoing server response headers.
Technique
Use the specific server response methods, or the headers_out() method from the Apache class for those headers that do not have a specific method.
sub handler {
my $r = shift;
# Do something interesting, then...
# Set the MIME type.
$r->content_type('text/html');
# Set some other header.
$r->headers_out->set('Cache-Control' => 'must-revalidate');
# Now, send the headers.
$r->send_http_header;
# Continue along...
}
Comments
Setting all the proper headers required of a server response is not an easy task. The $r->as_string() output in Recipe 3.2 shows all the headers from a document that has been handled by mod_negotiation. As you can see from the abundance of headers present in the response, sending appropriate and meaningful headers can mean quite a lot of work. Fortunately, mod_perl offers help in many of the most difficult aspects of setting proper headers.
Acceptable server response headers are defined in section 6.2 of RFC 2616 (with the exception of the Set-Cookie header, which is described in RFC 2109). As with the incoming client request, general or entity headers may also apply to the server response. Again, more headers exist than those listed in Table 3.6, but these are the ones you are most likely to encounter.
Table 3.6 Some HTTP Response Headers
|
Header |
Description |
|
Cache-Control |
One of several fields used to specify caching behavior |
|
Content-Encoding |
Specifies the encoding of the sent resource |
|
Content-Language |
Specifies the language of the content. |
|
Content-Length |
The length of the resource |
|
Content-Type |
Media type of the resource |
|
Etag |
Entity tag of the sent resource |
|
Expires |
Time the resource is considered to be stale |
|
Last-Modified |
Date of last modification of the resource |
|
Location |
An absolute URI for redirection |
|
Pragma |
Generic header that can be used to implement any client- or server-specific behavior |
|
Set-Cookie |
Describes a client cookie to be set |
|
Server |
Information about the server platform |
Like with the client request headers, the collection of server response headers occupies its own place in the Apache request record, which is accessible through the headers_out() method from the Apache class. The headers_out() method functions in the same way as the headers_in() method discussed in Recipe 3.4; it returns an array of key/value pairs in a list context or an Apache::Table object in a scalar context. However, unlike with the client request headers, there are very few headers that you will actually use headers_out() to manipulate.
In most cases, the outgoing server response headers each have their own specialized method that is used to access and alter the server response headers. This is true for a few reasons. Some response headers are considered worthy of their own place in the Apache request record due to the far-reaching implications they may have on the request. The Content-Type and No-Cache headers are an example of this. Other response headers are so tricky to implement that it is easier to take advantage of the mod_perl API than to figure it out for yourself, such as the Etag header.
Table 3.7 lists the particular headers that should never be manipulated through the headers_out() method, but instead via their designated interface using the Apache request object.
Table 3.7 Response Header Methods
|
Method |
Description |
|
content_encoding() |
Provides access to the Content-Encoding information held in the Apache request record. |
|
content_languages() |
Provides access to the Content-Language array held in the Apache request record. |
|
content_type() |
Provides access to the MIME type for the requested resource that will accompany the Content-Type header. |
|
no_cache() |
Provides access to various cache-controlling headers, such as Pragma and Cache-Control. |
|
set_content_length() |
Sets the Content-Length header. |
|
set_etag() |
Sets the Etag header. |
|
set_last_modified() |
Sets the Last-Modified header. |
Examples of many of these methods will be shown throughout the book.