Data::FormValidator::Constraints(3pm)

1Data::FormValidator::CoUnssetrraCionnttsr(i3b)uted PerlDDaotcau:m:eFnotramtViaolnidator::Constraints(3)
2
3
4

NAME

6       Data::FormValidator::Constraints - Basic sets of constraints on input
7       profile.
8

SYNOPSIS

10        use Data::FormValidator::Constraints qw(:closures);
11
12       In an Data::FormValidator profile:
13
14           constraint_methods => {
15               email   => email(),
16               phone   => american_phone(),
17               first_names =>  {
18                  constraint_method => FV_max_length(3),
19                  name => 'my_custom_name',
20              },
21           },
22           msgs => {
23              constraints => {
24                   my_custom_name => 'My message',
25              },
26           },
27

DESCRIPTION

29       These are the builtin constraints that can be specified by name in the
30       input profiles.
31
32       Be sure to check out the SEE ALSO section for even more pre-packaged
33       constraints you can use.
34
35   FV_length_between(1,23)
36   FV_max_length(23)
37   FV_min_length(1)
38         use Data::FormValidator::Constraints qw(
39           FV_length_between
40           FV_min_length
41           FV_max_length
42         );
43
44         constraint_methods => {
45
46           # specify a min and max, inclusive
47           last_name        => FV_length_between(1,23),
48
49         }
50
51       Specify a length constraint for a field.
52
53       These constraints have a different naming convention because they are
54       higher-order functions. They take input and return a code reference to
55       a standard constraint method. A constraint name of "length_between",
56       "min_length", or "max_length" will be set, corresponding to the
57       function name you choose.
58
59       The checks are all inclusive, so a max length of '100' will allow the
60       length 100.
61
62       Length is measured in perl characters as opposed to bytes or anything
63       else.
64
65       This constraint will untaint your data if you have untainting turned
66       on. However, a length check alone may not be enough to insure the
67       safety of the data you are receiving.  Using additional constraints to
68       check the data is encouraged.
69
70   FV_eq_with
71         use Data::FormValidator::Constraints qw( FV_eq_with );
72
73         constraint_methods => {
74           password  => FV_eq_with('password_confirm'),
75         }
76
77       Compares the current field to another field.  A constraint name of
78       "eq_with" will be set.
79
80   FV_num_values
81           use Data::FormValidator::Constraints qw ( FV_num_values );
82
83           constraint_methods => {
84               attachments => FV_num_values(4),
85           }
86
87       Checks the number of values in the array named by this param.  Note
88       that this is useful for making sure that only one value was passed for
89       a given param (by supplying a size argument of 1).  A constraint name
90       of "num_values" will be set.
91
92   FV_num_values_between
93           use Data::FormValidator::Constraints qw ( FV_num_values_between );
94
95           constraint_methods => {
96               attachments => FV_num_values_between(1,4),
97           }
98
99       Checks that the number of values in the array named by this param is
100       between the supplied bounds (inclusively).  A constraint name of
101       "num_values_between" will be set.
102
103   email
104       Checks if the email LOOKS LIKE an email address. This should be
105       sufficient 99% of the time.
106
107       Look elsewhere if you want something super fancy that matches every
108       possible variation that is valid in the RFC, or runs out and checks
109       some MX records.
110
111   state_or_province
112       This one checks if the input correspond to an american state or a
113       canadian province.
114
115   state
116       This one checks if the input is a valid two letter abbreviation of an
117       American state.
118
119   province
120       This checks if the input is a two letter Canadian province
121       abbreviation.
122
123   zip_or_postcode
124       This constraints checks if the input is an American zipcode or a
125       Canadian postal code.
126
127   postcode
128       This constraints checks if the input is a valid Canadian postal code.
129
130   zip
131       This input validator checks if the input is a valid american zipcode :
132       5 digits followed by an optional mailbox number.
133
134   phone
135       This one checks if the input looks like a phone number, (if it contains
136       at least 6 digits.)
137
138   american_phone
139       This constraints checks if the number is a possible North American
140       style of phone number : (XXX) XXX-XXXX. It has to contains 7 or more
141       digits.
142
143   cc_number
144       This constraint references the value of a credit card type field.
145
146        constraint_methods => {
147           cc_no      => cc_number({fields => ['cc_type']}),
148         }
149
150       The number is checked only for plausibility, it checks if the number
151       could be valid for a type of card by checking the checksum and looking
152       at the number of digits and the number of digits of the number.
153
154       This functions is only good at catching typos. IT DOESN'T CHECK IF
155       THERE IS AN ACCOUNT ASSOCIATED WITH THE NUMBER.
156
157   cc_exp
158       This one checks if the input is in the format MM/YY or MM/YYYY and if
159       the MM part is a valid month (1-12) and if that date is not in the
160       past.
161
162   cc_type
163       This one checks if the input field starts by M(asterCard), V(isa),
164       A(merican express) or D(iscovery).
165
166   ip_address
167       This checks if the input is formatted like a dotted decimal IP address
168       (v4).  For other kinds of IP address method, See Regexp::Common::net
169       which provides several more options. "REGEXP::COMMON SUPPORT" explains
170       how we easily integrate with Regexp::Common.
171

