NAME

Prancer::Config

SYNOPSIS

    # load a configuration file when creating a PSGI application
    # this loads only one configuration file
    my $psgi = Foo->new("/path/to/foobar.yml")->to_psgi_app();

    # just load the configuration and use it wherever
    # this loads all configuration files from the given path using logic
    # described below to figure out which configuration files take precedence
    my $app = Prancer::Core->new("/path/to/mysite/conf");

    # the configuration can be accessed as either a global method or as an
    # instance method, depending on how you loaded Prancer
    print $app->config->get('foo');
    print config->get('bar');

DESCRIPTION

Prancer uses Config::Any to process configuration files. Anything supported by that will be supported by this. It will load configuration files from the configuration file or from configuration files in a path based on what you set when you create your application.

To find configuration files from given directory, Prancer::Config follows this logic. First, it will look for a file named config.ext where ext is something like yml or ini. Then it will look for a file named after the currently defined environment like develoment.ext or production.ext. The environment is determined by looking first for an environment variable called ENVIRONMENT and then for an environment variable called PLACK_ENV. If neither of those exist then the default is development.

Configuration files will be merged such that configuration values pulled out of the environment configuration file will take precedence over values from the global configuration file. For example, if you have two configuration files:

    config.ini
    ==========
    foo = bar
    baz = bat

    development.ini
    ===============
    foo = bazbat

After loading these configuration files the value for foo will be bazbat and the value for baz will be bat.

If you just have one configuration file and have no desire to load multiple configuration files based on environments you can specify a file rather than a directory when your application is created.

Arbitrary configuration directives can be put into your configuration files and they can be accessed like this:

    $config->get('foo');

The configuration accessors will only give you the configuration directives found at the root of the configuration file. So if you use any data structures you will have to decode them yourself. For example, if you create a YAML file like this:

    foo:
        bar1: asdf
        bar2: fdsa

Then you will only be able to get the value to bar1 like this:

    my $foo = config->get('foo')->{'bar1'};

Reserved Configuration Options

To support the components of Prancer, some keys are otherwise "reserved" in that you aren't able to use them. For example, trying to use the config key session will only result in sessions being enabled and you not able to see your configuration values. These reserved keys are: session and static.

METHODS

has key

This will return true if the named key exists in the configuration:

    if ($config->has('foo')) {
        print "I see you've set foo already.\n";
    }

It will return false otherwise.

get key [default]

The get method takes two arguments: a key and a default value. If the key does not exist then the default value will be returned instead. If the value in the configuration is a reference then a clone of the value will be returned to avoid modifying the configuration in a strange way. Additionally, this method is context sensitive.

    my $foo = $config->get('foo');
    my %bar = $config->get('bar');
    my @baz = $config->get('baz');

set key value

The set method takes two arguments: a key and a value. If the key already exists in the configuration then it will be overwritten and the old value will be returned in a context sensitive way. If the value is a reference then it will be cloned before being saved into the configuration to avoid any strangeness.

    my $old_foo = $config->set('foo', 'bar');
    my %old_bar = $config->set('bar', { 'baz' => 'bat' });
    my @old_baz = $config->set('baz', [ 'foo', 'bar', 'baz' ]);
    $config->set('whatever', 'do not care');

remove key

The remove method takes one argument: the key to remove. The value that was removed will be returned in a context sensitive way.

SEE ALSO

Config::Any