Show Contents Previous Page Next Page
Chapter 9 - Perl API Reference Guide / The Apache Request Object
Server Configuration Methods Several methods give you access to the Apache server's configuration settings.
You can inspect the configuration and, in many cases, change it dynamically.
The most commonly needed configuration information can be obtained directly
from the methods given in this section. More esoteric information can be obtained
via the Apache::Server object returned by the request object's server()
method. See the section "The Apache::Server Class" for details.
dir_config()
The dir_config() method and the PerlSetVar configuration
directive together form the primary way of passing configuration information
to Apache Perl modules. The PerlSetVar directive can occur in the main part of a
configuration file, in a <VirtualHost> , <Directory>,
<Location>, or <Files> section, or in
a .htaccess file. It takes a key/ value pair separated by whitespace.
In the following two examples, the first directive sets a key named
Gate to a value of open. The second sets the
same key to a value of wide open andbeckoning. Notice how quotes are used to protect arguments
that contain whitespace:
PerlSetVar Gate open
PerlSetVar Gate "wide open and beckoning"
Configuration files can contain any number of PerlSetVar
directives. If multiple directives try to set the same key, the usual
rules of directive precedence apply. A key defined in a .htaccess
file has precedence over a key defined in a <Directory>,
<Location>, or <Files> section, which
in turn has precedence over a key defined in a <VirtualHost>
section. Keys defined in the main body of the configuration file have
the lowest precedence of all. Configuration keys set with PerlSetVar can be recovered within
Perl handlers using dir_ config(). The interface is simple.
Called with the name of a key, dir_config() looks up the key
and returns its value if found or undef otherwise.
my $value = $r->dir_config('Gate');
If called in a scalar context with no arguments, dir_config()
returns a hash reference tied to the Apache::Table class. See
"The Apache::Table Class" for
details.
my $dir_config = $r->dir_config;
my $value = $dir_config->{'Gate'};
Only scalar values are allowed in configuration variables set by PerlSetVar.
If you want to pass an array or hash, separate the items by a character
that doesn't appear elsewhere in the string and call split()
to break the retrieved variable into its components.
document_root()
The document_root() method returns the value of the document
root directory. The value of the document root is set by the server
configuration directive DocumentRoot and usually varies between
different virtual hosts. Apache uses the document root to translate
the URI into a physical pathname unless a more specific translation
rule, such as Alias, applies.
my $doc_root = $r->document_root;
If you are used to using the environment variable DOCUMENT_ROOT
within your CGI scripts in order to resolve URIs into physical pathnames,
be aware that there's a much better way to do this in the Apache API.
Perform a subrequest with the URI you want to resolve, and then call
the returned object's filename() method. This works correctly
even when the URI is affected by Alias directives or refers
to user-maintained virtual directories:
my $image = $r->lookup_uri('/~fred/images/cookbook.gif')->filename;
If you're interested in fetching the physical file corresponding to
the current request, call the current request object's filename()
method:
my $file = $r->filename;
get_server_port()
This method returns the port number on which the server is listening.
my $port = $r->get_server_port;
If UseCanonicalName is configured to be On (the default),
this method will return the value of the Port configuration directive.
If no Port directive is present, the default port 80 is returned.
If UseCanonicalName is Off and the client sent a Host
header, then the method returns the actual port specified here, regardless
of the value of the Port directive.
get_server_name()
This read-only method returns the name of the server handling the
request.
my $name = $r->get_server_name;
This method is sensitive to the value of the UseCanonicalName
configuration directive. If UseCanonicalName is On
(the default), the method will always return the value of the current
ServerName configuration directive. If UseCanonicalName
is Off, then this method will return the value of the incoming
request's Host header if present, or the value of the ServerName
directive otherwise. These values can be different if the server has
several different DNS names. The lower-level server_name() method in the Apache::Server
class always acts as if UseCanonicalName were on.
server_root_relative()
Called without any arguments, the server_root_relative()
method returns the currently configured ServerRoot directory
(in which Apache's binaries, configuration files, and logs commonly
reside). If you pass this method a relative pathname, it will resolve
the relative pathname to an absolute one based on the value of the server
root. This is the preferred way to locate configuration and log files
that are stored beneath the server root.
# return ServerRoot
my $ServerRoot = $r->server_root_relative;
# return $ServerRoot/logs/my.log
my $log = $r->server_root_relative("logs/my.log");
The server_root_relative method can also be invoked without
a request object by calling it directly from the Apache class. The following
example, which might be found at the beginning of a Perl startup file,
first imports the Apache module and then uses server_root_relative()
to add a site-specific library directory to the search path. It does
this in a BEGIN {} block to ensure that this code is evaluated
first. It then loads a local module named My::App, which
presumably will be found in the site-specific directory.
#!/usr/bin/perl
# modify the search path
BEGIN {
use Apache():
use lib Apache->server_root_relative("lib/my_app");
}
use My::App ();
Show Contents Previous Page Next Page
Copyright © 1999 by O'Reilly & Associates, Inc. | 
