NAME

       Catalyst::Plugin::ConfigLoader::Manual - Guide to using the ConfigLoader plugin

BASIC USAGE

           package MyApp;

           use Catalyst qw( ConfigLoader ... );

ENVIRONMENT VARIABLES

       •   "MYAPP_CONFIG" - specific config file to load for "MyApp"

       •   "CATALYST_CONFIG_LOCAL_SUFFIX" - global suffix for extra config files

       •   "MYAPP_CONFIG_LOCAL_SUFFIX" - suffix specifically for "MyApp"

CONFIG FORMATS

   Config::General
       Extensions

       •   cnf

       •   conf

       Example Config

           name = TestApp
           <Component Controller::Foo>
               foo bar
           </Component>
           <Model Baz>
               qux xyzzy
           </Model>

   INI
       Extensions

       •   ini

       Example Config

           name=TestApp

           [Controller::Foo]
           foo=bar

           [Model::Baz]
           qux=xyzzy

   JSON
       Extensions

       •   jsn

       •   json

       Example Config

           {
               "name": "TestApp",
               "Controller::Foo": {
                   "foo": "bar"
               },
               "Model::Baz": {
                   "qux": "xyzzy"
               }
           }

   Perl
       Extensions

       •   pl

       •   perl

       Example Config

           {
               name => 'TestApp',
               'Controller::Foo' => {
                   foo => 'bar'
               },
               'Model::Baz' => {
                   qux => 'xyzzy'
               }
           }

   XML
       Extensions

       •   xml

       Example Config

        <config>
               <name>MyApp::CMS</name>
               <paths>
                 <upload_dir>/var/www/docs/myapp-cms/uploads</upload_dir>
               </paths>
               <model name="DB">
                 <connect_info>dbi:mysql:cmsdb</connect_info>
                 <connect_info>user</connect_info>
                 <connect_info>password</connect_info>
               </model>
               <component name="View::TT">
                 <INCLUDE_PATH>__path_to(root,templates)__</INCLUDE_PATH>
                 <ENCODING>UTF-8</ENCODING>
                 <TRIM>1</TRIM>
                 <PRE_CHOMP>2</PRE_CHOMP>
                 <POST_CHOMP>2</POST_CHOMP>
               </component>

        </config>

       Note that the name attribute for the "model" tag should be the relative namespace of the
       Catalyst model, not the absolute one.  That is for "MyApp::Model::Something" the "name"
       attribute should be "Something".

   YAML
       Extensions

       •   yml

       •   yaml

       Example Config

           ---
           name: TestApp
           Controller::Foo:
               foo: bar
           Model::Baz:
               qux: xyzzy

COOKBOOK

   Configuring a Catalyst::Model::DBIC::Schema model from a YAML config
           Model::MyModel:
             schema_class: MyApp::MySchema
             connect_info:
               - dbi:SQLite:myapp.db
               - ''
               - ''
               - AutoCommit: 1

   Converting your existing config to Config::General format
       As of Catalyst::Devel 1.07, a newly created application will use Config::General for
       configuration. If you wish to convert your existing config, run the following one-liner
       (replacing MyApp with your app's name):

           perl -Ilib -MMyApp -MConfig::General -e 'Config::General->new->save_file("myapp.conf", MyApp->config);'

   Using UTF-8 strings in a Config::General file
       If you have UTF-8 strings in your Config::General-based config file, you should add the
       following config information to MyApp.pm:

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

   Using a local configuration file
       When ConfigLoader reads configurations, it starts by reading the configuration file for
       "myapp" with one of the supported extensions as listed above.

       For example, A Config::General config file is "myapp.conf".

       If a configuration file called "myapp_local" exists with one of the supported file
       extensions, it will also be read, and values from that file will override values from the
       main config file.

       A Config::General local configuration file would be called "myapp_local.conf".

       The "local" suffix can be changed.  See "get_config_local_suffix" in
       Catalyst::Plugin::ConfigLoader for the details of how.

       This is useful because it allows different people or environments to have different
       configuration files.  A project with three developers, Tom, Dick, and Harry as well as a
       production environment can have a "myapp_tom.conf", a "myapp_dick.conf", a
       "myapp_harry.conf", and a "myapp_production.conf".

       Each developer, and the web server, would set the environment variable to load their
       proper configuration file.  All of the configurations can be stored properly in source
       control.

       If there is no "myapp_local.ext" (where .ext is a supported extension), and the individual
       configuration files contain something required to start the application, such as the
       Model's data source definition, the applicaton won't start unless the environment variable
       is set properly.