1Data::FormValidator::CoUnssetrraCionnttsr(i3b)uted PerlDDaotcau:m:eFnotramtViaolnidator::Constraints(3)
2
6 Data::FormValidator::Constraints - Basic sets of constraints on input
7 profile.
8
10 use Data::FormValidator::Constraints qw(:closures);
11 In an Data::FormValidator profile:
13 constraint_methods => {
15 email => email(),
16 fax => american_phone(),
17 phone => american_phone(),
18 state => state(),
19 },
20
22 These are the builtin constraints that can be specified by name in the
23 input profiles.
24 Be sure to check out the SEE ALSO section for even more pre-packaged
26 constraints you can use.
27 FV_length_between(1,23)
29 FV_max_length(23)
30 FV_min_length[1m(1)
31 use Data::FormValidator::Constraints qw(
32 FV_length_between
33 FV_min_length
34 FV_max_length
35 );
36 constraint_methods => {
38 # specify a min and max, inclusive
40 last_name => FV_length_between(1,23),
41 }
43 Specify a length constraint for a field.
45 These constraints have a different naming convention because they are
47 higher-order functions. They take input and return a code reference to
48 a standard constraint method. A constraint name of "length_between",
49 "min_length", or "max_length" will be set, corresponding to the
50 function name you choose.
51 The checks are all inclusive, so a max length of '100' will allow the
53 length 100.
54 Length is measured in perl characters as opposed to bytes or anything
56 else.
57 This constraint will untaint your data if you have untainting turned
59 on. However, a length check alone may not be enough to insure the
60 safety of the data you are receiving. Using additional constraints to
61 check the data is encouraged.
62 FV_eq_with
64 use Data::FormValidator::Constraints qw( FV_eq_with );
65 constraint_methods => {
67 password => FV_eq_with('password_confirm'),
68 }
69 Compares the current field to another field. A constraint name of
71 "eq_with" will be set.
72 email
74 Checks if the email LOOKS LIKE an email address. This should be
75 sufficient 99% of the time.
76 Look elsewhere if you want something super fancy that matches every
78 possible variation that is valid in the RFC, or runs out and checks
79 some MX records.
80 state_or_province
82 This one checks if the input correspond to an american state or a
83 canadian province.
84 state
86 This one checks if the input is a valid two letter abbreviation of an
87 American state.
88 province
90 This checks if the input is a two letter Canadian province
91 abbreviation.
92 zip_or_postcode
94 This constraints checks if the input is an American zipcode or a
95 Canadian postal code.
96 postcode
98 This constraints checks if the input is a valid Canadian postal code.
99 zip
101 This input validator checks if the input is a valid american zipcode :
102 5 digits followed by an optional mailbox number.
103 phone
105 This one checks if the input looks like a phone number, (if it contains
106 at least 6 digits.)
107 american_phone
109 This constraints checks if the number is a possible North American
110 style of phone number : (XXX) XXX-XXXX. It has to contains 7 or more
111 digits.
112 cc_number
114 This constraint references the value of a credit card type field.
115 constraint_methods => {
117 cc_no => cc_number({fields => ['cc_type']}),
118 }
119 The number is checked only for plausibility, it checks if the number
121 could be valid for a type of card by checking the checksum and looking
122 at the number of digits and the number of digits of the number.
123 This functions is only good at catching typos. IT DOESN'T CHECK IF
125 THERE IS AN ACCOUNT ASSOCIATED WITH THE NUMBER.
126 cc_exp
128 This one checks if the input is in the format MM/YY or MM/YYYY and if
129 the MM part is a valid month (1-12) and if that date is not in the
130 past.
131 cc_type
133 This one checks if the input field starts by M(asterCard), V(isa),
134 A(merican express) or D(iscovery).
135 ip_address
137 This checks if the input is formatted like a dotted decimal IP address
138 (v4). For other kinds of IP address method, See Regexp::Common::net
139 which provides several more options. "REGEXP::COMMON SUPPORT" explains
140 how we easily integrate with Regexp::Common.
141
143 Data::FormValidator also includes built-in support for using any of
144 regular expressions in Regexp::Common as named constraints. Simply use
145 the name of regular expression you want. This works whether you want
146 to untaint the data or not. For example:
147 use Data::FormValidator::Constraints qw(:regexp_common);
149 constraint_methods => {
151 my_ip_address => FV_net_IPv4(),
152 # An example with parameters
154 other_ip => FV_net_IPv4(-sep=>' '),
155 }
156 Notice that the routines are named with the prefix "FV_" instead of
158 "RE_" now. This is simply a visual cue that these are slightly
159 modified versions. We've made a wrapper for each Regexp::Common routine
160 so that it can be used as a named constraint like this.
161 Be sure to check out the Regexp::Common syntax for how its syntax
163 works. It will make more sense to add future regular expressions to
164 Regexp::Common rather than to Data::FormValidator.
165
167 You may also call these functions directly through the procedural
168 interface by either importing them directly or importing the whole
169 :validators group. This is useful if you want to use the built-in
170 validators out of the usual profile specification interface.
171 For example, if you want to access the email validator directly, you
173 could either do:
174 use Data::FormValidator::Constraints (qw/valid_email/);
176 or
177 use Data::FormValidator::Constraints (:validators);
178 if (valid_email($email)) {
180 # do something with the email address
181 }
182 Notice that when you call validators directly, you'll need to prefix
184 the validator name with "valid_"
185 Each validator also has a version that returns the untainted value if
187 the validation succeeded. You may call these functions directly through
188 the procedural interface by either importing them directly or importing
189 the :matchers group. For example if you want to untaint a value with
190 the email validator directly you may:
191 if ($email = match_email($email)) {
193 system("echo $email");
194 }
195 else {
196 die "Unable to validate email";
197 }
198 Notice that when you call validators directly and want them to return
200 an untainted value, you'll need to prefix the validator name with
201 "match_"
202
204 New School Constraints Overview
205 This is the current recommended way to write constraints. See also "Old
206 School Constraints".
207 The most flexible way to create constraints to use closures-- a normal
209 seeming outer subroutine which returns a customized DFV method
210 subroutine as a result. It's easy to do. These "constraint methods"
211 can be named whatever you like, and imported normally into the name
212 space where the profile is located.
213 Let's look at an example.
215 # Near your profile
217 # Of course, you don't have to export/import if your constraints are in the same
218 # package as the profile.
219 use My::Constraints 'coolness';
220 # In your profile
222 constraint_methods => {
223 email => email(),
224 prospective_date => coolness( 40, 60,
225 {fields => [qw/personality smarts good_looks/]}
226 ),
227 }
228 Let's look at how this complex "coolness" constraint method works. The
230 interface asks for users to define minimum and maximum coolness values,
231 as well as declaring three data field names that we should peek into to
232 look their values.
233 Here's what the code might look like:
235 sub coolness {
237 my ($min_cool,$max_cool, $attrs) = @_;
238 my ($personality,$smarts,$looks) = @{ $attrs->{fields} } if $attrs->{fields};
239 return sub {
240 my $dfv = shift;
241 # Name it to refer to in the 'msgs' system.
243 $dfv->name_this('coolness');
244 # value of 'prospective_date' parameter
246 my $val = $dfv->get_current_constraint_value();
247 # get other data to refer to
249 my $data = $dfv->get_filtered_data;
250 my $has_all_three = ($data->{$personality} && $data->{$smarts} && $data->{$looks});
252 return ( ($val >= $min_cool) && ($val <= $max_cool) && $has_all_three );
253 }
254 }
255 Old School Constraints
257 Here is documentation on how old school constraints are created. These
258 are supported, but the the new school style documented above is
259 recommended.
260 See also the "validator_packages" option in the input profile, for
262 loading sets of old school constraints from other packages.
263 Old school constraint routines are named two ways. Some are named with
265 the prefix "match_" while others start with "valid_". The difference is
266 that the "match_" routines are built to untaint the data and return a
267 safe version of it if it validates, while "valid_" routines simply
268 return a true value if the validation succeeds and false otherwise.
269 It is preferable to write "match_" routines that untaint data for the
271 extra security benefits. Plus, Data::FormValidator will AUTOLOAD a
272 "valid_" version if anyone tries to use it, so you only need to write
273 one routine to cover both cases.
274 Usually constraint routines only need one input, the value being
276 specified. However, sometimes more than one value is needed.
277 Example:
279 image_field => {
281 constraint_method => 'max_image_dimensions',
282 params => [\100,\200],
283 },
284 Using that syntax, the first parameter that will be passed to the
286 routine is the Data::FormValidator object. The remaining parameters
287 will come from the "params" array. Strings will be replaced by the
288 values of fields with the same names, and references will be passed
289 directly.
290 In addition to "constraint_method", there is also an even older
292 technique using the name "constraint" instead. Routines that are
293 designed to work with "constraint" don't have access to
294 Data::FormValidator object, which means users need to pass in the name
295 of the field being validated. Besides adding unnecessary syntax to the
296 user interface, it won't work in conjunction with
297 "constraint_regexp_map".
298 Methods available for use inside of constraints
300 A few useful methods to use on the Data::FormValidator::Results object
301 are available to you to use inside of your routine.
302 get_input_data()
304 Returns the raw input data. This may be a CGI object if that's what was
306 used in the constraint routine.
307 Examples:
309 # Raw and uncensored
311 my $data = $self->get_input_data;
312 # tamed to be a hashref, if it wasn't already
314 my $data = $self->get_input_data( as_hashref => 1 );
315 get_filtered_data()
317 my $data = $self->get_filtered_data;
319 Returns the valid filtered data as a hashref, regardless of whether it
321 started out as a CGI.pm compatible object. Multiple values are
322 expressed as array references.
323 get_current_constraint_field()
325 Returns the name of the current field being tested in the constraint.
327 Example:
329 my $field = $self->get_current_constraint_field;
331 This reduces the number of parameters that need to be passed into the
333 routine and allows multi-valued constraints to be used with
334 "constraint_regexp_map".
335 For complete examples of multi-valued constraints, see
337 Data::FormValidator::Constraints::Upload
338 get_current_constraint_value()
340 Returns the name of the current value being tested in the constraint.
342 Example:
344 my $value = $self->get_current_constraint_value;
346 This reduces the number of parameters that need to be passed into the
348 routine and allows multi-valued constraints to be used with
349 "constraint_regexp_map".
350 get_current_constraint_name()
352 Returns the name of the current constraint being applied
354 Example:
356 my $value = $self->get_current_constraint_name;
358 This is useful for building a constraint on the fly based on its name.
360 It's used internally as part of the interface to the Regexp::Commmon
361 regular expressions.
362 untainted_constraint_value()
364 return $dfv->untainted_constraint_value($match);
366 If you have written a constraint which untaints, use this method to
368 return the untainted result. It will prepare the right result whether
369 the user has requested untainting or not.
370 name_this()
372 set_current_constraint_name()
374 Sets the name of the current constraint being applied.
376 Example:
378 sub my_constraint {
380 my @outer_params = @_;
381 return sub {
382 my $dfv = shift;
383 $dfv->set_current_constraint_name('my_constraint');
384 my @params = @outer_params;
385 # do something constraining here...
386 }
387 }
388 By returning a closure which uses this method, you can build an
390 advanced named constraint in your profile, before you actually have
391 access to the DFV object that will be used later. See
392 Data::FormValidator::Constraints::Upload for an example.
393 "name_this" is a provided as a shorter synonym.
395 The "meta()" method may also be useful to communicate meta data that
397 may have been found. See Data::FormValidator::Results for documentation
398 of that method.
399
401 Prior to Data::FormValidator 4.00, constraints were specified a bit
402 differently. This older style is still supported.
403 It was not necessary to explicitly load some constraints into your name
405 space, and the names were given as strings, like this:
406 constraints => {
408 email => 'email',
409 fax => 'american_phone',
410 phone => 'american_phone',
411 state => 'state',
412 my_ip_address => 'RE_net_IPv4',
413 other_ip => {
414 constraint => 'RE_net_IPv4',
415 params => [ \'-sep'=> \' ' ],
416 },
417 my_cc_no => {
418 constraint => 'cc_number',
419 params => [qw/cc_no cc_type/],
420 }
421 },
422
424 Constraints available in other modules
425 Data::FormValidator::Constraints::Upload - validate the bytes, format
426 and dimensions of file uploads
427 Data::FormValidator::Constraints::DateTime - A newer DateTime
428 constraint module. May save you a step of transforming the date into a
429 more useful format after it's validated.
430 Data::FormValidator::Constraints::Dates - the original DFV date
431 constraint module. Try the newer one first!
432 Data::FormValidator::Constraints::Japanese - Japan-specific constraints
433 Data::FormValidator::Constraints::MethodsFactory - a useful collection
434 of tools generate more complex constraints. Recommended!
435 Related modules in this package
437 Data::FormValidator::Filters - transform data before constraints are
438 applied
439 Data::FormValidator::ConstraintsFactory - This is a historical
440 collection of constraints that suffer from cumbersome names. They are
441 worth reviewing though-- "make_and_constraint" will allow to validate
442 against a list of constraints and shortcircuit if the first one fails.
443 That's perfect if the second constraint depends on the first one having
444 passed. For a modern version of this toolkit, see
445 Data::FormValidator::Constraints::MethodsFactory.
446 Data::FormValidator
447
449 Some of those input validation functions have been taken from MiniVend
450 by Michael J. Heins
451 The credit card checksum validation was taken from contribution by
453 Bruce Albrecht to the MiniVend program.
454
456 Francis J. Lacoste
457 Michael J. Heins
458 Bruce Albrecht
459 Mark Stosberg
460
462 Copyright (c) 1999 iNsu Innovations Inc. All rights reserved.
463 Parts Copyright 1996-1999 by Michael J. Heins Parts Copyright 1996-1999
465 by Bruce Albrecht Parts Copyright 2005-2009 by Mark Stosberg
466 This program is free software; you can redistribute it and/or modify it
468 under the terms as perl itself.
469perl v5.12.3 2011-08-28Data::FormValidator::Constraints(3)