NAME

INTRO

CONFIGURING

    <global>
        database_server_name ourdb.ourcompany.com
    </global>

    <shared appearance>
        background white
        foreground blue
    </shared>

    <instance app1>
        ConfigureVia FlatFile Config::General /path/to/file
        use appearance
    </instance>

    <instance app2>
        ConfigureVia HTTP Config::General http://conf.oc.com/conf
        use appearance
    </instance>

    <instance right_here>
        var   value
        color blue
    </instance>

    include /etc/gantry.d/*.conf

Then in /etc/gantry.d/app3.conf:

    <instance app3>
        ConfigureVia FlatFile Config::Tiny /path/to/conf
        ConfigureVia HTTP Config::General http://conf.oc.com/conf
    </instance>

Each application instance has a section in this file, unless its instance can be gleaned from /etc/gantry.d. This allows not only multiple apps, but also multiple instances of the same app running in the same server. The instance name must be unique and is what the app uses to find its conf.

In the instance block, you may choose to define conf variables and their values directly (as the "right_here" instance does above). Otherwise, the core of any instance's configuration is the ConfigureVia statement(s). The form of these statments vary by the configuration method.

The methods supported are:

PerlSetVar

This method is designed for use in a mod_perl setting. Here's a typical example:

    <instance inmod_perl>
        ConfigureVia PerlSetVar
        LoadParameters the variables you need here note the \
                       backslash allowed by Config General
    </instance>
    

The listed parameters are loaded using dir_config on the apache request object.

In the future, it may be possible to use this method outside of mod_perl. In that case, you will have to factor out the part of the apache conf relating to this application into a separate file and include:

    ApacheConfigFile /path/to/your.conf
    

This will only be used outside of mod_perl.

Note that this feature is not yet available and may never be.

ParamBuilder

This method is not yet available, but it will work like PerlSetVar above, except it will expect to see variables defined for ParamBuilder use.

FlatFile

Use this if you keep your conf in one or more flat files somewhere on your local system.

    <instance app>
        ConfigureVia FlatFile Config::General file1 [file2...]
    </instance>
    

In this case, I chose to use Config::General to parse the file. The other current choice is Config::Tiny. If you need a different flat file syntax, you need to implement a provider for it, see "EXTENDING Gantry::Conf".

See the perldoc for your provider for the syntax your conf file must follow.

SQL

HTTP

If your conf is available through the web, via http or https use this method to retrieve your config information from a remote system:

    <instance app>
        ConfigureVia HTTP Config::General url [url...]
    </instance>
    

You can use all the same providers for the HTTP method as you use for the FlatFile method. That provider is responsible for converting the response from the server into a conf hash.

To include apache basic auth information, add it to the url:

    http://user:pass@host.example.com/path/to/conf
    

Note that ssl is supported (by LWP), so you can use https://... to keep your configuration information from traveling in the clear.

Default

Normally, you get the default merely by omitting the ConfigureVia statement from an instance block. Then the configuration must be included directly in Gantry::Conf format in the <instance> block.

Any instance can share conf with other instances in three ways:

repeated ConfigureVia statements

Each instance block can have as many ConfigureVia statements as you want. Earlier ones have precedence. In the example above, the app3 instance has its own flat file of conf information, but also refers to the http served conf that app2 is using.

I'll say it again: precedence goes the earliest file listed. So if you have an instance that looks like this:

  <instance appoverride> 
    ConfigureVia FlatFile Config::Tiny /etc/appoverride.conf 
    ConfigureVia HTTP Config::General http://dev.domain.com/main.conf 
  </instance>
    

then any configuration options in /etc/appoverride.conf will override those found in the remote http://dev.domain.com/main.conf.

global

If you define a global block, all instances will have the variables defined in it included in their conf hashes. To override a global, define the same variable in the conf data source of one of your ConfigVia statements. In the example above, all three instances share the database_server_name variable (unless their individual conf data sources define the same variable).

use

If two or more apps need to share a set of configuration options which you want to define directly in the Gantry::Conf file, put them in a shared block. Then include a use statement in each instance block which should share this data. To override a shared variable, define the same variable in the conf data source of one of your ConfigVia statements. In the example above, app1 and app2 share all the variables in the appearance shared block.

The precedence is:

1.

ConfigVia statements in the order they appear.

2.

Any variables declared in the global block.

3.

Any shared blocks used by the instance in the order they appear.

Note that you may use "include" at any point passing it a shell style file glob. Any matching files will be included at that point as if typed there. This is highly convenient for separating config information into separate files by app. Then your master config file (/etc/gantry.conf) might be as simple as:

    include /etc/gantr.d/*.conf

USING A CONFIGURATION

    use Gantry::Conf;

    my $conf = Gantry::Conf->retrieve(
        {
            instance    => 'app1',
            config_file => '/etc/gantry.confs/standard.conf',
        }
    );

When using Gantry::Conf with mod_perl you should specify the config file inside of a Perl block or your apache startup file as follows:

    use Gantry::Conf qw(-Config=/etc/gantry.conf)

Failure to do so will cause Gantry::Conf to reload its configuration on each request.

When calling retrieve, you must provide the parameters by name in a hash reference. The only required key is "instance". Gantry::Conf will look for the instance in the "config_file". By default the config_file is "/etc/gantry.conf". If your config files use GantryLocation blocks, like this:

    level_name top
    all_share 5
    reset 5

    <GantryLocation /second>
        level_name second
        reset 4
    </GantryLevel>

    <GantryLocation /second/nested>
        level_name second.nested
        reset 2
    </GantryLevel>

You can pass "location" to retrieve, then you will get the values for the specified location. Note that parameters are not inherited from "parent" locations. All locations are thought to be independent. Thus, if "/second/nested" above did not define "reset", its value for it would be 5 (inherited from the top level) and not 4 (which "/second" defined).

EXTENDING Gantry::Conf

To implement your own FlatFile provider name it like this:

    package Gantry::Conf::Provider::Module;

Then put a method in it called config which is called as a class method taking a single parameter. For example, here is the whole Config::General provider:

    package Gantry::Conf::Provider::FlatFile::Config::General;

    use strict;
    use warnings;

    use Carp qw(croak);

    use Config::General;
    use Gantry::Conf::Provider;
    use base qw( Gantry::Conf::Provider );

    sub config {
        my $self    =   shift;
        my $file    =   shift;

        my $config = Config::General->new( $file ) or
                croak "Unable to create Config::General object: $!";

        my %confs = $config->getall;

        return( \%confs );

    } # END config

SEE ALSO

AUTHOR

Frank Wiles <frank@revsys.com>

COPYRIGHT and LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.6 or, at your option, any later version of Perl 5 you may have available.