Commit | Line | Data |
587d381b |
1 | |
affbca23 |
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 | |
bc40ee17 |
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 | |
affbca23 |
24 | =head1 CONFIG FORMATS |
25 | |
26 | =head2 Config::General |
27 | |
0365c42f |
28 | =head3 Extensions |
29 | |
30 | =over 4 |
31 | |
32 | =item * cnf |
33 | |
34 | =item * conf |
35 | |
36 | =back |
37 | |
38 | =head3 Example Config |
39 | |
affbca23 |
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 | |
0365c42f |
50 | =head3 Extensions |
51 | |
52 | =over 4 |
53 | |
54 | =item * ini |
55 | |
56 | =back |
57 | |
58 | =head3 Example Config |
59 | |
affbca23 |
60 | name=TestApp |
61 | |
62 | [Controller::Foo] |
63 | foo=bar |
64 | |
65 | [Model::Baz] |
66 | qux=xyzzy |
67 | |
68 | =head2 JSON |
69 | |
0365c42f |
70 | =head3 Extensions |
71 | |
72 | =over 4 |
73 | |
74 | =item * jsn |
75 | |
76 | =item * json |
77 | |
78 | =back |
79 | |
80 | =head3 Example Config |
81 | |
affbca23 |
82 | { |
83 | "name": "TestApp", |
84 | "Controller::Foo": { |
85 | "foo": "bar" |
86 | }, |
87 | "Model::Baz": { |
88 | "qux": "xyzzy" |
89 | } |
90 | } |
91 | |
92 | =head2 Perl |
93 | |
0365c42f |
94 | =head3 Extensions |
95 | |
96 | =over 4 |
97 | |
98 | =item * pl |
99 | |
100 | =item * perl |
101 | |
102 | =back |
103 | |
104 | =head3 Example Config |
105 | |
affbca23 |
106 | { |
107 | name => 'TestApp', |
108 | 'Controller::Foo' => { |
109 | foo => 'bar' |
110 | }, |
111 | 'Model::Baz' => { |
112 | qux => 'xyzzy' |
113 | } |
114 | } |
115 | |
116 | =head2 XML |
117 | |
0365c42f |
118 | =head3 Extensions |
119 | |
120 | =over 4 |
121 | |
122 | =item * xml |
123 | |
124 | =back |
125 | |
126 | =head3 Example Config |
127 | |
affbca23 |
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 | |
0365c42f |
140 | =head3 Extensions |
141 | |
142 | =over 4 |
143 | |
144 | =item * yml |
145 | |
146 | =item * yaml |
147 | |
148 | =back |
149 | |
150 | =head3 Example Config |
151 | |
affbca23 |
152 | --- |
153 | name: TestApp |
154 | Controller::Foo: |
155 | foo: bar |
156 | Model::Baz: |
157 | qux: xyzzy |
158 | |
b134c74a |
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 |
92e263ac |
165 | connect_info: |
b134c74a |
166 | - dbi:SQLite:myapp.db |
167 | - '' |
168 | - '' |
169 | - AutoCommit: 1 |
170 | |
ea561203 |
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 | |
e0d47620 |
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 | |
6a5c6f19 |
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>, and the individual configuration files contain |
220 | something required to start the application, such as the Model's data source |
221 | definition, the applicaton won't start unless the environment variable |
222 | is set properly. |
223 | |
affbca23 |
224 | =cut |
b134c74a |
225 | |