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 8 - Customizing the Apache Configuration Process / The Apache Configuration Directive API
The Apache::CmdParms and Apache::ModuleConfig Classes

The configuration mechanism uses two auxiliary classes, Apache::CmdParms and Apache::ModuleConfig, to pass information between Apache and your module.

Apache::ModuleConfig is the simpler of the two. It provides just a single method, get(), which retrieves a module's current configuration information. The return value is the object created by the DIR_CREATE() or SERVER_CREATE() methods.

The get() method is called with the current request object or server object and an optional additional argument indicating which module to retrieve the configuration from. In the typical case, you'll omit this additional argument to indicate that you want to fetch the configuration information for the current module. For example, we saw this in the Apache::PassThru handler() routine:

my $cfg = Apache::ModuleConfig->get($r);

This call returns the per-directory configuration object because the argument to get() is the current request. To obtain the per-server configuration object, provided that you defined a SERVER_CREATE() routine, pass the request's server object instead:

my $cfg = Apache::ModuleConfig->get($r->server);

As a convenience, the per-directory configuration object for the current module is always the first argument passed to any configuration processing callback routine. Directives processing callbacks that need to operate on server-specific configuration data should ignore this hash and fetch the configuration data themselves using a technique we will discuss shortly.

It is also possible for one module to peek at another module's configuration data by naming its package as the second argument to get():

my $friends_cfg = Apache::ModuleConfig->get($r, 'Apache::TrafficCop');

You can now read and write the other module's configuration information!

Apache::CmdParms is a helpful class that Apache uses to pass a variety of configuration information to modules. An Apache::CmdParms object is the second argument passed to directive handler routines.

The various methods available from Apache::CmdParms are listed fully in Chapter 9, Perl API Reference Guide. The two you are most likely to use in your modules are server() and path(). server() returns the Apache::Server object corresponding to the current configuration. From this object you can retrieve the virtual host's name, its configured port, the document root, and other core configuration information. For example, this code retrieves the administrator's name from within a configuration callback and adds it to the module's configuration table:

sub TrafficCopActiveSergeant ($$$) {
  my($cfg, $parms, $arg) = @_;
  $cfg->{Sergeant} = $arg;
  my $chief_of_police = $parms->server->server_admin;
  $cfg->{ChiefOfPolice} = $chief_of_police;
}

The server() method is also vital when directive processing callbacks need to set server-specific configuration information. In this case, the per-directory configuration passed as the first callback argument must be ignored, and the per-server configuration must be fetched by calling the Apache::ModuleConfigget() with the server object as its argument.

Here's an example:

sub TrafficCopDispatcher ($$$) {
   my($cfg, $parms, $arg) = @_;
   my $scfg = Apache::ModuleConfig->get($parms->server)
   $scfg->{Dispatcher} = $arg;
}

If the configuration-processing routine is being called to process a container directive such as <Location> or <Directory>, the Apache::CmdParms path() method will return the directive's argument. Depending on the context this might be a URI, a directory path, a virtual host address, or a filename pattern.

See Chapter 9 for details on other methods that Apache::ModuleConfig and Apache::CmdParms makes available.