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 =cut
 191