8.1. Simple Configuration with the PerlSetVar Directive

The Apache Perl API provides a simple mechanism for passing information from configuration files to Perl modules using the PerlSetVar directive. As we've seen, the directive takes two arguments, the name of a variable and its value:

PerlSetVar FoodForThought apples

Because Perl is such a whiz at parsing text, it's trivial to pass an array or even a hash in this way. For example, here's one way (out of a great many) to pass an array:

# in configuration file
PerlSetVar FoodForThought apples:oranges:kiwis:mangos

# in Perl module
@foodForThought = split ":", $r->dir_config('FoodForThought'),

And here's a way to pass a hash:

# in configuration file
PerlSetVar FoodForThought apples=>23,kiwis=>12

# in Perl module
%foodForThought = split /s*(?:=>|,)s*/, $r->dir_config('FoodForThought);

Notice that the pattern match allows whitespace to come before or after the comma or arrow operators, just as Perl does.

By modifying the pattern match appropriately, you can pass more complex configuration information. The only trick is to remember to put double quotes around the configuration value if it contains whitespace and not to allow your text editor to wrap it to another line. You can use backslash as a continuation character if you find long lines a pain to read:

PerlSetVar FoodForThought "apples    => 23,
                           kiwis     => 12,
                           rutabagas => 0"

If you have a really complex configuration, then you are probably better off using a separate configuration file and pointing to it using a single PerlSetVar directive. The server_root_relative() method is useful for specifying configuration files that are relative to the server root:

# in server configuration file
PerlSetVar  FoodConfig conf/food.conf

# in Perl module
$conf_file = $r->server_root_relative($r->dir_config('FoodConfig'));

Despite the simplicity of this approach, there are times when you may prefer to create your own "first-class" configuration directives. This becomes particularly desirable when you have many different directives, when the exact syntax of the directives is important and you want Apache to check the syntax at startup time, or when you are planning to distribute your module and want it to appear polished. There is also a performance penalty associated with parsing PerlSetVar configuration at request time, which you avoid using first-class configuration directives because they are parsed once at server startup time.