Commit | Line | Data |
0580e0f8 |
1 | package Catalyst::Plugin::ConfigLoader::Environment; |
2 | |
3 | use warnings; |
4 | use strict; |
5 | use JSON::Any; |
6 | |
7 | =head1 NAME |
8 | |
9 | Catalyst::Plugin::ConfigLoader::Environment - Configure your |
10 | application with environment variables. |
11 | |
12 | =head1 VERSION |
13 | |
14 | Version 0.05 |
15 | |
16 | =cut |
17 | |
18 | our $VERSION = '0.05'; |
19 | |
20 | =head1 SYNOPSIS |
21 | |
22 | Catalyst::Plugin::ConfigLoader::Environment reads environment |
23 | variables and sets up the configuration in your application |
24 | accordingly. |
25 | |
26 | Here's how you use it: |
27 | |
28 | package MyApp; |
29 | use Catalyst qw(... ConfigLoader::Environment ...); |
30 | MyApp->setup; |
31 | |
32 | Then, before you run your application, set some environment |
33 | variables: |
34 | |
35 | export MYAPP_foo='Hello, world!' |
36 | export MYAPP_bar="foobar" |
37 | perl script/myapp_server.pl |
38 | |
39 | Inside your application, C<< $c->config->{foo} >> will be equal to |
40 | C<Hello, world!>, and C<< $c->config->{bar} >> will be equal to |
41 | C<foobar>. |
42 | |
43 | =head2 Compatibility with ConfigLoader |
44 | |
45 | You can use both ConfigLoader and this module in the same application. |
46 | If you specify C<ConfigLoader> before C<ConfigLoader::Environment> in |
47 | the import list to Catalyst, the environment will override any |
48 | configuration files that ConfigLoader may find. This is the |
49 | recommended setup. |
50 | |
51 | You can reverse the order in the import list if you want static config |
52 | files to override the environment, but that's not recommended. |
53 | |
54 | =head1 DETAILS |
55 | |
56 | Here's exactly how environment variables are translated into |
57 | configuration. |
58 | |
59 | First, your application's name is converted to ALL CAPS, any colons |
60 | are converted to underscores (i.e. C<My::App> is translated to |
61 | C<MY_APP>), and a C<_> is appended. Then, any environment variables |
62 | not starting with this prefix are discarded. |
63 | |
64 | The prefix is then stripped, and the remaining variables are then |
65 | converted to elements in the C<config> hash as follows. |
66 | |
67 | Variables starting with C<Model::>, C<View::>, or C<Controller::> and |
68 | then any character other than C<_> are treated as configuration |
69 | options for the corresponding component of your application. The |
70 | prefix is saved as C<prefix> and everything after the first C<_> is |
71 | used as a key into the C<< $c->config->{"prefix"} >> hash. |
72 | |
73 | Any other variables not starting with a special prefix are added |
74 | directly to the C<< $c->config >> hash. |
75 | |
76 | =head1 EXAMPLES |
77 | |
78 | Let's translate a YAML config file: |
79 | |
80 | --- |
81 | name: MyApp |
82 | title: This is My App! |
83 | View::Foo: |
84 | EXTENSION: tt |
85 | EVAL_PERL: 1 |
86 | Model::Bar: |
87 | root: "/etc" |
88 | Model::DBIC: |
89 | connect_info: [ "dbi:Pg:dbname=foo", "username", "password" ] |
90 | |
91 | into environment variables that would setup the same configuration: |
92 | |
93 | MYAPP_name=MyApp |
94 | MYAPP_title=This is My App! |
95 | MYAPP_View__Foo_EXTENSION=tt |
96 | MYAPP_View__Foo_EVAL_PERL=1 |
97 | MYAPP_Model__Bar_root=/etc |
98 | MYAPP_Model__DBIC_connect_info=["dbi:Pg:dbname=foo", "username", "password"] |
99 | |
100 | Double colons are converted into double underscores. For |
101 | compatibility's sake, support for the 0.01-style use of |
102 | bourne-incompatible variable names is retained. |
103 | |
104 | Values are JSON-decoded if they look like JSON arrays or objects |
105 | (i.e. if they're enclosed in []s or {}s). Taking advantage of that, we |
106 | can write the same example this way: |
107 | |
108 | MYAPP_name=MyApp |
109 | MYAPP_title=This is My App! |
110 | MYAPP_View__Foo={"EXTENSION":"tt","EVAL_PERL":1} |
111 | MYAPP_Model__Bar={"root":"/etc"} |
112 | MYAPP_Model__DBIC={"connect_info":["dbi:Pg:dbname=foo", "username", "password"]} |
113 | |
114 | =head1 FUNCTIONS |
115 | |
116 | =head2 setup |
117 | |
118 | Overriding Catalyst' setup routine. |
119 | |
120 | =cut |
121 | |
122 | sub setup { |
123 | my $c = shift; |
124 | my $prefix = Catalyst::Utils::class2env($c); |
125 | my %env; |
126 | grep { /^${prefix}[_](.+)$/ && ($env{$1}=$ENV{$_})} keys %ENV; |
127 | |
128 | foreach my $var (keys %env) { |
129 | my $val = $env{$var}; |
130 | |
131 | # Decode JSON array/object |
132 | if ( $val =~ m{^\[.*\]$|^\{.*\}$} ) { |
133 | $val = JSON::Any->jsonToObj($val); |
134 | } |
135 | |
136 | # Special syntax Model__Foo is equivalent to Model::Foo |
137 | if($var =~ /(Model|View|Controller)(?:::|__)([^_]+)(?:_(.+))?$/) { |
138 | $var = "${1}::$2"; |
139 | |
140 | # Special syntax Model__Foo_bar (or Model::Foo_bar) will |
141 | # tweak just the 'bar' subparam for Model::Foo's |
142 | # config. We can accomplish this using a hash that |
143 | # specifies just 'bar' ($c->config will merge hashes). |
144 | if ( defined $3 ) { |
145 | $val = { $3 => $val }; |
146 | } |
147 | } |
148 | |
149 | $c->config( $var => $val ); |
150 | } |
151 | |
152 | return $c->NEXT::setup(@_); |
153 | } |
154 | |
155 | |
156 | =head1 AUTHOR |
157 | |
158 | Jonathan Rockway, C<< <jrockway at cpan.org> >> |
159 | |
160 | =head1 CONTRIBUTORS |
161 | |
162 | mugwump |
163 | |
164 | Ryan D Johnson, C<< <ryan at innerfence.com> >> |
165 | |
166 | =head1 BUGS |
167 | |
168 | Please report any bugs or feature requests to |
169 | C<bug-catalyst-plugin-configloader-environment at rt.cpan.org>, or through the web interface at |
170 | L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Catalyst-Plugin-ConfigLoader-Environment>. |
171 | I will be notified, and then you'll automatically be notified of progress on |
172 | your bug as I make changes. |
173 | |
174 | =head1 SUPPORT |
175 | |
176 | You can find documentation for this module with the perldoc command. |
177 | |
178 | perldoc Catalyst::Plugin::ConfigLoader::Environment |
179 | |
180 | You can also look for information at: |
181 | |
182 | =over 4 |
183 | |
184 | =item * Catalyst Mailing List |
185 | |
186 | L<mailto:catalyst@lists.rawmode.org>. |
187 | |
188 | =item * RT: CPAN's request tracker |
189 | |
190 | L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Catalyst-Plugin-ConfigLoader-Environment> |
191 | |
192 | =back |
193 | |
194 | =head1 COPYRIGHT & LICENSE |
195 | |
196 | Copyright 2006 Jonathan Rockway, all rights reserved. |
197 | |
198 | This program is free software; you can redistribute it and/or modify it |
199 | under the same terms as Perl itself. |
200 | |
201 | If you'd like to use it under a different license, that's probably OK. |
202 | Please contact the author. |
203 | |
204 | =cut |
205 | |
206 | 1; # End of Catalyst::Plugin::ConfigLoader::Environment |