blib/lib/Web/VWF/Config.pm untested

filter: Statementstmt 0.0% 0 / 123 Branchbran 0.0% 0 / 72 Conditioncond 0.0% 0 / 30 MC/DCmcdc 0.0% 0 / 20 Subroutinesub 0.0% 0 / 13 Podpod 0.0% 0 / 2 totaltotal 0.0% 0 / 260 CC 37 SCAR 64.6
CC
37
Cov
0%
new
992.0
AUTOLOAD
56.0
BEGIN
2.0
CRAP 636.0
1 package Web::VWF::Config;
2  
3 # VWF is licensed under GPL2.0 for personal use only
4 # njh@bandsman.co.uk
5  
6 # Usage is subject to licence terms.
7 # The licence terms of this software are as follows:
8 # Personal single user, single computer use: GPL2
9 # All other users (including Commercial, Charity, Educational, Government)
10 # must apply in writing for a licence for use from Nigel Horne at the
11 # above e-mail.
12  
13 use warnings;
14 use strict;
15  
16 use Carp;
17 use Config::Abstraction;
18 use CGI::Info;
19 use Data::Dumper;
20 use Web::VWF::Utils ();
21 use Error::Simple;
22 use File::Spec;
23 use Params::Get 0.13;
24  
25 =encoding utf-8
26  
27 =head1 NAME
28  
29 Web::VWF::Config - Site-independent configuration file for the Versatile Web Framework
30  
31 =head1 VERSION
32  
33 Version 0.003.0
34  
35 =cut
36  
37 use version; our $VERSION = version->declare('0.003.0');
38  
39 # Where the server keeps one configuration directory per site, named after the
40 # site - see Web::VWF::directory()
41 our $DEFAULT_DIRECTORY = '/usr/lib/vwf';
42  
43 =head1 SUBROUTINES/METHODS
44  
45 =head2 new
46  
47 Creates a new Web::VWF::Config instance with hierarchical configuration loading.
48  
49 Takes four optional arguments:
50 info (CGI::Info object)
51 logger
52 config_directory - used when the configuration directory can't be worked out
53 config_file - name of the configuration file - otherwise determined dynamically
54 config (ref to hash of values to override in the config file
55  
56 Values in the file are overridden by what's in the environment
57  
58 B<Parameters:>
59  
60 =over 4
61  
62 =item * C<info> - CGI::Info object (optional, created if not provided)
63  
64 =item * C<logger> - Logger object with debug() method (optional)
65  
66 =item * C<config_directory> - Additional config directory path (optional)
67  
68 =item * C<config_file> - Specific config filename (optional)
69  
70 =item * C<config> - Hash ref of override values (optional)
71  
72 =back
73  
74 B<Configuration Resolution Order:>
75 1. Base configuration files
76 2. Values from config parameter
77 3. Environment variable overrides
78  
79 B<Directory Search Order:>
80 1. $ENV{CONFIG_DIR} (if set)
81 2. Provided config_directory
82 3. ../conf relative to script
83 4. ../../conf relative to script
84 5. $DOCUMENT_ROOT/../lib/conf
85 6. $HOME/lib/conf
86  
87 B<Returns:> Blessed Web::VWF::Config object
88  
89 B<Throws:> Error::Simple on configuration errors
90  
91 =head3 FORMAL SPECIFICATION
92  
93 [STRING, HASH, LOGGER]
94  
95 ConfigState ::= ⟨⟨ config_dirs : ℙ STRING;
96 config_data : HASH;
97 logger : LOGGER ⟩⟩
98  
99 ConfigArgs ::= ⟨⟨ info : CGI_Info;
100 logger : LOGGER;
101 config_directory : STRING;
102 config_file : STRING;
103 config : HASH ⟩⟩
104  
105 Init : ConfigArgs → ConfigState
106  
107 ∀ params : ConfigArgs •
108 let dirs == if env.CONFIG_DIR ≠ ∅
109 then {env.CONFIG_DIR}
110 else default_dirs ∪ {params.config_directory} fi •
111 let valid_dirs == {d : dirs | ∃ f : FILE • readable(d, f)} •
112 valid_dirs ≠ ∅ ∧
113 config_data ∈ HASH ∧
114 config_data = merge(file_config, params.config, env_overrides)
115  
116 ValidConfigKey == {k : STRING | k ∈ dom config_data}
117  
118 GetConfigValue : ValidConfigKey → (STRING ∪ HASH ∪ ARRAY)
119  
120 =cut
121  
122 sub new
123 {
124 my $proto = shift;
125 my $params = Params::Get::get_params(undef, @_);
126  
127 if (exists $params->{logger} && defined $params->{logger}) {
128 throw Error::Simple('logger must be an object with debug method')
129 unless ref($params->{logger}) && $params->{logger}->can('debug');
130 }
131  
132 if($params->{'logger'}) {
133 $params->{'logger'}->debug(__PACKAGE__, '->new()');
134 }
135  
136 if(exists $params->{config} && defined $params->{config}) {
137 throw Error::Simple('config must be a hash reference') unless ref($params->{config}) eq 'HASH';
138 }
139  
140 my $class = ref($proto) || $proto;
141 my $info = $params->{info} || CGI::Info->new();
142  
143 my @config_dirs;
144 if($ENV{'CONFIG_DIR'}) {
145 # Validate directory exists
146 throw Error::Simple("CONFIG_DIR '$ENV{CONFIG_DIR}' does not exist or is not readable")
147 unless -d $ENV{'CONFIG_DIR'} && -r $ENV{'CONFIG_DIR'};
148 @config_dirs = ($ENV{'CONFIG_DIR'});
149 } else {
150 # Build the standard search path; caller's config_directory is prepended below
151 @config_dirs = (
152 File::Spec->catdir(
153 $info->script_dir(),
154 File::Spec->updir(),
155 File::Spec->updir(),
156 'conf'
157 ), File::Spec->catdir(
158 $info->script_dir(),
159 File::Spec->updir(),
160 'conf'
161 )
162 );
163  
164 # The server's own directory for this site, used when the site keeps no
165 # conf/ beside its cgi-bin/. The domain name comes from the Host header,
166 # so it must look like a host name before it is made part of a path
167 if(defined(my $directory = $params->{'directory'})) {
168 throw Error::Simple('directory must be a string') if ref($directory);
169 my $domain = $info->domain_name();
170 if(defined($domain) && ($domain =~ /\A[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)*\z/)) {
171 push @config_dirs, File::Spec->catdir($directory, $domain);
172 }
173 }
174  
175 if($ENV{'DOCUMENT_ROOT'}) {
176 push(@config_dirs, File::Spec->catdir(
177 $ENV{'DOCUMENT_ROOT'},
178 File::Spec->updir(),
179 'lib',
180 'conf'
181 ))
182 }
183 if($ENV{'HOME'}) {
184 push(@config_dirs, File::Spec->catdir(
185 $ENV{'HOME'},
186 'lib',
187 'conf'
188 ));
189 }
190  
191 # Prepend the caller-supplied directory so it takes highest precedence
192 if($params->{config_directory}) {
193 throw Error::Simple("config_directory must be a string") if ref($params->{config_directory});
194 throw Error::Simple("config_directory '$params->{config_directory}' does not exist")
195 unless -d $params->{config_directory};
196 unshift @config_dirs, $params->{config_directory};
197 }
198 }
199  
200 # Look for localised configurations
201 my $language;
202 if(my $lingua = $params->{'lingua'}) {
203 $language = $lingua->language_code_alpha2();
204 }
205 $language ||= $info->lang();
206  
207 if($language) {
208 @config_dirs = map {
209 ($_, "$_/default", "$_/$language")
210 } @config_dirs;
211 } else {
212 @config_dirs = map {
213 ($_, File::Spec->catdir($_, 'default'))
214 } @config_dirs;
215 }
216  
217 if($params->{'debug'}) {
218 # Not sure this really does anything
219 # $Config::Auto::Debug = 1;
220  
221 if($params->{logger}) {
222 while(my ($key,$value) = each %ENV) {
223 if($value) {
224 $params->{logger}->debug("$key=$value");
225 }
226 }
227 }
228 }
229  
230 my $config;
231 eval {
232 $config = Config::Abstraction->new(
233 config_dirs => \@config_dirs,
234 config_files => ['default', $info->domain_name(), $ENV{'CONFIG_FILE'}, $params->{'config_file'}],
235 logger => $params->{'logger'}
236 )->all();
237 };
238 if($@ || !defined($config)) {
239 throw Error::Simple("Configuration error: $@");
240 }
241  
242 # Validate essential configuration structure
243 throw Error::Simple('Configuration must be a hash reference') unless(ref($config) eq 'HASH');
244  
245 # The values in config are defaults which can be overridden by
246 # the values in params->{config}
247 if(defined($params->{'config'})) {
248 $config = { %{$config}, %{$params->{'config'}} };
249 }
250  
251 # Allow variables to be overridden by the environment
252 foreach my $key(keys %{$config}) {
253 if(my $value = $ENV{$key}) {
254 # Validate environment variable names
255 # throw Error::Simple("Invalid environment variable name: $key")
256 # unless $key =~ /^[A-Z_][A-Z0-9_]*$/;
257  
258 # Sanitize values
259 # $value =~ s/[^\w\s=\.\-]//g; # Remove potentially dangerous characters
260  
261 if($params->{'logger'}) {
262 $params->{'logger'}->debug(__PACKAGE__, ': ', __LINE__, " overwriting $key, ", $config->{$key}, " with $value");
263 }
264 # If the value contains an equals make it into a hash value
265 if($value =~ /(.+)=(.+)/) {
266 delete $config->{$key} if(!ref($config->{$key}));
267 $config->{$key}{$1} = $2;
268 } else {
269 $config->{$key} = $value;
270 }
271 }
272 }
273  
274 # Config::Any turns fields with spaces into arrays, put them back
275 foreach my $field('Contents', 'SiteTitle') {
276 next if(!exists $config->{$field});
277 my $value = $config->{$field};
278  
279 if(ref($value) eq 'ARRAY') {
280 $config->{$field} = join(' ', @{$value});
281 }
282 }
283  
284 # unless($config->{'config_path'}) {
285 # $config->{'config_path'} = File::Spec->catdir($config_dir, $info->domain_name());
286 # }
287 if($params->{'debug'} && $params->{'logger'}) {
288 $params->{'logger'}->debug(__PACKAGE__, '(', __LINE__, '): ', Data::Dumper->new([Web::VWF::Utils::redact_config($config)])->Dump());
289 }
290  
291 return bless $config, $class;
292 }
293  
294 sub AUTOLOAD
295 {
296 our $AUTOLOAD;
297 my $self = shift;
298  
299 # Called as a class method there is no hash to look in
300 return undef unless(ref($self));
301 return unless defined($AUTOLOAD);
302  
303 # Extract the key name from the AUTOLOAD variable
304 (my $key = $AUTOLOAD) =~ s/.*:://;
305  
306 return unless defined($key);
307  
308 # Don't handle special methods
309 return if $key eq 'DESTROY';
310  
311 # Validate method name - only allow safe config keys
312 Carp::croak(__PACKAGE__, ": Invalid key name: $key") unless $key =~ /^[a-zA-Z_][a-zA-Z0-9_]*$/;
313  
314 # Return the value of the corresponding hash key
315 # Only return existing keys to avoid auto-vivification
316 return exists $self->{$key} ? $self->{$key} : undef;
317 }
318  
319 1;
320  
321 =head1 AUTHOR
322  
323 Nigel Horne, C<< <njh at nigelhorne.com> >>
324  
325 =head1 LICENCE AND COPYRIGHT
326  
327 Copyright 2010-2026 Nigel Horne.
328  
329 Usage is subject to the GPL2 licence terms.
330 If you use it,
331 please let me know.
332  
333 =cut