/ 
Config-Abstraction-0.37
River stage two • 5 direct dependents • 16 total dependents
/ README.md

NAME

Config::Abstraction - Merge and manage configuration data from different sources

VERSION

Version 0.37

SYNOPSIS

Config::Abstraction lets you load configuration from multiple sources, such as files, environment variables, and in-code defaults, and merge them with predictable precedence. It provides a consistent API for accessing the configuration settings, regardless of where they came from, this helps keep your application's or class's configuration flexible, centralized, and easy to override.

use Config::Abstraction;

my $config = Config::Abstraction->new(
  config_dirs => ['config'],
  env_prefix => 'APP_',
  flatten => 0,
);

my $db_user = $config->get('database.user');

DESCRIPTION

Config::Abstraction is a flexible configuration management layer that sits above Config::* modules. It provides a simple way to layer multiple configuration sources with predictable merge order. It lets you define sources such as:

Sources are applied in the order they are provided. Later sources override earlier ones unless a key is explicitly set to undef in the later source.

In addition to using drivers to load configuration data from multiple file formats (YAML, JSON, XML, and INI), it also allows levels of configuration, each of which overrides the lower levels. So, it also integrates environment variable overrides and command line arguments for runtime configuration adjustments. This module is designed to help developers manage layered configurations that can be loaded from files and overridden at run-time for debugging, offering a modern, robust and dynamic approach to configuration management.

Merge Precedence Diagram

+----------------+
|   CLI args     |  (Highest priority)
+----------------+
| Environment    |
+----------------+
| Config file(s) |
+----------------+
| Defaults       |  (Lowest priority)
+----------------+

KEY FEATURES

SUPPORTED FILE FORMATS

ENVIRONMENT VARIABLE HANDLING

Configuration values can be overridden via environment variables. Environment variables use double underscores (__) to denote nested configuration keys and single underscores remain as part of the key name under the prefix namespace.

For example:

APP_DATABASE__USER becomes database.user (nested structure)

  $ export APP_DATABASE__USER="env_user"

will override any value set for `database.user` in the configuration files.

APP_LOGLEVEL becomes APP.loglevel (flat under prefix namespace)

APP_API__RATE_LIMIT becomes api.rate_limit (mixed usage)

This allows you to override both top-level and nested configuration values using environment variables.

Configuration values can be overridden via the command line (@ARGV). For instance, if you have a key in the configuration such as database.user, you can override it by adding "--APP_DATABASE__USER=other_user_name" to the command line arguments. This will override any value set for database.user in the configuration files.

EXAMPLE CONFIGURATION FLOW

METHODS

new

Constructor for creating a new configuration object.

Options:

If just one argument is given, it is assumed to be the name of a file.

get(key)

Retrieve a configuration value using dotted key notation (e.g., 'database.user'). Returns undef if the key doesn't exist.

exists(key)

Does a configuration value using dotted key notation (e.g., 'database.user') exist? Returns 0 or 1.

all()

Returns the entire configuration hash, possibly flattened depending on the flatten option.

The entry config_path contains a list of the files that the configuration was loaded from.

merge_defaults

Merge the configuration hash into the given hash.

package MyPackage;
use Params::Get;
use Config::Abstraction;

sub new
{
  my $class = shift;

  my $params = Params::Get::get_params(undef, \@_) || {};

  if(my $config = Config::Abstraction->new(env_prefix => "${class}::")) {
    $params = $config->merge_defaults(defaults => $params, merge => 1, section => $class);
  }

  return bless $params, $class;
}

Options:

AUTOLOAD

This module supports dynamic access to configuration keys via AUTOLOAD. Nested keys are accessible using the separator, so $config->database_user() resolves to $config->{database}->{user}, when sep_char is set to '_'.

$config = Config::Abstraction->new(
    data => {
        database => {
            user => 'alice',
            pass => 'secret'
        },
        log_level => 'debug'
    },
    flatten => 1,
    sep_char => '_'
);

my $user = $config->database_user();        # returns 'alice'

# or
$user = $config->database()->{'user'};      # returns 'alice'

# Attempting to call a nonexistent key
my $foo = $config->nonexistent_key();       # dies with error

COMMON PITFALLS

BUGS

It should be possible to escape the separator character either with backslashes or quotes.

Due to the case-insensitive nature of environment variables on Windows, it may be challenging to override values using environment variables on that platform.

REPOSITORY

https://github.com/nigelhorne/Config-Abstraction

SUPPORT

This module is provided as-is without any warranty.

Please report any bugs or feature requests to bug-config-abstraction at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Config-Abstraction. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

You can find documentation for this module with the perldoc command.

perldoc Config::Abstraction

SEE ALSO

AUTHOR

Nigel Horne, <njh at nigelhorne.com>