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>MyApp::CMS</name>
 130         <paths>
 131           <upload_dir>/var/www/docs/myapp-cms/uploads</upload_dir>
 132         </paths>
 133         <model name="DB">
 134           <connect_info>dbi:mysql:cmsdb</connect_info>
 135           <connect_info>user</connect_info>
 136           <connect_info>password</connect_info>
 137         </model>
 138         <component name="View::TT">
 139           <INCLUDE_PATH>__path_to(root,templates)__</INCLUDE_PATH>
 140           <ENCODING>UTF-8</ENCODING>
 141           <TRIM>1</TRIM>
 142           <PRE_CHOMP>2</PRE_CHOMP>
 143           <POST_CHOMP>2</POST_CHOMP>
 144         </component>
 145
 146  </config>
 147
 148 Note that the name attribute for the C<model> tag should be the relative
 149 namespace of the Catalyst model, not the absolute one.  That is for
 150 C<MyApp::Model::Something> the C<name> attribute should be C<Something>.
 151
 152 =head2 YAML
 153
 154 =head3 Extensions
 155
 156 =over 4
 157
 158 =item * yml
 159
 160 =item * yaml
 161
 162 =back
 163
 164 =head3 Example Config
 165
 166     ---
 167     name: TestApp
 168     Controller::Foo:
 169         foo: bar
 170     Model::Baz:
 171         qux: xyzzy
 172
 173 =head1 COOKBOOK
 174
 175 =head2 Configuring a Catalyst::Model::DBIC::Schema model from a YAML config
 176
 177     Model::MyModel:
 178       schema_class: MyApp::MySchema
 179       connect_info:
 180         - dbi:SQLite:myapp.db
 181         - ''
 182         - ''
 183         - AutoCommit: 1
 184
 185 =head2 Converting your existing config to Config::General format
 186
 187 As of L<Catalyst::Devel> 1.07, a newly created application will use
 188 L<Config::General> for configuration. If you wish to convert your existing
 189 config, run the following one-liner (replacing MyApp with your app's name):
 190
 191     perl -Ilib -MMyApp -MConfig::General -e 'Config::General->new->save_file("myapp.conf", MyApp->config);'
 192
 193 =head2 Using UTF-8 strings in a Config::General file
 194
 195 If you have UTF-8 strings in your L<Config::General>-based config file, you
 196 should add the following config information to MyApp.pm:
 197
 198     __PACKAGE__->config( 'Plugin::ConfigLoader' => {
 199         driver => {
 200             'General' => { -UTF8 => 1 },
 201         }
 202     } );
 203
 204 =head2 Using a local configuration file
 205
 206 When ConfigLoader reads configurations, it starts by reading the configuration
 207 file for C<myapp> with one of the supported extensions as listed
 208 L<above|/Config Formats>.
 209
 210 For example, A L<Config::General> config file is C<myapp.conf>.
 211
 212 If a configuration file called C<myapp_local> exists with one of the supported
 213 file extensions, it will also be read, and values from that file will
 214 override values from the main config file.
 215
 216 A L<Config::General> local configuration file would be called
 217 C<myapp_local.conf>.
 218
 219 The C<local> suffix can be changed.  See
 220 L<Catalyst::Plugin::ConfigLoader/get_config_local_suffix> for the details of
 221 how.
 222
 223 This is useful because it allows different people or environments to have
 224 different configuration files.  A project with three developers,
 225 I<Tom>, I<Dick>, and I<Harry> as well as a production environment can have
 226 a C<myapp_tom.conf>, a C<myapp_dick.conf>, a C<myapp_harry.conf>, and a
 227 C<myapp_production.conf>.
 228
 229 Each developer, and the web server, would set the environment variable
 230 to load their proper configuration file.  All of the configurations can
 231 be stored properly in source control.
 232
 233 If there is no C<myapp_local.ext> (where .ext is a supported extension), and
 234 the individual configuration files contain something required to start the
 235 application, such as the Model's data source definition, the applicaton won't
 236 start unless the environment variable is set properly.
 237
 238 =cut
 239