NAME

Config::Environment - Application Configuration via Environment Variables

VERSION

version 0.000010

SYNOPSIS

    use Config::Environment;

    my $conf = Config::Environment->new('myapp');
    my $conn = $conf->param('db.1.conn' => 'dbi:mysql:dbname=foobar');
    my $user = $conf->param('db.1.user'); # via $ENV{MYAPP_DB_1_USER} or undef
    my $pass = $conf->param('db.1.pass'); # via $ENV{MYAPP_DB_1_PASS} or undef

    or

    my $info = $conf->param('db.1');
    say $info->{conn}; # outputs dbi:mysql:dbname=foobar
    say $info->{user}; # outputs the value of $ENV{MYAPP_DB_1_USER}
    say $info->{pass}; # outputs the value of $ENV{MYAPP_DB_1_PASS}

    likewise ...

    $conf->param('server' => {node => ['10.10.10.02', '10.10.10.03']});

    creates the following environment variables and assignments

    $ENV{MYAPP_SERVER_NODE_1} = '10.10.10.02';
    $ENV{MYAPP_SERVER_NODE_2} = '10.10.10.03';

    ... and the configuration can be retrieved using any of the following

    $conf->param('server');
    $conf->param('server.node');
    $conf->param('server.node.1');
    $conf->param('server.node.2');

    or

    my ($node1, $node2) = $conf->params(qw(server.node.1 server.node.2));

DESCRIPTION

Config::Environment is an interface for managing application configuration using environment variables as a backend. Using environment variables as a means of application configuration is a great way of controlling which parts of your application configuration gets hard-coded and shipped with your codebase (and which parts do not). Using environment variables, application configuration can be set at the system, user, and/or application levels and easily overridden.

ATTRIBUTES

autoload

The autoload attribute contains a boolean value which determines whether the global ENV hash will be sourced during instantiation. This attribute is set to true by default.

domain

The domain attribute contains the environment variable prefix used as context to differentiate between other environment variables.

lifecycle

The lifecycle attribute contains a boolean value which if true restricts any environment variables changes to life of the class instance. This attribute is set to false by default.

mirror

The mirror attribute contains a boolean value which if true copies any configuration assignments to the corresponding environment variables. This attribute is set to true by default.

override

The override attribute contains a boolean value which determines whether parameters corresponding to an existing environment variable can have it's value overridden. This attribute is set to true by default.

stash

The stash attribute contains a hashref which can be used to store arbitrary data which does not undergo parsing and which can be accessed using the param method.

METHODS

load

The load method expects a hashref which it parses and generates environment variables from (whether they exist or not) and registers the formatted environment structure. This method is called automatically on instantiation using the global ENV hash as an argument. Note! The hash can contain nested objects but it's keys should resemble capitalized/underscored environment variable names.

    my $hash = {
        APP_MODE => 'development',
        APP_USER => 'vagrant',
        APP_PORT => 9000
    };

    $self->load($hash);

param

The param method expects a key which it uses to locate the corresponding environment variable in the registered data structure. The key uses dot-notation to traverse hierarchical data in the registry. This method will return undefined if no element can be found matching the query. The method can also be used to set environment variables by passing an additional argument as the value in the form of a scalar, arrayref or hashref.

    my $item = $self->param($key);
    my $item = $self->param($key => $value);

    # load parsed data from another configuration source, e.g. a config file
    while (my($key, $val) = each(%$configuration) {
        $self->param($key => $val);
    }

params

The params method expects a list of keys which are used to locate the corresponding environment variables in the registered data structure. The keys use dot-notation to traverse hierarchical data in the registry and return a list of corresponding values in order specified. This method returns a list in list-context, otherwise it returns the first element found of the list of queries specified.

    my $item  = $self->params(@list_of_keys);
    my @items = $self->params(@list_of_keys);

You can also pass a single hash-reference to this method and have it traverse the key/value pairs and perform the desired assignments. This usage will not return a value.

    $self->params(\%params);

environment

The environment method returns a hashref representing all environment variables specific to the instantiated object's domain and instance.

    my $environment = $self->environment;

subdomain

The subdomain method returns a copy of the class instance with a modified domain reference for easier access to nested configuration keys.

    my $db  = $self->subdomain('db');
    my $db1 = $db->subdomain('1');

    $db1->param('conn' => $connstring);
    $db1->param('user' => $username);
    $db1->param('pass' => $password);

AUTHOR

Al Newkirk <anewkirk@ana.io>

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Al Newkirk.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm Config::Environment

perl -MCPAN -e shell
install Config::Environment