RENAMING BUILT-IN CONSTAINTS

173       If you'd like, you can rename any of the built-in constraints. Just
174       define the constraint_method and name in a hashref, like this:
175
176               constraint_methods => {
177                   first_names =>  {
178                       constraint_method => FV_max_length(3),
179                       name => 'custom_length',
180                   }
181               },
182

REGEXP::COMMON SUPPORT

184       Data::FormValidator also includes built-in support for using any of
185       regular expressions in Regexp::Common as named constraints. Simply use
186       the name of regular expression you want.  This works whether you want
187       to untaint the data or not. For example:
188
189        use Data::FormValidator::Constraints qw(:regexp_common);
190
191        constraint_methods => {
192           my_ip_address => FV_net_IPv4(),
193
194           # An example with parameters
195           other_ip      => FV_net_IPv4(-sep=>' '),
196        }
197
198       Notice that the routines are named with the prefix "FV_" instead of
199       "RE_" now.  This is simply a visual cue that these are slightly
200       modified versions. We've made a wrapper for each Regexp::Common routine
201       so that it can be used as a named constraint like this.
202
203       Be sure to check out the Regexp::Common syntax for how its syntax
204       works. It will make more sense to add future regular expressions to
205       Regexp::Common rather than to Data::FormValidator.
206

PROCEDURAL INTERFACE

208       You may also call these functions directly through the procedural
209       interface by either importing them directly or importing the whole
210       :validators group.  This is useful if you want to use the built-in
211       validators out of the usual profile specification interface.
212
213       For example, if you want to access the email validator directly, you
214       could either do:
215
216           use Data::FormValidator::Constraints (qw/valid_email/);
217           or
218           use Data::FormValidator::Constraints (:validators);
219
220           if (valid_email($email)) {
221             # do something with the email address
222           }
223
224       Notice that when you call validators directly, you'll need to prefix
225       the validator name with "valid_"
226
227       Each validator also has a version that returns the untainted value if
228       the validation succeeded. You may call these functions directly through
229       the procedural interface by either importing them directly or importing
230       the :matchers group. For example if you want to untaint a value with
231       the email validator directly you may:
232
233           if ($email = match_email($email)) {
234               system("echo $email");
235           }
236           else {
237               die "Unable to validate email";
238           }
239
240       Notice that when you call validators directly and want them to return
241       an untainted value, you'll need to prefix the validator name with
242       "match_"
243

WRITING YOUR OWN CONSTRAINT ROUTINES

