4 Catalyst::Plugin::ConfigLoader::Manual - Guide to using the ConfigLoader plugin
10 use Catalyst qw( ConfigLoader ... );
12 =head1 ENVIRONMENT VARIABLES
16 =item * C<MYAPP_CONFIG> - specific config file to load for "MyApp"
18 =item * C<CATALYST_CONFIG_LOCAL_SUFFIX> - global suffix for extra config files
20 =item * C<MYAPP_CONFIG_LOCAL_SUFFIX> - suffix specifically for "MyApp"
26 =head2 Config::General
41 <Component Controller::Foo>
104 =head3 Example Config
108 'Controller::Foo' => {
126 =head3 Example Config
130 <component name="Controller::Foo">
150 =head3 Example Config
161 =head2 Configuring a Catalyst::Model::DBIC::Schema model from a YAML config
164 schema_class: MyApp::MySchema
166 - dbi:SQLite:myapp.db
171 =head2 Converting your existing config to Config::General format
173 As of L<Catalyst::Devel> 1.07, a newly created application will use
174 L<Config::General> for configuration. If you wish to convert your existing
175 config, run the following one-liner (replacing MyApp with your app's name):
177 perl -Ilib -MMyApp -MConfig::General -e 'Config::General->new->save_file("myapp.conf", MyApp->config);'
179 =head2 Using UTF-8 strings in a Config::General file
181 If you have UTF-8 strings in your L<Config::General>-based config file, you
182 should add the following config information to MyApp.pm:
184 __PACKAGE__->config( 'Plugin::ConfigLoader' => {
186 'General' => { -UTF8 => 1 },
190 =head2 Using a local configuration file
192 When ConfigLoader reads configurations, it starts by reading the configuration
193 file for C<myapp> with one of the supported extensions as listed
194 L<above|/Config Formats>.
196 For example, A L<Config::General> config file is C<myapp.conf>.
198 If a configuration file called C<myapp_local> exists with one of the supported
199 file extensions, it will also be read, and values from that file will
200 override values from the main config file.
202 A L<Config::General> local configuration file would be called
205 The C<local> suffix can be changed. See
206 L<Catalyst::Plugin::ConfigLoader/get_config_local_suffix> for the details of
209 This is useful because it allows different people or environments to have
210 different configuration files. A project with three developers,
211 I<Tom>, I<Dick>, and I<Harry> as well as a production environment can have
212 a C<myapp_tom.conf>, a C<myapp_dick.conf>, a C<myapp_harry.conf>, and a
213 C<myapp_production.conf>.
215 Each developer, and the web server, would set the environment variable
216 to load their proper configuration file. All of the configurations can
217 be stored properly in source control.
219 If there is no C<myapp.local>, and the individual configuration files contain
220 something required to start the application, such as the Model's data source
221 definition, the applicaton won't start unless the environment variable