FormValidator.pm untested

filter: Statementstmt 0.0% 0 / 47 Branchbran 0.0% 0 / 20 Conditioncond 0.0% 0 / 6 MC/DCmcdc 0.0% 0 / 4 Subroutinesub 0.0% 0 / 8 Podpod 0.0% 0 / 5 totaltotal 0.0% 0 / 90 CC 11 SCAR 33.1
CC
11
Cov
0%
load_profiles
56.0
check
20.0
new
6.0
CRAP 27.4
1 #
2 # FormValidator.pm - Object that validates form input data.
3 #
4 # This file is part of FormValidator.
5 #
6 # Author: Francis J. Lacoste <francis.lacoste@Contre.COM>
7 #
8 # Copyright (C) 1999,2000 iNsu Innovations Inc.
9 # Copyright (C) 2001 Francis J. Lacoste
10 #
11 # This program is free software; you can redistribute it and/or modify
12 # it under the terms same terms as perl itself.
13 #
14 package HTML::FormValidator;
15  
16 use HTML::FormValidator::Results;
17  
18 use strict;
19  
20 use vars qw( $VERSION );
21  
22 BEGIN {
23 $VERSION = '0.11';
24 }
25  
26 =pod
27  
28 =head1 NAME
29  
30 HTML::FormValidator - Validates user input (usually from an HTML form) based
31 on input profile.
32  
33 =head1 SYNOPSIS
34  
35 In an HTML::Empberl page:
36  
37 use HTML::FormValidator;
38  
39 my $validator = new HTML::FormValidator( "/home/user/input_profiles.pl" );
40 my ( $valid, $missing, $invalid, $unknown ) = $validator->validate( \%fdat, "customer_infos" );
41  
42 =head1 DESCRIPTION
43  
44 HTML::FormValidator's main aim is to make the tedious coding of input
45 validation expressible in a simple format and to let the programmer focus
46 on more interesting task.
47  
48 When you are coding web application one of the most tedious though
49 crucial task is to validate user's input (usually submitted by way of
50 an HTML form). You have to check that each required fields is present
51 and that some feed have valid data. (Does the phone input looks like a
52 phone number ? Is that a plausible email address ? Is the YY state
53 valid ? etc.) For simple form, this is not really a problem but as
54 forms get more complex and you code more of them this task became
55 really boring and tedious.
56  
57 HTML::FormValidator lets you defines profiles which defines the
58 required fields and their format. When you are ready to validate the
59 user's input, you tell HTML::FormValidator the profile to apply to the
60 user data and you get the valid fields, the name of the fields which
61 are missing, the name of the fields that contains invalid input and
62 the name of the fields that are unknown to this profile.
63  
64 You are then free to use this information to build a nice display to
65 the user telling which fields that he forgot to fill.
66  
67 =cut
68  
69 sub new {
70 my $proto = shift;
71 my $class = ref $proto || $proto;
72  
73 my $profile_file = shift;
74 my $profiles = undef;
75  
76 if ( ref $profile_file ) {
77 # Profile already passed as an hash reference.
78 $profiles = $profile_file;
79 $profile_file = undef;
80 }
81  
82  
83 bless { profile_file => $profile_file,
84 profiles => $profiles,
85 }, $class;
86 }
87  
88 =pod
89  
90 =head1 INPUT PROFILE SPECIFICATION
91  
92 To create a HTML::FormValidator, use the following :
93  
94 my $validator = new HTML::FormValidator( $input_profile );
95  
96 Where $input_profile may either be an hash reference to an input
97 profiles specification or a file that will be evaluated at runtime to
98 get a hash reference to an input profiles specification.
99  
100 The input profiles specification is an hash reference where each key
101 is the name of the input profile and each value is another hash
102 reference which contains the actual profile elements. If the input
103 profile is specified as a file name, the profiles will be reread each
104 time that the disk copy is modified.
105  
106 Here is an example of a valid input profiles specification :
107  
108 {
109 customer_infos => {
110 optional =>
111 [ qw( company fax country ) ],
112 required =>
113 [ qw( fullname phone email address city state zipcode ) ],
114 constraints =>
115 {
116 email => "email",
117 fax => "american_phone",
118 phone => "american_phone",
119 zipcode => '/^\s*\d{5}(?:[-]\d{4})?\s*$/',
120 state => "state",
121 },
122 defaults => {
123 country => "USA",
124 },
125 },
126 customer_billing_infos => {
127 optional => [ "cc_no" ],
128 dependencies => {
129 "cc_no" => [ qw( cc_type cc_exp ) ],
130 },
131 constraints => {
132 cc_no => { constraint => "cc_number",
133 params => [ qw( cc_no cc_type ) ],
134 },
135 cc_type => "cc_type",
136 cc_exp => "cc_exp",
137 }
138 filters => [ "trim" ],
139 field_filters => { cc_no => "digit" },
140 },
141 }
142  
143 The following are the valid fields for an input specification :
144  
145 =over
146  
147 =item required
148  
149 This is an array reference which contains the name of the fields which
150 are required. Any fields in this list which are not present in the
151 user input will be reported as missing.
152  
153 =item optional
154  
155 This is an array reference which contains the name of optional fields.
156 These are fields which MAY be present and if they are, they will be
157 check for valid input. Any fields not in optional or required list
158 will be reported as unknown.
159  
160 =item dependencies
161  
162 This is an hash reference which contains dependencies information.
163 This is for the case where one optional fields has other requirements.
164 For example, if you enter your credit card number, the field cc_exp
165 and cc_type should also be present. Any fields in the dependencies
166 list that is missing when the target is present will be reported as
167 missing.
168  
169 =item conflicts
170  
171 This is an hash reference which contains conflicts information. The
172 key is the name of the field, which if present, the fields in the
173 array reference value shouldn't be present. The fields which conflicts
174 with another will be reported as conflicting.
175  
176 =item defaults
177  
178 This is an hash reference which contains defaults which should be
179 substituted if the user hasn't filled the fields. Key is field name
180 and value is default value which will be returned in the list of valid
181 fields.
182  
183 =item filters
184  
185 This is a reference to an array of filters that will be applied to ALL
186 optional or required fields. This can be the name of a builting filter
187 (trim,digit,etc) or an anonymous subroutine which should take one parameter, the field value and return the (possibly) modified value.
188  
189 =item field_filters
190  
191 This is a reference to an hash which contains reference to array of
192 filters which will be apply to specific input fields. The key of the
193 hash is the name of the input field and the valud is a reference to an
194 array of filters like for the filters parameter.
195  
196 =item constraints
197  
198 This is a reference to an hash which contains the constraints that
199 will be used to check wheter or not the field contains valid data.
200 Constraint can be either the name of a builtin constraint function
201 (see below), a perl regexp or an anonymous subroutine which will check
202 the input and return 1 or 0 depending on the input's validity.
203 The constraint function may also -1 to express data that is valid but
204 not recommended.
205  
206 The constraint function takes one parameter, the input to be validated
207 and returns 1, 0 or -1. It is possible to specify the parameters
208 that will be passed to the subroutine. For that use an hash reference
209 which contains in the I<constraint> element, the anonymous subroutine
210 or the name of the builtin and in the I<params> element the name of
211 the fields to pass a parameter to the function. (Don't forget to
212 include the name of the field to check in that list!) For an example,
213 look at the I<cc_no> constraint example.
214  
215 =back
216  
217 =cut
218  
219 sub load_profiles {
220 my $self = shift;
221  
222 my $file = $self->{profile_file};
223 return unless $file;
224  
225 die "No such file: $file\n" unless -f $file;
226 die "Can't read $file\n" unless -r _;
227  
228 my $mtime = (stat _)[9];
229 return if $self->{profiles} and $self->{profiles_mtime} <= $mtime;
230  
231 $self->{profiles} = do $file;
232 die "Error in input profiles: $@\n" if $@;
233 die "Input profiles didn't return an hash ref\n"
234 unless ref $self->{profiles} eq "HASH";
235  
236 $self->{profiles_mtime} = $mtime;
237 }
238  
239 =pod
240  
241 =head1 VALIDATING INPUT
242  
243 my $results = $validator->check( \%fdat, "customer_infos" );
244  
245 my %fdat = $results->valid();
246 if ( $results->has_missing) ) {
247 foreach my $f ( $results->missing ) {
248 print "Field ", $f , " is missing\n";
249 }
250 }
251  
252 To validate input you use the check() method. This method takes two
253 parameters :
254  
255 =over
256  
257 =item data
258  
259 Contains an hash which should correspond to the form input as
260 submitted by the user. This hash is not modified by the call to validate.
261  
262 =item profile
263  
264 Can be either a name which will be used to lookup the corresponding profile
265 in the input profiles specification, or it can be an hash reference to the
266 input profile which should be used.
267  
268 =back
269  
270 This method returns an HTML::FormValidator::Results(3) object. This
271 object can then be queried for valid, invalid, unknown, missing fields
272 or fields which cause conflicts or have warnings. Consult the
273 HTML::FormValidator::Results(3) for more information.
274  
275 There is also a deprecated method which takes the same parameter but
276 returns its as result in a 4 elements array.
277  
278 =over
279  
280 =item valid
281  
282 This is an hash reference to the valid fields which were submitted in
283 the data. The data may have been modified by the various filters specified.
284  
285 =item missing
286  
287 This is a reference to an array which contains the name of the missing
288 fields. Those are the fields that the user forget to fill or filled
289 with space. These fields may comes from the I<required> list or the
290 I<dependencies> list.
291  
292 =item invalid
293  
294 This is a reference to an hash which contains the the fields and their value
295 which failed their constraint check.
296  
297 =item unknown
298  
299 This is a reference to an hash which contains the fields which are unknown
300 to the profile. Whether or not this indicates an error in the user
301 input is application dependant.
302  
303 =back
304  
305 =cut
306  
307 sub validate {
308 my $data_set = check( @_ );
309  
310 my $valid = $data_set->valid();
311 my $missing = $data_set->missing();
312 my $invalid = [ $data_set->invalid ];
313 my $unknown = [ $data_set->unknown ];
314  
315 return ( $valid, $missing, $invalid, $unknown );
316 }
317  
318 sub check {
319 my ( $self, $data, $name ) = @_;
320  
321 my $profile;
322 if ( ref $name ) {
323 $profile = $name;
324 } else {
325 $self->load_profiles;
326 $profile = $self->{profiles}{$name};
327 die "No such profile $name\n" unless $profile;
328 }
329 die "Invalid input profile\n" unless ref $profile eq "HASH";
330  
331 new HTML::FormValidator::Results( $profile, $data );
332 }
333  
334 1;
335  
336 __END__