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 | |
c61fb758 |
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> |
affbca23 |
137 | </model> |
c61fb758 |
138 | <component name="View::TT"> |
883b81a0 |
139 | <INCLUDE_PATH>__path_to(root,templates)__</INCLUDE_PATH> |
c61fb758 |
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>. |
affbca23 |
151 | |
152 | =head2 YAML |
153 | |
0365c42f |
154 | =head3 Extensions |
155 | |
156 | =over 4 |
157 | |
158 | =item * yml |
159 | |
160 | =item * yaml |
161 | |
162 | =back |
163 | |
164 | =head3 Example Config |
165 | |
affbca23 |
166 | --- |
167 | name: TestApp |
168 | Controller::Foo: |
169 | foo: bar |
170 | Model::Baz: |
171 | qux: xyzzy |
172 | |
b134c74a |
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 |
92e263ac |
179 | connect_info: |
b134c74a |
180 | - dbi:SQLite:myapp.db |
181 | - '' |
182 | - '' |
183 | - AutoCommit: 1 |
184 | |
ea561203 |
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 | |
e0d47620 |
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 | |
6a5c6f19 |
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 | |
ddb0ab25 |
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. |
6a5c6f19 |
237 | |
affbca23 |
238 | =cut |
b134c74a |
239 | |