=head1 Configuration layouts

A common use case is the need to parametrize an application's config
in a way that includes your credentials and the environment's data
(for example: db host/port, use of frontend proxy or not, caching,
require-ssl, etc). This is simple to achieve until your project starts
getting bigger.

=head2 Catalyst::Plugin::ConfigLoader

The ConfigLoader plugin gives you the chance to load the config by
using its suffix. This approach which will look for a local config
file, if specified, in the following order of preference:

=over

=item * C<$ENV{ MYAPP_CONFIG_LOCAL_SUFFIX }>

=item * C<$ENV{ CATALYST_CONFIG_LOCAL_SUFFIX }>

=item * C<$c-E<gt>config-E<gt>{ 'Plugin::ConfigLoader' }-E<gt>{ config_local_suffix }>

=back

By default the suffix value is C<local>, which will load
C<myapp_local.conf>. If, for example, C<$ENV{
MYAPP_CONFIG_LOCAL_SUFFIX }> is set to C<testing>, ConfigLoader will
try to load C<myapp_testing.conf> instead of C<myapp_local.conf>.

Or you could even load local files for each config set directly from
your main file:

    # load db config file, in Config::General format
    <Model::Database>
        schema_class My::Schema
        <connect_info>
            <<include conf/db_local.conf>>
        </connect_info>
    </Model::Database>

Both of these approaches get in your way when you have X number of
applications with Y number of developers and Z number of boxes for
each environment (development, testing, staging and production).

=head2 MyCompany::Plugin::ConfigLoader

So, all you need to do is extend the C<get_config_local_suffix> method
from ConfigLoad plugin and implement your own config file loading
logic.


For example:

    package MyCompany::Plugin::ConfigLoader;

    use strict;
    use warnings;
    use parent 'Catalyst::Plugin::ConfigLoader';

    use Catalyst::Utils ();
    use Sys::Hostname();

    sub get_config_local_suffix {
        my ($c) = @_;
        my $username = $ENV{USER} || getpwuid($<);
        my ($hostname) = Sys::Hostname::hostname() =~ m/^([^\.]+)/;
        my $env_suffix = Catalyst::Utils::env_value($c, 'CONFIG_ENV_SUFFIX');
        my $config_local_suffix =
            Catalyst::Utils::env_value($c, 'CONFIG_LOCAL_SUFFIX')
            || join('_', grep { $_ } ($username, $hostname, $env_suffix));
        return $config_local_suffix;
    }

    1;

Then, in your app class

    use Catalyst qw/+MyCompany::Plugin::ConfigLoader/;

    # ...

    __PACKAGE__->config( 'Plugin::ConfigLoader' => { file => __PACKAGE__->path_to('conf') } );

This loads a config file under C<conf> directory in your application's
homedir based on current sysuser and hostname
(e.g. myapp_wreis_hercule.conf).  You can even set the
C<CONFIG_ENV_SUFFIX> environment variable, and it would be appended to
the config local suffix (e.g. myapp_wreis_hercule_staging.conf).

Remember that you can load a specific config file at any time by
setting MYAPP_CONFIG=/path/to/config/file or CATALYST_CONFIG
environment variable.

=head1 SEE ALSO
	
L<Catalyst Advent Calendar 2007-15|http://www.catalystframework.org/calendar/2007/15>,
L<Catalyst Advent Calendar 2008-10|http://www.catalystframework.org/calendar/2008/10>, 
L<Catalyst::Plugin::ConfigLoader::Multi>.

=head1 AUTHOR

wreis: Wallace Reis | <w.reis@shadowcat.co.uk>