Writing Apache Modules with Perl and C By:   Lincoln Stein and Doug MacEachern Published:   O'Reilly & Associates, Inc.  - March 1999 Copyright © 1999 by O'Reilly & Associates, Inc.

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 ();