.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Catalyst::Plugin::ConfigLoader::Manual 3pm"
.TH Catalyst::Plugin::ConfigLoader::Manual 3pm "2018-04-07" "perl v5.26.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Catalyst::Plugin::ConfigLoader::Manual \- Guide to using the ConfigLoader plugin
.SH "BASIC USAGE"
.IX Header "BASIC USAGE"
.Vb 1
\&    package MyApp;
\&    
\&    use Catalyst qw( ConfigLoader ... );
.Ve
.SH "ENVIRONMENT VARIABLES"
.IX Header "ENVIRONMENT VARIABLES"
.IP "\(bu" 4
\&\f(CW\*(C`MYAPP_CONFIG\*(C'\fR \- specific config file to load for \*(L"MyApp\*(R"
.IP "\(bu" 4
\&\f(CW\*(C`CATALYST_CONFIG_LOCAL_SUFFIX\*(C'\fR \- global suffix for extra config files
.IP "\(bu" 4
\&\f(CW\*(C`MYAPP_CONFIG_LOCAL_SUFFIX\*(C'\fR \- suffix specifically for \*(L"MyApp\*(R"
.SH "CONFIG FORMATS"
.IX Header "CONFIG FORMATS"
.SS "Config::General"
.IX Subsection "Config::General"
\fIExtensions\fR
.IX Subsection "Extensions"
.IP "\(bu" 4
cnf
.IP "\(bu" 4
conf
.PP
\fIExample Config\fR
.IX Subsection "Example Config"
.PP
.Vb 7
\&    name = TestApp
\&    <Component Controller::Foo>
\&        foo bar
\&    </Component>
\&    <Model Baz>
\&        qux xyzzy
\&    </Model>
.Ve
.SS "\s-1INI\s0"
.IX Subsection "INI"
\fIExtensions\fR
.IX Subsection "Extensions"
.IP "\(bu" 4
ini
.PP
\fIExample Config\fR
.IX Subsection "Example Config"
.PP
.Vb 1
\&    name=TestApp
\&    
\&    [Controller::Foo]
\&    foo=bar
\&    
\&    [Model::Baz]
\&    qux=xyzzy
.Ve
.SS "\s-1JSON\s0"
.IX Subsection "JSON"
\fIExtensions\fR
.IX Subsection "Extensions"
.IP "\(bu" 4
jsn
.IP "\(bu" 4
json
.PP
\fIExample Config\fR
.IX Subsection "Example Config"
.PP
.Vb 9
\&    {
\&        "name": "TestApp",
\&        "Controller::Foo": {
\&            "foo": "bar"
\&        },
\&        "Model::Baz": {
\&            "qux": "xyzzy"
\&        }
\&    }
.Ve
.SS "Perl"
.IX Subsection "Perl"
\fIExtensions\fR
.IX Subsection "Extensions"
.IP "\(bu" 4
pl
.IP "\(bu" 4
perl
.PP
\fIExample Config\fR
.IX Subsection "Example Config"
.PP
.Vb 9
\&    {
\&        name => \*(AqTestApp\*(Aq,
\&        \*(AqController::Foo\*(Aq => {
\&            foo => \*(Aqbar\*(Aq
\&        },
\&        \*(AqModel::Baz\*(Aq => {
\&            qux => \*(Aqxyzzy\*(Aq
\&        }
\&    }
.Ve
.SS "\s-1XML\s0"
.IX Subsection "XML"
\fIExtensions\fR
.IX Subsection "Extensions"
.IP "\(bu" 4
xml
.PP
\fIExample Config\fR
.IX Subsection "Example Config"
.PP
.Vb 10
\& <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>
.Ve
.PP
Note that the name attribute for the \f(CW\*(C`model\*(C'\fR tag should be the relative
namespace of the Catalyst model, not the absolute one.  That is for
\&\f(CW\*(C`MyApp::Model::Something\*(C'\fR the \f(CW\*(C`name\*(C'\fR attribute should be \f(CW\*(C`Something\*(C'\fR.
.SS "\s-1YAML\s0"
.IX Subsection "YAML"
\fIExtensions\fR
.IX Subsection "Extensions"
.IP "\(bu" 4
yml
.IP "\(bu" 4
yaml
.PP
\fIExample Config\fR
.IX Subsection "Example Config"
.PP
.Vb 6
\&    \-\-\-
\&    name: TestApp
\&    Controller::Foo:
\&        foo: bar
\&    Model::Baz:
\&        qux: xyzzy
.Ve
.SH "COOKBOOK"
.IX Header "COOKBOOK"
.SS "Configuring a Catalyst::Model::DBIC::Schema model from a \s-1YAML\s0 config"
.IX Subsection "Configuring a Catalyst::Model::DBIC::Schema model from a YAML config"
.Vb 7
\&    Model::MyModel:
\&      schema_class: MyApp::MySchema
\&      connect_info:
\&        \- dbi:SQLite:myapp.db
\&        \- \*(Aq\*(Aq
\&        \- \*(Aq\*(Aq
\&        \- AutoCommit: 1
.Ve
.SS "Converting your existing config to Config::General format"
.IX Subsection "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):
.PP
.Vb 1
\&    perl \-Ilib \-MMyApp \-MConfig::General \-e \*(AqConfig::General\->new\->save_file("myapp.conf", MyApp\->config);\*(Aq
.Ve
.SS "Using \s-1UTF\-8\s0 strings in a Config::General file"
.IX Subsection "Using UTF-8 strings in a Config::General file"
If you have \s-1UTF\-8\s0 strings in your Config::General\-based config file, you
should add the following config information to MyApp.pm:
.PP
.Vb 5
\&    _\|_PACKAGE_\|_\->config( \*(AqPlugin::ConfigLoader\*(Aq => {
\&        driver => {
\&            \*(AqGeneral\*(Aq => { \-UTF8 => 1 },
\&        }
\&    } );
.Ve
.SS "Using a local configuration file"
.IX Subsection "Using a local configuration file"
When ConfigLoader reads configurations, it starts by reading the configuration
file for \f(CW\*(C`myapp\*(C'\fR with one of the supported extensions as listed
above.
.PP
For example, A Config::General config file is \f(CW\*(C`myapp.conf\*(C'\fR.
.PP
If a configuration file called \f(CW\*(C`myapp_local\*(C'\fR 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.
.PP
A Config::General local configuration file would be called
\&\f(CW\*(C`myapp_local.conf\*(C'\fR.
.PP
The \f(CW\*(C`local\*(C'\fR suffix can be changed.  See
\&\*(L"get_config_local_suffix\*(R" in Catalyst::Plugin::ConfigLoader for the details of
how.
.PP
This is useful because it allows different people or environments to have
different configuration files.  A project with three developers,
\&\fITom\fR, \fIDick\fR, and \fIHarry\fR as well as a production environment can have
a \f(CW\*(C`myapp_tom.conf\*(C'\fR, a \f(CW\*(C`myapp_dick.conf\*(C'\fR, a \f(CW\*(C`myapp_harry.conf\*(C'\fR, and a
\&\f(CW\*(C`myapp_production.conf\*(C'\fR.
.PP
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.
.PP
If there is no \f(CW\*(C`myapp_local.ext\*(C'\fR (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.