245   New School Constraints Overview
246       This is the current recommended way to write constraints. See also "Old
247       School Constraints".
248
249       The most flexible way to create constraints to use closures-- a normal
250       seeming outer subroutine which returns a customized DFV method
251       subroutine as a result.  It's easy to do. These "constraint methods"
252       can be named whatever you like, and imported normally into the name
253       space where the profile is located.
254
255       Let's look at an example.
256
257         # Near your profile
258         # Of course, you don't have to export/import if your constraints are in the same
259         # package as the profile.
260         use My::Constraints 'coolness';
261
262         # In your profile
263         constraint_methods => {
264           email            => email(),
265           prospective_date => coolness( 40, 60,
266               {fields => [qw/personality smarts good_looks/]}
267           ),
268         }
269
270       Let's look at how this complex "coolness" constraint method works. The
271       interface asks for users to define minimum and maximum coolness values,
272       as well as declaring three data field names that we should peek into to
273       look their values.
274
275       Here's what the code might look like:
276
277         sub coolness {
278           my ($min_cool,$max_cool, $attrs) = @_;
279           my ($personality,$smarts,$looks) = @{ $attrs->{fields} } if $attrs->{fields};
280           return sub {
281               my $dfv = shift;
282
283               # Name it to refer to in the 'msgs' system.
284               $dfv->name_this('coolness');
285
286               # value of 'prospective_date' parameter
287               my $val = $dfv->get_current_constraint_value();
288
289               # get other data to refer to
290               my $data = $dfv->get_filtered_data;
291
292               my $has_all_three = ($data->{$personality} && $data->{$smarts} && $data->{$looks});
293               return ( ($val >= $min_cool) && ($val <= $max_cool) && $has_all_three );
294           }
295         }
296
297   Old School Constraints
298       Here is documentation on how old school constraints are created. These
299       are supported, but the new school style documented above is
300       recommended.
301
302       See also the "validator_packages" option in the input profile, for
303       loading sets of old school constraints from other packages.
304
305       Old school constraint routines are named two ways. Some are named with
306       the prefix "match_" while others start with "valid_". The difference is
307       that the "match_" routines are built to untaint the data and return a
308       safe version of it if it validates, while "valid_" routines simply
309       return a true value if the validation succeeds and false otherwise.
310
311       It is preferable to write "match_" routines that untaint data for the
312       extra security benefits. Plus, Data::FormValidator will AUTOLOAD a
313       "valid_" version if anyone tries to use it, so you only need to write
314       one routine to cover both cases.
315
316       Usually constraint routines only need one input, the value being
317       specified.  However, sometimes more than one value is needed.
318
319       Example:
320
321               image_field  => {
322                   constraint_method  => 'max_image_dimensions',
323                   params => [\100,\200],
324               },
325
326       Using that syntax, the first parameter that will be passed to the
327       routine is the Data::FormValidator object. The remaining parameters
328       will come from the "params" array. Strings will be replaced by the
329       values of fields with the same names, and references will be passed
330       directly.
331
332       In addition to "constraint_method", there is also an even older
333       technique using the name "constraint" instead. Routines that are
334       designed to work with "constraint" don't have access to
335       Data::FormValidator object, which means users need to pass in the name
336       of the field being validated. Besides adding unnecessary syntax to the
337       user interface, it won't work in conjunction with
338       "constraint_regexp_map".
339
340   Methods available for use inside of constraints
341       A few useful methods to use on the Data::FormValidator::Results object
342       are available to you to use inside of your routine.
343
344       get_input_data()
345
346       Returns the raw input data. This may be a CGI object if that's what was
347       used in the constraint routine.
348
349       Examples:
350
351        # Raw and uncensored
352        my $data = $self->get_input_data;
353
354        # tamed to be a hashref, if it wasn't already
355        my $data = $self->get_input_data( as_hashref => 1 );
356
357       get_filtered_data()
358
359        my $data = $self->get_filtered_data;
360
361       Returns the valid filtered data as a hashref, regardless of whether it
362       started out as a CGI.pm compatible object. Multiple values are
363       expressed as array references.
364
365       get_current_constraint_field()
366
367       Returns the name of the current field being tested in the constraint.
368
369       Example:
370
371        my $field = $self->get_current_constraint_field;
372
373       This reduces the number of parameters that need to be passed into the
374       routine and allows multi-valued constraints to be used with
375       "constraint_regexp_map".
376
377       For complete examples of multi-valued constraints, see
378       Data::FormValidator::Constraints::Upload
379
380       get_current_constraint_value()
381
382       Returns the name of the current value being tested in the constraint.
383
384       Example:
385
386        my $value = $self->get_current_constraint_value;
387
388       This reduces the number of parameters that need to be passed into the
389       routine and allows multi-valued constraints to be used with
390       "constraint_regexp_map".
391
392       get_current_constraint_name()
393
394       Returns the name of the current constraint being applied
395
396       Example:
397
398        my $value = $self->get_current_constraint_name;
399
400       This is useful for building a constraint on the fly based on its name.
401       It's used internally as part of the interface to the Regexp::Commmon
402       regular expressions.
403
404       untainted_constraint_value()
405
406          return $dfv->untainted_constraint_value($match);
407
408       If you have written a constraint which untaints, use this method to
409       return the untainted result. It will prepare the right result whether
410       the user has requested untainting or not.
411
412       name_this()
413
414       set_current_constraint_name()
415
416       Sets the name of the current constraint being applied.
417
418       Example:
419
420        sub my_constraint {
421           my @outer_params = @_;
422           return sub {
423               my $dfv = shift;
424               $dfv->set_current_constraint_name('my_constraint');
425               my @params = @outer_params;
426               # do something constraining here...
427           }
428        }
429
430       By returning a closure which uses this method,  you can build an
431       advanced named constraint in your profile, before you actually have
432       access to the DFV object that will be used later. See
433       Data::FormValidator::Constraints::Upload for an example.
434
435       "name_this" is a provided as a shorter synonym.
436
437       The meta() method may also be useful to communicate meta data that may
438       have been found. See Data::FormValidator::Results for documentation of
439       that method.
440

BACKWARDS COMPATIBILITY

442       Prior to Data::FormValidator 4.00, constraints were specified a bit
443       differently.  This older style is still supported.
444
445       It was not necessary to explicitly load some constraints into your name
446       space, and the names were given as strings, like this:
447
448           constraints  => {
449               email         => 'email',
450               fax           => 'american_phone',
451               phone         => 'american_phone',
452               state         => 'state',
453               my_ip_address => 'RE_net_IPv4',
454               other_ip => {
455                   constraint => 'RE_net_IPv4',
456                   params => [ \'-sep'=> \' ' ],
457               },
458               my_cc_no      => {
459                   constraint => 'cc_number',
460                   params => [qw/cc_no cc_type/],
461               }
462           },
463

CREDITS

490       Some of those input validation functions have been taken from MiniVend
491       by Michael J. Heins
492
493       The credit card checksum validation was taken from contribution by
494       Bruce Albrecht to the MiniVend program.
495

AUTHORS

497           Francis J. Lacoste
498           Michael J. Heins
499           Bruce Albrecht
500           Mark Stosberg
501

COPYRIGHT

503       Copyright (c) 1999 iNsu Innovations Inc.  All rights reserved.
504
505       Parts Copyright 1996-1999 by Michael J. Heins Parts Copyright 1996-1999
506       by Bruce Albrecht Parts Copyright 2005-2009 by Mark Stosberg
507
508       This program is free software; you can redistribute it and/or modify it
509       under the terms as perl itself.
510
511
512
513perl v5.36.0                      2023-01-20Data::FormValidator::Constraints(3)