lib/Catalyst/Plugin/ConfigLoader/Manual.pod

   1
   2 =head1 NAME
   3
   4 Catalyst::Plugin::ConfigLoader::Manual - Guide to using the ConfigLoader plugin
   5
   6 =head1 BASIC USAGE
   7
   8     package MyApp;
   9
  10     use Catalyst qw( ConfigLoader ... );
  11
  12 =head1 ENVIRONMENT VARIABLES
  13
  14 =over 4
  15
  16 =item * C<MYAPP_CONFIG> - specific config file to load for "MyApp"
  17
  18 =item * C<CATALYST_CONFIG_LOCAL_SUFFIX> - global suffix for extra config files
  19
  20 =item * C<MYAPP_CONFIG_LOCAL_SUFFIX> - suffix specifically for "MyApp"
  21
  22 =back
  23
  24 =head1 CONFIG FORMATS
  25
  26 =head2 Config::General
  27
  28 =head3 Extensions
  29
  30 =over 4
  31
  32 =item * cnf
  33
  34 =item * conf
  35
  36 =back
  37
  38 =head3 Example Config
  39
  40     name = TestApp
  41     <Component Controller::Foo>
  42         foo bar
  43     </Component>
  44     <Model Baz>
  45         qux xyzzy
  46     </Model>
  47
  48 =head2 INI
  49
  50 =head3 Extensions
  51
  52 =over 4
  53
  54 =item * ini
  55
  56 =back
  57
  58 =head3 Example Config
  59
  60     name=TestApp
  61
  62     [Controller::Foo]
  63     foo=bar
  64
  65     [Model::Baz]
  66     qux=xyzzy
  67
  68 =head2 JSON
  69
  70 =head3 Extensions
  71
  72 =over 4
  73
  74 =item * jsn
  75
  76 =item * json
  77
  78 =back
  79
  80 =head3 Example Config
  81
  82     {
  83         "name": "TestApp",
  84         "Controller::Foo": {
  85             "foo": "bar"
  86         },
  87         "Model::Baz": {
  88             "qux": "xyzzy"
  89         }
  90     }
  91
  92 =head2 Perl
  93
  94 =head3 Extensions
  95
  96 =over 4
  97
  98 =item * pl
  99
 100 =item * perl
 101
 102 =back
 103
 104 =head3 Example Config
 105
 106     {
 107         name => 'TestApp',
 108         'Controller::Foo' => {
 109             foo => 'bar'
 110         },
 111         'Model::Baz' => {
 112             qux => 'xyzzy'
 113         }
 114     }
 115
 116 =head2 XML
 117
 118 =head3 Extensions
 119
 120 =over 4
 121
 122 =item * xml
 123
 124 =back
 125
 126 =head3 Example Config
 127
 128     <config>
 129         <name>TestApp</name>
 130         <component name="Controller::Foo">
 131             <foo>bar</foo>
 132         </component>
 133         <model name="Baz">
 134             <qux>xyzzy</qux>
 135         </model>
 136     </config>
 137
 138 =head2 YAML
 139
 140 =head3 Extensions
 141
 142 =over 4
 143
 144 =item * yml
 145
 146 =item * yaml
 147
 148 =back
 149
 150 =head3 Example Config
 151
 152     ---
 153     name: TestApp
 154     Controller::Foo:
 155         foo: bar
 156     Model::Baz:
 157         qux: xyzzy
 158
 159 =head1 COOKBOOK
 160
 161 =head2 Configuring a Catalyst::Model::DBIC::Schema model from a YAML config
 162
 163     Model::MyModel:
 164       schema_class: MyApp::MySchema
 165       connect_info:
 166         - dbi:SQLite:myapp.db
 167         - ''
 168         - ''
 169         - AutoCommit: 1
 170
 171 =head2 Converting your existing config to Config::General format
 172
 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):
 176
 177     perl -Ilib -MMyApp -MConfig::General -e 'Config::General->new->save_file("myapp.conf", MyApp->config);'
 178
 179 =head2 Using UTF-8 strings in a Config::General file
 180
 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:
 183
 184     __PACKAGE__->config( 'Plugin::ConfigLoader' => {
 185         driver => {
 186             'General' => { -UTF8 => 1 },
 187         }
 188     } );
 189
 190 =head2 Using a local configuration file
 191
 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>.
 195
 196 For example, A L<Config::General> config file is C<myapp.conf>.
 197
 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.
 201
 202 A L<Config::General> local configuration file would be called
 203 C<myapp_local.conf>.
 204
 205 The C<local> suffix can be changed.  See
 206 L<Catalyst::Plugin::ConfigLoader/get_config_local_suffix> for the details of
 207 how.
 208
 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>.
 214
 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.
 218
 219 If there is no C<myapp_local.ext> (where .ext is a supported extension), and
 220 the individual configuration files contain something required to start the
 221 application, such as the Model's data source definition, the applicaton won't
 222 start unless the environment variable is set properly.
 223
 224 =cut
 225