3 Catalyst::Plugin::ConfigLoader::Manual - Guide to using the ConfigLoader plugin
9 use Catalyst qw( ConfigLoader ... );
11 =head1 ENVIRONMENT VARIABLES
15 =item * C<MYAPP_CONFIG> - specific config file to load for "MyApp"
17 =item * C<CATALYST_CONFIG_LOCAL_SUFFIX> - global suffix for extra config files
19 =item * C<MYAPP_CONFIG_LOCAL_SUFFIX> - suffix specifically for "MyApp"
25 =head2 Config::General
40 <Component Controller::Foo>
103 =head3 Example Config
107 'Controller::Foo' => {
125 =head3 Example Config
128 <name>MyApp::CMS</name>
130 <upload_dir>/var/www/docs/myapp-cms/uploads</upload_dir>
133 <connect_info>dbi:mysql:cmsdb</connect_info>
134 <connect_info>user</connect_info>
135 <connect_info>password</connect_info>
137 <component name="View::TT">
138 <INCLUDE_PATH>__path_to(root,templates)__</INCLUDE_PATH>
139 <ENCODING>UTF-8</ENCODING>
141 <PRE_CHOMP>2</PRE_CHOMP>
142 <POST_CHOMP>2</POST_CHOMP>
146 Note that the name attribute for the C<model> tag should be the relative
147 namespace of the Catalyst model, not the absolute one. That is for
148 C<MyApp::Model::Something> the C<name> attribute should be C<Something>.
162 =head3 Example Config
173 =head2 Configuring a Catalyst::Model::DBIC::Schema model from a YAML config
176 schema_class: MyApp::MySchema
178 - dbi:SQLite:myapp.db
183 =head2 Converting your existing config to Config::General format
185 As of L<Catalyst::Devel> 1.07, a newly created application will use
186 L<Config::General> for configuration. If you wish to convert your existing
187 config, run the following one-liner (replacing MyApp with your app's name):
189 perl -Ilib -MMyApp -MConfig::General -e 'Config::General->new->save_file("myapp.conf", MyApp->config);'
191 =head2 Using UTF-8 strings in a Config::General file
193 If you have UTF-8 strings in your L<Config::General>-based config file, you
194 should add the following config information to MyApp.pm:
196 __PACKAGE__->config( 'Plugin::ConfigLoader' => {
198 'General' => { -UTF8 => 1 },
202 =head2 Using a local configuration file
204 When ConfigLoader reads configurations, it starts by reading the configuration
205 file for C<myapp> with one of the supported extensions as listed
206 L<above|/CONFIG FORMATS>.
208 For example, A L<Config::General> config file is F<myapp.conf>.
210 If a configuration file called C<myapp_local> exists with one of the supported
211 file extensions, it will also be read, and values from that file will
212 override values from the main config file.
214 A L<Config::General> local configuration file would be called
217 The C<local> suffix can be changed. See
218 L<Catalyst::Plugin::ConfigLoader/get_config_local_suffix> for the details of
221 This is useful because it allows different people or environments to have
222 different configuration files. A project with three developers,
223 I<Tom>, I<Dick>, and I<Harry> as well as a production environment can have
224 a F<myapp_tom.conf>, a F<myapp_dick.conf>, a F<myapp_harry.conf>, and a
225 F<myapp_production.conf>.
227 Each developer, and the web server, would set the environment variable
228 to load their proper configuration file. All of the configurations can
229 be stored properly in source control.
231 If there is no F<myapp_local.ext> (where C<.ext> is a supported extension), and
232 the individual configuration files contain something required to start the
233 application, such as the Model's data source definition, the applicaton won't
234 start unless the environment variable is set properly.