Commit | Line | Data |
affbca23 |
1 | =head1 NAME |
2 | |
3 | Catalyst::Plugin::ConfigLoader::Manual - Guide to using the ConfigLoader plugin |
4 | |
5 | =head1 BASIC USAGE |
6 | |
7 | package MyApp; |
ff1f7cb0 |
8 | |
affbca23 |
9 | use Catalyst qw( ConfigLoader ... ); |
10 | |
bc40ee17 |
11 | =head1 ENVIRONMENT VARIABLES |
12 | |
13 | =over 4 |
14 | |
15 | =item * C<MYAPP_CONFIG> - specific config file to load for "MyApp" |
16 | |
17 | =item * C<CATALYST_CONFIG_LOCAL_SUFFIX> - global suffix for extra config files |
18 | |
19 | =item * C<MYAPP_CONFIG_LOCAL_SUFFIX> - suffix specifically for "MyApp" |
20 | |
21 | =back |
22 | |
affbca23 |
23 | =head1 CONFIG FORMATS |
24 | |
25 | =head2 Config::General |
26 | |
0365c42f |
27 | =head3 Extensions |
28 | |
29 | =over 4 |
30 | |
31 | =item * cnf |
32 | |
33 | =item * conf |
34 | |
35 | =back |
36 | |
37 | =head3 Example Config |
38 | |
affbca23 |
39 | name = TestApp |
40 | <Component Controller::Foo> |
41 | foo bar |
42 | </Component> |
43 | <Model Baz> |
44 | qux xyzzy |
45 | </Model> |
46 | |
47 | =head2 INI |
48 | |
0365c42f |
49 | =head3 Extensions |
50 | |
51 | =over 4 |
52 | |
53 | =item * ini |
54 | |
55 | =back |
56 | |
57 | =head3 Example Config |
58 | |
affbca23 |
59 | name=TestApp |
ff1f7cb0 |
60 | |
affbca23 |
61 | [Controller::Foo] |
62 | foo=bar |
ff1f7cb0 |
63 | |
affbca23 |
64 | [Model::Baz] |
65 | qux=xyzzy |
66 | |
67 | =head2 JSON |
68 | |
0365c42f |
69 | =head3 Extensions |
70 | |
71 | =over 4 |
72 | |
73 | =item * jsn |
74 | |
75 | =item * json |
76 | |
77 | =back |
78 | |
79 | =head3 Example Config |
80 | |
affbca23 |
81 | { |
82 | "name": "TestApp", |
83 | "Controller::Foo": { |
84 | "foo": "bar" |
85 | }, |
86 | "Model::Baz": { |
87 | "qux": "xyzzy" |
88 | } |
89 | } |
90 | |
91 | =head2 Perl |
92 | |
0365c42f |
93 | =head3 Extensions |
94 | |
95 | =over 4 |
96 | |
97 | =item * pl |
98 | |
99 | =item * perl |
100 | |
101 | =back |
102 | |
103 | =head3 Example Config |
104 | |
affbca23 |
105 | { |
106 | name => 'TestApp', |
107 | 'Controller::Foo' => { |
108 | foo => 'bar' |
109 | }, |
110 | 'Model::Baz' => { |
111 | qux => 'xyzzy' |
112 | } |
113 | } |
114 | |
115 | =head2 XML |
116 | |
0365c42f |
117 | =head3 Extensions |
118 | |
119 | =over 4 |
120 | |
121 | =item * xml |
122 | |
123 | =back |
124 | |
125 | =head3 Example Config |
126 | |
ff1f7cb0 |
127 | <config> |
c61fb758 |
128 | <name>MyApp::CMS</name> |
129 | <paths> |
ff1f7cb0 |
130 | <upload_dir>/var/www/docs/myapp-cms/uploads</upload_dir> |
c61fb758 |
131 | </paths> |
132 | <model name="DB"> |
ff1f7cb0 |
133 | <connect_info>dbi:mysql:cmsdb</connect_info> |
134 | <connect_info>user</connect_info> |
135 | <connect_info>password</connect_info> |
affbca23 |
136 | </model> |
c61fb758 |
137 | <component name="View::TT"> |
ff1f7cb0 |
138 | <INCLUDE_PATH>__path_to(root,templates)__</INCLUDE_PATH> |
139 | <ENCODING>UTF-8</ENCODING> |
140 | <TRIM>1</TRIM> |
141 | <PRE_CHOMP>2</PRE_CHOMP> |
142 | <POST_CHOMP>2</POST_CHOMP> |
c61fb758 |
143 | </component> |
ff1f7cb0 |
144 | </config> |
c61fb758 |
145 | |
146 | Note that the name attribute for the C<model> tag should be the relative |
147 | namespace of the Catalyst model, not the absolute one. That is for |
148 | C<MyApp::Model::Something> the C<name> attribute should be C<Something>. |
affbca23 |
149 | |
150 | =head2 YAML |
151 | |
0365c42f |
152 | =head3 Extensions |
153 | |
154 | =over 4 |
155 | |
156 | =item * yml |
157 | |
158 | =item * yaml |
159 | |
160 | =back |
161 | |
162 | =head3 Example Config |
163 | |
affbca23 |
164 | --- |
165 | name: TestApp |
166 | Controller::Foo: |
167 | foo: bar |
168 | Model::Baz: |
169 | qux: xyzzy |
170 | |
b134c74a |
171 | =head1 COOKBOOK |
172 | |
173 | =head2 Configuring a Catalyst::Model::DBIC::Schema model from a YAML config |
174 | |
175 | Model::MyModel: |
ff1f7cb0 |
176 | schema_class: MyApp::MySchema |
177 | connect_info: |
178 | - dbi:SQLite:myapp.db |
179 | - '' |
180 | - '' |
181 | - AutoCommit: 1 |
b134c74a |
182 | |
ea561203 |
183 | =head2 Converting your existing config to Config::General format |
184 | |
185 | As of L<Catalyst::Devel> 1.07, a newly created application will use |
186 | L<Config::General> for configuration. If you wish to convert your existing |
187 | config, run the following one-liner (replacing MyApp with your app's name): |
188 | |
189 | perl -Ilib -MMyApp -MConfig::General -e 'Config::General->new->save_file("myapp.conf", MyApp->config);' |
190 | |
e0d47620 |
191 | =head2 Using UTF-8 strings in a Config::General file |
192 | |
193 | If you have UTF-8 strings in your L<Config::General>-based config file, you |
194 | should add the following config information to MyApp.pm: |
195 | |
196 | __PACKAGE__->config( 'Plugin::ConfigLoader' => { |
197 | driver => { |
198 | 'General' => { -UTF8 => 1 }, |
199 | } |
200 | } ); |
201 | |
6a5c6f19 |
202 | =head2 Using a local configuration file |
203 | |
204 | When ConfigLoader reads configurations, it starts by reading the configuration |
205 | file for C<myapp> with one of the supported extensions as listed |
ff1f7cb0 |
206 | L<above|/CONFIG FORMATS>. |
6a5c6f19 |
207 | |
ff1f7cb0 |
208 | For example, A L<Config::General> config file is F<myapp.conf>. |
6a5c6f19 |
209 | |
210 | If a configuration file called C<myapp_local> exists with one of the supported |
211 | file extensions, it will also be read, and values from that file will |
212 | override values from the main config file. |
213 | |
214 | A L<Config::General> local configuration file would be called |
ff1f7cb0 |
215 | F<myapp_local.conf>. |
6a5c6f19 |
216 | |
217 | The C<local> suffix can be changed. See |
218 | L<Catalyst::Plugin::ConfigLoader/get_config_local_suffix> for the details of |
219 | how. |
220 | |
221 | This is useful because it allows different people or environments to have |
222 | different configuration files. A project with three developers, |
223 | I<Tom>, I<Dick>, and I<Harry> as well as a production environment can have |
ff1f7cb0 |
224 | a F<myapp_tom.conf>, a F<myapp_dick.conf>, a F<myapp_harry.conf>, and a |
225 | F<myapp_production.conf>. |
6a5c6f19 |
226 | |
227 | Each developer, and the web server, would set the environment variable |
228 | to load their proper configuration file. All of the configurations can |
229 | be stored properly in source control. |
230 | |
ff1f7cb0 |
231 | If there is no F<myapp_local.ext> (where C<.ext> is a supported extension), and |
ddb0ab25 |
232 | the individual configuration files contain something required to start the |
233 | application, such as the Model's data source definition, the applicaton won't |
234 | start unless the environment variable is set properly. |
6a5c6f19 |
235 | |
affbca23 |
236 | =cut |