Apache::RequestRec - Perl API for Apache request record accessors
use Apache::RequestRec (); sub handler{ my $r = shift; ... my $auth_type = $r->auth_type; ... my $s = $r->server; }
META: to be completed
Apache::RequestRec provides the Perl API for Apache request object.
Apache::RequestRec
Apache::RequestRec provides the following functions and/or methods:
proxyreq
Get and set the proxyrec request record member and optionally adjust other related fields.
$ret = $r->proxyreq($val);
$r
$val
0, 1 or none.
$ret
If $val is 0 or 1, the proxyrec member will be set to that value and previous value will be returned.
If $val is not passed, and $r->proxyreq is not true, and the proxy request is matching the current vhost (scheme, hostname and port), the proxyrec member will be set to 1 and that value will be returned. In addition $r->uri is set to $r->unparsed_uri and $r->filename is set to "modperl-proxy:".$r->uri. If those conditions aren't true 0 is returned.
$r->proxyreq
$r->uri
$r->unparsed_uri
$r->filename
"modperl-proxy:".$r->uri
For example to turn a normal request into a proxy request to be handled on the same server in the PerlTransHandler phase run:
PerlTransHandler
my $real_url = $r->unparsed_uri; $r->proxyreq(1); $r->uri($real_url); $r->filename("proxy:$real_url"); $r->handler('proxy-server');
Also remember that if you want to turn a proxy request into a non-proxy request, it's not enough to call:
$r->proxyreq(0);
You need to adjust $r->uri and $r->filename as well if you run that code in PerlPostReadRequestHandler phase, since if you don't -- mod_proxy's own post_read_request handler will override your settings (as it will run after the mod_perl handler).
PerlPostReadRequestHandler
mod_proxy
pool
META: Autogenerated - needs to be reviewed/completed
The pool associated with the request
$p = $r->pool();
$p
APR::Pool
connection
The connection record to the client
$c = $r->connection();
$c
Apache::Connection
server
Get the Apache::Server object for the server the request $r is running under.
Apache::Server
$s = $r->server();
$s
next
Pointer to the redirected request if this is an external redirect
$next_r = $r->next();
$next_r
prev
Pointer to the previous request if this is an internal redirect
$prev_r = $r->prev();
$prev_r
main
Get the main request record
$main_r = $r->main();
$main_r
If the current request is a sub-request, this method returns a blessed reference to the main request structure. If the current request is the main request, then this method returns undef.
To figure out whether you are inside a main request or a sub-request/internal redirect, use $r->is_initial_req.
$r->is_initial_req
the_request
First line of request
$request = $r->the_request();
$request
assbackwards
When set to a true value, Apache won't send any HTTP response headers allowing you to send any headers.
$status = $r->assbackwards($newval); $status = $r->assbackwards();
$newval
assign a new state.
$status
current state.
If you send your own set of headers, which includes the Keep-Alive HTTP response header, you must make sure to increment the number of requests served over this connection (which is normally done by the core connection output filter ap_http_header_filter, but skipped when assbackwards is enabled).
Keep-Alive
ap_http_header_filter
$r->connection->keepalives($r->connection->keepalives + 1);
otherwise code relying on the value of $r->connection->keepalives may malfunction. For example, this counter is used to tell when a new request is coming in over the same connection to a filter that wants to parse only HTTP headers (like Apache::Filter::HTTPHeadersFixup). Of course you will need to set $r->connection->keepalive(1)) as well.
$r->connection->keepalives
Apache::Filter::HTTPHeadersFixup
$r->connection->keepalive(1)
header_only
HEAD request, as opposed to GET
$status = $r->header_only();
protocol
Protocol string, as given to us, or HTTP/0.9
$protocol = $r->protocol();
$protocl
proto_num
Protocol version number of protocol; 1.1 = 1001
$proto_num = $r->proto_num();
$proto_num
hostname
Host, as set by full URI or Host:
$hostname = $r->hostname();
$hostname
request_time
Time when the request started
$request_time = $r->request_time();
$request_time
status_line
Status line, if set by script
$status_line = $r->status_line();
$status_line
status
Get/set status line
$status = $r->status($new_status); $status = $r->status();
$new_status
If $new_status is passed the new status is assigned.
If $new_status is passed the old status is returned.
method
Request method (eg. GET, HEAD, POST, etc.)
$method = $r->method();
$method
method_number
Apache::M_GET, Apache::M_POST, etc.
$methno = $r->method_number();
$methno
allowed
'allowed' is a bitvector of the allowed methods.
$allowed = $r->allowed();
$allowed
A handler must ensure that the request method is one that it is capable of handling. Generally modules should DECLINE any request methods they do not handle. Prior to aborting the handler like this the handler should set r->allowed to the list of methods that it is willing to handle. This bitvector is used to construct the "Allow:" header required for OPTIONS requests, and HTTP_METHOD_NOT_ALLOWED and HTTP_NOT_IMPLEMENTED status codes.
Since the default_handler deals with OPTIONS, all modules can usually decline to deal with OPTIONS. TRACE is always allowed, modules don't need to set it explicitly.
Since the default_handler will always handle a GET, a module which does *not* implement GET should probably return HTTP_METHOD_NOT_ALLOWED. Unfortunately this means that a Script GET handler can't be installed by mod_actions.
allowed_xmethods
Array of extension methods
$array = $r->allowed_xmethods();
$array
APR::ArrayHeader
allowed_methods
List of allowed methods
$list = $r->allowed_methods();
$list
Apache::MethodList
bytes_sent
body byte count, for easy access
$bytes_sent = $r->bytes_sent();
$bytes_sent
mtime
Last modified time of the requested resource
$mtime = $r->mtime($new_mtime); $mtime = $r->mtime();
$new_mtime
$mtime
remaining
Remaining bytes left to read from the request body
$bytes = $r->remaining();
META: I think this method is not needed if the deprecated client_block methods aren't used, (and plain $r-<read() is used instead).
$bytes
headers_in
$headers_in = $r->headers_in();
$headers_in
APR::Table
headers_out
MIME header environment for the response
$headers_out = $r->headers_out();
$headers_out
err_headers_out
MIME header environment for the response, printed even on errors and persist across internal redirects
$err_headers_out = $r->err_headers_out();
$err_headers_out
The difference between headers_out and err_headers_out is that the latter are printed even on error, and persist across internal redirects (so the headers printed for ErrorDocument handlers will have them).
notes
Notes from one module to another
$notes = $r->notes(); $notes = $r->notes($new_notes);
$new_notes
$notes
The 'notes' is for notes from one module to another, with no other set purpose in mind...
handler
$handler = $r->handler(); $handler = $r->handler($new_handler);
$new_handler
$handler
content_type
Get/set the HTTP response Content-type header value.
my $content_type = $r->content_type(); my $content_type = $r->content_type($new_content_type);
$new_content_type
Assign a new HTTP response content-type. It will affect the response only if HTTP headers weren't sent yet.
$content_type
The current content-type value.
For example, set the Content-type header to text/plain.
Content-type
$r->content_type('text/plain');
If you set this header via the headers_out table directly, it will be ignored by Apache. So do not do that.
content_encoding
$ce = $r->content_encoding();
$ce
content_languages
Array of strings representing the content languages
$array_header = $r->content_languages();
$array_header
user
If an authentication check was made, this gets set to the user name.
$r->user($user); $user = $r->user();
$user
ap_auth_type
If an authentication check was made, get or set the ap_auth_type slot in the request record
$auth_type = $r->ap_auth_type(); $r->ap_auth_type($newval);
If this argument is passed then a new auth type is assigned. For example:
$r->auth_type('Basic');
$auth_type
If $newval is passed, nothing is returned. Otherwise the current auth type is returned.
ap_auth_type holds the authentication type that has been negotiated between the client and server during the actual request. Generally, ap_auth_type is populated automatically when you call $r->get_basic_auth_pw so you don't really need to worry too much about it, but if you want to roll your own authentication mechanism then you will have to populate ap_auth_type yourself.
$r->get_basic_auth_pw
Note that $r->ap_auth_type was $r->connection->auth_type in the mod_perl 1.0 API.
$r->ap_auth_type
$r->connection->auth_type
no_local_copy
There is no local copy of this response
$status = $r->no_local_copy();
unparsed_uri
The URI without any parsing performed
$unparsed_uri = $r->unparsed_uri();
$unparsed_uri
uri
The path portion of the URI
$uri = $r->uri(); $r->uri($uri);
$uri
filename
The filename on disk corresponding to this response
$filename = $r->filename(); $r->filename($filename);
$filename
canonical_filename
$canon_filename = $r->canonical_filename();
$canon_filename
path_info
The PATH_INFO extracted from this request
$path_info = $r->path_info(); $r->path_info($path_info);
$path_info
args
The QUERY_ARGS extracted from this request
$args = $r->args(); $r->args($args);
$args
used_path_info
Flag for the handler to accept or reject path_info on the current request. All modules should respect the AP_REQ_ACCEPT_PATH_INFO and AP_REQ_REJECT_PATH_INFO values, while AP_REQ_DEFAULT_PATH_INFO indicates they may follow existing conventions. This is set to the user's preference upon HOOK_VERY_FIRST of the fixups.
$ret = $r->used_path_info($newval);
per_dir_config
These are config vectors, with one void* pointer for each module (the thing pointed to being the module's business). * Options set in config files, etc.
$per_dir_config = $r->per_dir_config();
$per_dir_config
Apache::ConfVector
request_config
Notes on *this* request
$ret = $r->request_config($newval);
output_filters
A list of output filters to be used for this request
$output_filters = $r->output_filters();
$output_filters
Apache::Filter
input_filters
A list of input filters to be used for this request
$input_filters = $r->input_filters();
$input_filters
proto_output_filters
A list of protocol level output filters to be used for this request
$proto_output_filters = $r->proto_output_filters();
$proto_output_filters
proto_input_filters
A list of protocol level input filters to be used for this request
$proto_input_filters = $r->proto_input_filters();
$proto_input_filters
mod_perl 2.0 documentation.
mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 1.1.
The mod_perl development team and numerous contributors.
To install mod_perl, copy and paste the appropriate command in to your terminal.
cpanm
cpanm mod_perl
CPAN shell
perl -MCPAN -e shell install mod_perl
For more information on module installation, please visit the detailed CPAN module installation guide.