lib/Catalyst/Plugin/ConfigLoader/Manual.pod

   1 =head1 NAME
   2
   3 Catalyst::Plugin::ConfigLoader::Manual - Guide to using the ConfigLoader plugin
   4
   5 =head1 BASIC USAGE
   6
   7     package MyApp;
   8
   9     use Catalyst qw( ConfigLoader ... );
  10
  11 =head1 ENVIRONMENT VARIABLES
  12
  13 =over 4
  14
  15 =item * C<MYAPP_CONFIG> - specific config file to load for "MyApp"
  16
  17 =item * C<CATALYST_CONFIG_LOCAL_SUFFIX> - global suffix for extra config files
  18
  19 =item * C<MYAPP_CONFIG_LOCAL_SUFFIX> - suffix specifically for "MyApp"
  20
  21 =back
  22
  23 =head1 CONFIG FORMATS
  24
  25 =head2 Config::General
  26
  27 =head3 Extensions
  28
  29 =over 4
  30
  31 =item * cnf
  32
  33 =item * conf
  34
  35 =back
  36
  37 =head3 Example Config
  38
  39     name = TestApp
  40     <Component Controller::Foo>
  41         foo bar
  42     </Component>
  43     <Model Baz>
  44         qux xyzzy
  45     </Model>
  46
  47 =head2 INI
  48
  49 =head3 Extensions
  50
  51 =over 4
  52
  53 =item * ini
  54
  55 =back
  56
  57 =head3 Example Config
  58
  59     name=TestApp
  60
  61     [Controller::Foo]
  62     foo=bar
  63
  64     [Model::Baz]
  65     qux=xyzzy
  66
  67 =head2 JSON
  68
  69 =head3 Extensions
  70
  71 =over 4
  72
  73 =item * jsn
  74
  75 =item * json
  76
  77 =back
  78
  79 =head3 Example Config
  80
  81     {
  82         "name": "TestApp",
  83         "Controller::Foo": {
  84             "foo": "bar"
  85         },
  86         "Model::Baz": {
  87             "qux": "xyzzy"
  88         }
  89     }
  90
  91 =head2 Perl
  92
  93 =head3 Extensions
  94
  95 =over 4
  96
  97 =item * pl
  98
  99 =item * perl
 100
 101 =back
 102
 103 =head3 Example Config
 104
 105     {
 106         name => 'TestApp',
 107         'Controller::Foo' => {
 108             foo => 'bar'
 109         },
 110         'Model::Baz' => {
 111             qux => 'xyzzy'
 112         }
 113     }
 114
 115 =head2 XML
 116
 117 =head3 Extensions
 118
 119 =over 4
 120
 121 =item * xml
 122
 123 =back
 124
 125 =head3 Example Config
 126
 127     <config>
 128         <name>MyApp::CMS</name>
 129         <paths>
 130             <upload_dir>/var/www/docs/myapp-cms/uploads</upload_dir>
 131         </paths>
 132         <model name="DB">
 133             <connect_info>dbi:mysql:cmsdb</connect_info>
 134             <connect_info>user</connect_info>
 135             <connect_info>password</connect_info>
 136         </model>
 137         <component name="View::TT">
 138             <INCLUDE_PATH>__path_to(root,templates)__</INCLUDE_PATH>
 139             <ENCODING>UTF-8</ENCODING>
 140             <TRIM>1</TRIM>
 141             <PRE_CHOMP>2</PRE_CHOMP>
 142             <POST_CHOMP>2</POST_CHOMP>
 143         </component>
 144     </config>
 145
 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>.
 149
 150 =head2 YAML
 151
 152 =head3 Extensions
 153
 154 =over 4
 155
 156 =item * yml
 157
 158 =item * yaml
 159
 160 =back
 161
 162 =head3 Example Config
 163
 164     ---
 165     name: TestApp
 166     Controller::Foo:
 167         foo: bar
 168     Model::Baz:
 169         qux: xyzzy
 170
 171 =head1 COOKBOOK
 172
 173 =head2 Configuring a Catalyst::Model::DBIC::Schema model from a YAML config
 174
 175     Model::MyModel:
 176         schema_class: MyApp::MySchema
 177         connect_info:
 178             - dbi:SQLite:myapp.db
 179             - ''
 180             - ''
 181             - AutoCommit: 1
 182
 183 =head2 Converting your existing config to Config::General format
 184
 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):
 188
 189     perl -Ilib -MMyApp -MConfig::General -e 'Config::General->new->save_file("myapp.conf", MyApp->config);'
 190
 191 =head2 Using UTF-8 strings in a Config::General file
 192
 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:
 195
 196     __PACKAGE__->config( 'Plugin::ConfigLoader' => {
 197         driver => {
 198             'General' => { -UTF8 => 1 },
 199         }
 200     } );
 201
 202 =head2 Using a local configuration file
 203
 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>.
 207
 208 For example, A L<Config::General> config file is F<myapp.conf>.
 209
 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.
 213
 214 A L<Config::General> local configuration file would be called
 215 F<myapp_local.conf>.
 216
 217 The C<local> suffix can be changed.  See
 218 L<Catalyst::Plugin::ConfigLoader/get_config_local_suffix> for the details of
 219 how.
 220
 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>.
 226
 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.
 230
 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.
 235
 236 =cut