Cataly...Loader(3pm)

💖 Catalyst::Plugin::ConfigLoader — the config-loading bestie 💖

okay so bestie, this is Catalyst::Plugin::ConfigLoader (a 3pm page, perl vibes) and it's literally the plugin that goes and finds your config file so you don't have to hardcode anything. she's giving "load config files of various types" and honestly? iconic. 🎀

---

✨ NAME ✨

Catalyst::Plugin::ConfigLoader — Load config files of various types 🦋

---

✨ SYNOPSIS ✨

package MyApp;

# ConfigLoader should be first in your list so
# other plugins can get the config information
use Catalyst qw( ConfigLoader ... );

# by default myapp.* will be loaded
# you can specify a file if you'd like
__PACKAGE__->config( 'Plugin::ConfigLoader' => { file => 'config.yaml' } );

Then in the file itself, assuming it's in YAML format:

foo: bar

And you can grab it through the context object, or through the class itself, whichever hits different for you:

$c->config->{foo}    # bar
MyApp->config->{foo} # bar

---

✨ DESCRIPTION ✨

so this module will try to find and load a config file, and it handles various types. right now it supports YAML, JSON, XML, INI and Perl formats. periodt. 💅

If you've got special configuration you wanna hand to one particular driver format, you stash it in MyApp->config->{ 'Plugin::ConfigLoader' }->{ driver }. for example, to pass args to Config::General, you do this:

__PACKAGE__->config( 'Plugin::ConfigLoader' => {
    driver => {
        'General' => { -LowerCaseNames => 1 }
    }
} );

see Config::Any's driver_args parameter for more info, iykyk. 📚

And because we need to tell dev and production apart (main character energy for both environments, honestly), this module will also attempt to load a local config — like myapp_local.yaml — which overrides any duplicate settings. 🌸 how is that configured, you ask? see get_config_local_suffix. she explains everything.

---

✨ METHODS ✨

🌈 setup( )

Catalyst's setup routine calls this automatically, no need to do anything. it'll try to use each plugin and, once a file has been successfully loaded, it sets the config() section. slay. ✅

🌈 load_config

this one handles loading the configuration data into the Catalyst context object. ngl it does not return a value. it's just out here doing the work. 💪

🌈 find_files

this method figures out the potential file paths to use for config loading. it returns an array of paths (up to the filename less the extension) to pass to Config::Any for loading. 🔍

🌈 get_config_path

this one determines the path, the filename prefix, and the file extension to use for config loading. it returns the path (up to the filename less the extension) to check, plus the specific extension to use (if one was specified). ✨

the order of preference is, in this exact order:

• $ENV{ MYAPP_CONFIG }
• $ENV{ CATALYST_CONFIG }
• "$c->config->{ 'Plugin::ConfigLoader' }->{ file }"
• "$c->path_to( $application_prefix )"

if either of the first two user-specified options are directories, the application prefix gets added on to the end of the path. don't forget bestie 🫶

🌈 get_config_local_suffix

this determines the suffix of the files used to override the main config. by default that value is local, which will load myapp_local.conf. 🎀

the suffix can be specified in this order of preference:

• $ENV{ MYAPP_CONFIG_LOCAL_SUFFIX }
• $ENV{ CATALYST_CONFIG_LOCAL_SUFFIX }
• "$c->config->{ 'Plugin::ConfigLoader' }->{ config_local_suffix }"

the first one of these values that's found replaces the default of local in the name of the local config file that gets loaded. 👑

for example, if $ENV{ MYAPP_CONFIG_LOCAL_SUFFIX } is set to testing, ConfigLoader will try and load myapp_testing.conf instead of myapp_local.conf. literally that easy. 🦋

🌈 finalize_config

this method gets called after the config file is loaded. it's your moment to implement tuning of config values that can only be done at runtime. if you need to do this to properly configure any plugins, it's important to load ConfigLoader before them — order matters, bestie, no cap. ⚠️

ConfigLoader provides a default finalize_config method which walks through the loaded config hash and calls the config_substitutions method on any string. 🌸

🌈 config_substitutions( $value )

this method substitutes macros found with calls to a function. there are a number of default macros, and they're all kinda iconic:

• "__HOME__" — replaced with "$c->path_to('')"
• "__ENV(foo)__" — replaced with the value of $ENV{foo}
• "__path_to(foo/bar)__" — replaced with "$c->path_to('foo/bar')"
• "__literal(__FOO__)__" — leaves __FOO__ alone (this lets you use "__DATA__" as a config value, for example) 💜

the parameter list is split on comma (,). you can override this method to do your own string munging, or you can define your own macros in MyApp->config->{ 'Plugin::ConfigLoader' }->{ substitutions }. example:

MyApp->config->{ 'Plugin::ConfigLoader' }->{ substitutions } = {
    baz => sub { my $c = shift; qux( @_ ); }
}

the above will respond to "__baz(x,y)__" in config strings. your config, your rules. 💅

---

✨ AUTHOR ✨

Brian Cassidy <bricas@cpan.org> 👑

---

✨ CONTRIBUTORS ✨

these people generously donated their time to the development of this module, and we love them for it:

• Joel Bernstein <rataxis@cpan.org> — Rewrite to use Config::Any
• David Kamholz <dkamholz@cpan.org> — Data::Visitor integration
• Stuart Watt — Addition of ENV macro.

work to this module has been generously sponsored by:

• Portugal Telecom <http://www.sapo.pt/> — Work done by Joel Bernstein

---

✨ COPYRIGHT AND LICENSE ✨

Copyright 2006-2010 by Brian Cassidy

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. 🌈

---

✨ SEE ALSO ✨

• Catalyst
• Catalyst::Plugin::ConfigLoader::Manual
• Config::Any

---

and that's the whole page bestie!! 💖 this one was perl v5.30.3, dated 2020-07-30, and she ATE. go configure something cute. 🎀✨🦋