- 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
The Client Request
You want to access basic information about the incoming client request.
Technique
Use the request object to access the various fields of the Apache request record.
#!/usr/bin/perl -w
use strict;
my $r = shift;
# Send our basic headers.
$r->send_http_header('text/plain');
# Read things you would normally get from CGI.
print " REQUEST_METHOD is: ", $r->method, "\n";
print " REQUEST_URI is: ", $r->uri, "\n";
print "SERVER_PROTOCOL is: ", $r->protocol, "\n";
print " PATH_INFO is: ", $r->path_info, "\n";
print " QUERY_STRING is: ", scalar $r->args, "\n";
print "SCRIPT_FILENAME is: ", $r->filename, "\n";
print " SERVER_NAME is: ", $r->hostname, "\n";
Comments
Before any of your mod_perl code is allowed to interact with the incoming request, Apache populates various fields within the request record with various bits of important information. The Apache class provides a large set of methods to access the details of the incoming request directly from the Apache request record. These methods include uri(), args() and others. The sample Apache::Registry script illustrates their use.
Assume our sample Apache::Registry script is placed within the directory /usr/local/apache/perl-bin/, and we type the following URL into our Web browser:
http://www.example.com/perl-bin/echo.pl/extra?x=1The results would be comparable to what you would expect to see contained in %ENV for a normal CGI script. When programming in a mod_perl environment, such as when using Apache::Registry, the Apache methods are preferred over their %ENV counterparts because populating %ENV is expensive to do on every request (which is why the PerlSetupEnv directive exists, as described in Recipe 2.6). Additionally, these methods allow for greater flexibility, because most can also modify their corresponding field in the request record, and as you begin to program outside of the content-generation phase, the ability to alter the request record becomes important.
Table 3.2 summarizes the methods available to the Apache request object for interfacing with the client request data found in the request record.
Table 3.2 Methods for Accessing Request Data
|
Method |
Example Value |
Details |
|
args() |
x=1 |
Returns the chunk of text following the ? in the URL when called in a scalar context. |
|
filename() |
/usr/local/apache/¬perl-bin/echo.pl |
Provides access to the translated script name for this request. |
|
header_only() |
TRUE |
Returns true if the request is a HEAD request |
|
hostname() |
spinnaker.example.com |
Returns the name of the host running the script; this may well be different than the host in the URL in the user's browser. |
|
method() |
GET |
Provides access to the HTTP method used for this request is returned. GET and POST are most commonly used. |
|
path_info() |
/extra |
Provides access to the additional path information located after the script name for this request. Does not include the query string. |
|
protocol() |
HTTP/1.0 |
Returns the protocol for this request. Generally this is either HTTP/1.0 or HTTP/1.1. |
|
proxyreq() |
TRUE |
Returns true if the request is a proxy request |
|
uri() |
/perl-bin/echo.pl/extra |
Provides access to the request URI, which includes the basic request, plus additional path information. |
You can do a lot with this basic set of methods for reading the client request. However, mod_perl provides even higher level abstractions of this data. Later recipes introduce classes such as Apache::URI and Apache::Request, both high level object interfaces to the request information.