1Data::FormValidator(3)User Contributed Perl DocumentationData::FormValidator(3)
2
3
4

NAME

6       Data::FormValidator - Validates user input (usually from an HTML form)
7       based on input profile.
8

SYNOPSIS

10        use Data::FormValidator;
11
12        my $results = Data::FormValidator->check(\%input_hash, \%dfv_profile);
13
14        if ($results->has_invalid or $results->has_missing) {
15            # do something with $results->invalid, $results->missing
16            # or  $results->msgs
17        }
18        else {
19            # do something with $results->valid
20        }
21

DESCRIPTION

23       Data::FormValidator's main aim is to make input validation expressible
24       in a simple format.
25
26       Data::FormValidator lets you define profiles which declare the required
27       and optional fields and any constraints they might have.
28
29       The results are provided as an object, which makes it easy to handle
30       missing and invalid results, return error messages about which
31       constraints failed, or process the resulting valid data.
32

VALIDATING INPUT

34   check()
35        my $results = Data::FormValidator->check(\%input_hash, \%dfv_profile);
36
37       "check" is the recommended method to use to validate forms. It returns
38       its results as a Data::FormValidator::Results object.  A deprecated
39       method "validate" described below is also available, returning its
40       results as an array.
41
42        use Data::FormValidator;
43        my $results = Data::FormValidator->check(\%input_hash, \%dfv_profile);
44
45       Here, check() is used as a class method, and takes two required
46       parameters.
47
48       The first a reference to the data to be be validated. This can either
49       be a hash reference, or a CGI.pm-like object. In particular, the object
50       must have a param() method that works like the one in CGI.pm does.
51       CGI::Simple and Apache::Request objects are known to work in
52       particular. Note that if you use a hash reference, multiple values for
53       a single key should be presented as an array reference.
54
55       The second argument is a reference to the profile you are validating.
56
57   validate()
58           my( $valids, $missings, $invalids, $unknowns ) =
59               Data::FormValidator->validate( \%input_hash, \%dfv_profile);
60
61       validate() provides a deprecated alternative to check(). It has the
62       same input syntax, but returns a four element array, described as
63       follows
64
65       valids
66           This is a hash reference to the valid fields which were submitted
67           in the data. The data may have been modified by the various filters
68           specified.
69
70       missings
71           This is a reference to an array which contains the name of the
72           missing fields. Those are the fields that the user forget to fill
73           or filled with spaces. These fields may comes from the required
74           list or the dependencies list.
75
76       invalids
77           This is a reference to an array which contains the name of the
78           fields which failed one or more of their constraint checks. If
79           there are no invalid fields, an empty arrayref will be returned.
80
81           Fields defined with multiple constraints will have an array ref
82           returned in the @invalids array instead of a string. The first
83           element in this array is the name of the field, and the remaining
84           fields are the names of the failed constraints.
85
86       unknowns
87           This is a list of fields which are unknown to the profile. Whether
88           or not this indicates an error in the user input is application
89           dependent.
90
91   new()
92       Using new() is only needed for advanced usage, including these cases:
93
94       o   Loading more than one profile at a time. Then you can select the
95           profile you want by name later with check(). Here's an example:
96
97            my $dfv = Data::FormValidator->new({
98               profile_1 => { # usual profile definition here },
99               profile_2 => { # another profile definition },
100            });
101
102           As illustrated, multiple profiles are defined through a hash ref
103           whose keys point to profile definitions.
104
105           You can also load several profiles from a file, by defining several
106           profiles as shown above in an external file. Then just pass in the
107           name of the file:
108
109            my $dfv = Data::FormValidator->new('/path/to/profiles.pl');
110
111           If the input profile is specified as a file name, the profiles will
112           be reread each time that the disk copy is modified.
113
114           Now when calling check(), you just need to supply the profile name:
115
116            my $results = $dfv->check(\%input_hash,'profile_1');
117
118       o   Applying defaults to more than one input profile. There are some
119           parts of the validation profile that you might like to re-use for
120           many form validations.
121
122           To facilitate this, new() takes a second argument, a hash
123           reference. Here the usual input profile definitions can be made.
124           These will act as defaults for any subsequent calls to check() on
125           this object.
126
127           Currently the logic for this is very simple. Any definition of a
128           key in your validation profile will completely overwrite your
129           default value.
130
131           This means you can't define two keys for "constraint_regexp_map"
132           and expect they will always be there. This kind of feature may be
133           added in the future.
134
135           The exception here is definitions for your "msgs" key. You will
136           safely  be able to define some defaults for the top level keys
137           within "msgs" and not have them clobbered just because "msgs" was
138           defined in a validation profile.
139
140           One way to use this feature is to create your own sub-class that
141           always provides your defaults to new().
142
143           Another option is to create your own wrapper routine which provides
144           these defaults to new().  Here's an example of a routine you might
145           put in a CGI::Application super-class to make use of this feature:
146
147            # Always use the built-in CGI object as the form data
148            # and provide some defaults to new constructor
149            sub check_form {
150                my $self = shift;
151                my $profile = shift
152                   || die 'check_form: missing required profile';
153
154                require Data::FormValidator;
155                my $dfv = Data::FormValidator->new({},{
156                   # your defaults here
157                });
158                return $dfv->check($self->query,$profile);
159            }
160

INPUT PROFILE SPECIFICATION

162       An input profile is a hash reference containing one or more of the
163       following keys.
164
165       Here is a very simple input profile. Examples of more advanced options
166       are described below.
167
168           use Data::FormValidator::Constraints qw(:closures);
169
170           my $profile = {
171               optional => [qw( company
172                                fax
173                                country )],
174
175               required => [qw( fullname
176                                phone
177                                email
178                                address )],
179
180               constraint_methods => {
181                   email => email(),
182               }
183           };
184
185       That defines some fields as optional, some as required, and defines
186       that the field named 'email' must pass the constraint named 'email'.
187
188       Here is a complete list of the keys available in the input profile,
189       with examples of each.
190
191   required
192       This is an array reference which contains the name of the fields which
193       are required. Any fields in this list which are not present or contain
194       only spaces will be reported as missing.
195
196   required_regexp
197        required_regexp => qr/city|state|zipcode/,
198
199       This is a regular expression used to specify additional field names for
200       which values will be required.
201
202   require_some
203        require_some => {
204           # require any two fields from this group
205           city_or_state_or_zipcode => [ 2, qw/city state zipcode/ ],
206        }
207
208       This is a reference to a hash which defines groups of fields where 1 or
209       more fields from the group should be required, but exactly which fields
210       doesn't matter. The keys in the hash are the group names.  These are
211       returned as "missing" unless the required number of fields from the
212       group has been filled in. The values in this hash are array references.
213       The first element in this array should be the number of fields in the
214       group that is required. If the first field in the array is not an a
215       digit, a default of "1" will be used.
216
217   optional
218        optional => [qw/meat coffee chocolate/],
219
220       This is an array reference which contains the name of optional fields.
221       These are fields which MAY be present and if they are, they will be
222       checked for valid input. Any fields not in optional or required list
223       will be reported as unknown.
224
225   optional_regexp
226        optional_regexp => qr/_province$/,
227
228       This is a regular expression used to specify additional fields which
229       are optional. For example, if you wanted all fields names that begin
230       with user_ to be optional, you could use the regular expression,
231       /^user_/
232
233   dependencies
234        dependencies   => {
235
236           # If cc_no is entered, make cc_type and cc_exp required
237           "cc_no" => [ qw( cc_type cc_exp ) ],
238
239           # if pay_type eq 'check', require check_no
240           "pay_type" => {
241               check => [ qw( check_no ) ],
242            }
243
244           # if cc_type is VISA or MASTERCARD require CVV
245           "cc_type" => sub {
246               my $dfv  = shift;
247               my $type = shift;
248
249               return [ 'cc_cvv' ] if ($type eq "VISA" || $type eq "MASTERCARD");
250               return [ ];
251           },
252        },
253
254       This is for the case where an optional field has other requirements.
255       The dependent fields can be specified with an array reference.
256
257       If the dependencies are specified with a hash reference then the
258       additional constraint is added that the optional field must equal a key
259       for the dependencies to be added.
260
261       If the dependencies are specified as a code reference then the code
262       will be executed to determine the dependent fields.  It is passed two
263       parameters, the object and the value of the field, and it should return
264       an array reference containing the list of dependent fields.
265
266       Any fields in the dependencies list that are missing when the target is
267       present will be reported as missing.
268
269   dependency_groups
270        dependency_groups  => {
271            # if either field is filled in, they all become required
272            password_group => [qw/password password_confirmation/],
273        }
274
275       This is a hash reference which contains information about groups of
276       interdependent fields. The keys are arbitrary names that you create and
277       the values are references to arrays of the field names in each group.
278
279   dependencies_regexp
280        dependencies_regexp => {
281           qr/Line\d+\_ItemType$/ => sub {
282              my $dfv = shift;
283              my $itemtype = shift;
284              my $field = shift;
285
286              if ($type eq 'NeedsBatteries') {
287                 my ($prefix, $suffix) = split(/\_/, $field);
288
289                 return([$prefix . '_add_batteries]);
290              } else {
291                 return([]);
292              }
293           },
294        },
295
296       This is a regular expression used to specify additional fields which
297       are dependent. For example, if you wanted to add dependencies for all
298       fields which meet a certain criteria (such as multiple items in a
299       shopping cart) where you do not know before hand how many of such
300       fields you may have.
301
302   dependent_optionals
303        dependent_optionals => {
304           # If delivery_address is specified then delivery_notes becomes optional
305           "delivery_address" => [ qw( delivery_notes ) ],
306
307           # if delivery_type eq 'collection', collection_notes becomes optional
308           "delivery_type" => {
309              collection => [ qw( collection_notes ) ],
310           }
311
312           # if callback_type is "phone" or "email" then additional_notes becomes optional
313           "callback_type" => sub {
314              my $dfv = shift;
315              my $type = shift;
316
317              if ($type eq 'phone' || $type eq 'email') {
318                 return(['additional_notes']);
319              } else {
320                 return([]);
321              }
322           },
323        },
324
325       This is for the case where an optional field can trigger other optional
326       fields.  The dependent optional fields can be specified with an array
327       reference.
328
329       If the dependent optional fields are specified with a hash reference,
330       then an additional constraint is added that the optional field must
331       equal a key for the additional optional fields to be added.
332
333       If the dependent optional fields are specified as a code reference then
334       the code will be executed to determine the additional optional fields.
335       It is passed two parameters, the object and the value of the field, and
336       it should return an array reference containing the list of additional
337       optional fields.
338
339   dependent_require_some
340        dependent_require_some => {
341           # require any fields from this group if AddressID is "new"
342           AddressID => sub {
343              my $dfv = shift;
344              my $value = shift;
345
346              if ($value eq 'new') {
347                 return({
348                    house_name_or_number => [ 1, 'HouseName', 'HouseNumber' ],
349                 });
350              } else {
351                 return;
352              }
353           },
354        }
355
356       Sometimes a field will need to trigger additional dependencies but you
357       only require some of the fields. You cannot set them all to be
358       dependent as you might only have some of them, and you cannot set them
359       all to be optional as you must have some of them. This method allows
360       you to specify this in a similar way to the equire_some method but
361       dependent upon other values. In the example above if the AddressID
362       submitted is "new" then at least 1 of HouseName and HouseNumber must
363       also be supplied. See require_some for the valid options for the
364       return.
365
366   defaults
367        defaults => {
368            country => "USA",
369        },
370
371       This is a hash reference where keys are field names and values are
372       defaults to use if input for the field is missing.
373
374       The values can be code refs which will be used to calculate the value
375       if needed. These code refs will be passed in the DFV::Results object as
376       the only parameter.
377
378       The defaults are set shortly before the constraints are applied, and
379       will be returned with the other valid data.
380
381   defaults_regexp_map
382         defaults_regexp_map => {
383             qr/^opt_/ => 1,
384         },
385
386       This is a hash reference that maps  regular expressions to default
387       values to use for matching optional or required fields.
388
389       It's useful if you have generated many checkbox fields with the similar
390       names.  Since checkbox fields submit nothing at all when they are not
391       checked, it's useful to set defaults for them.
392
393       Note that it doesn't make sense to use a default for a field handled by
394       "optional_regexp" or "required_regexp".  When the field is not
395       submitted, there is no way to know that it should be optional or
396       required, and thus there's no way to know that a default should be set
397       for it.
398
399   filters
400        # trim leading and trailing whitespace on all fields
401        filters       => ['trim'],
402
403       This is a reference to an array of filters that will be applied to ALL
404       optional and required fields, before any constraints are applied.
405
406       This can be the name of a built-in filter (trim,digit,etc) or an
407       anonymous subroutine which should take one parameter, the field value
408       and return the (possibly) modified value.
409
410       Filters modify the data returned through the results object, so use
411       them carefully.
412
413       See Data::FormValidator::Filters for details on the built-in filters.
414
415   field_filters
416        field_filters => {
417            cc_no => ['digit'],
418        },
419
420       A hash ref with field names as keys. Values are array references of
421       built-in filters to apply (trim,digit,etc) or an anonymous subroutine
422       which should take one parameter, the field value and return the
423       (possibly) modified value.
424
425       Filters are applied before any constraints are applied.
426
427       See Data::FormValidator::Filters for details on the built-in filters.
428
429   field_filter_regexp_map
430        field_filter_regexp_map => {
431            # Upper-case the first letter of all fields that end in "_name"
432            qr/_name$/    => ['ucfirst'],
433        },
434
435       'field_filter_regexp_map' is used to apply filters to fields that match
436       a regular expression.  This is a hash reference where the keys are the
437       regular expressions to use and the values are references to arrays of
438       filters which will be applied to specific input fields. Just as with
439       'field_filters', you can you use a built-in filter or use a coderef to
440       supply your own.
441
442   constraint_methods
443        use Data::FormValidator::Constraints qw(:closures);
444
445        constraint_methods => {
446           cc_no      => cc_number({fields => ['cc_type']}),
447           cc_type    => cc_type(),
448           cc_exp     => cc_exp(),
449         },
450
451       A hash ref which contains the constraints that will be used to check
452       whether or not the field contains valid data.
453
454       Note: To use the built-in constraints, they need to first be loaded
455       into your name space using the syntax above. (Unless you are using the
456       old "constraints" key, documented in "BACKWARDS COMPATIBILITY").
457
458       The keys in this hash are field names. The values can be any of the
459       following:
460
461       o   A named constraint.
462
463           Example:
464
465            my_zipcode_field     => zip(),
466
467           See Data::FormValidator::Constraints for the details of which
468           built-in constraints that are available.
469
470       o   A perl regular expression
471
472           Example:
473
474            my_zipcode_field   => qr/^\d{5}$/, # match exactly 5 digits
475
476           If this field is named in "untaint_constraint_fields" or
477           "untaint_regexp_map", or "untaint_all_constraints" is effective, be
478           aware of the following: If you write your own regular expressions
479           and only match part of the string then you'll only get part of the
480           string in the valid hash. It is a good idea to write you own
481           constraints like /^regex$/. That way you match the whole string.
482
483       o   a subroutine reference, to supply custom code
484
485           This will check the input and return true or false depending on the
486           input's validity.  By default, the constraint function receives a
487           Data::FormValidator::Results object as its first argument, and the
488           value to be validated as the second.  To validate a field based on
489           more inputs than just the field itself, see "VALIDATING INPUT BASED
490           ON MULTIPLE FIELDS".
491
492           Examples:
493
494            # Notice the use of 'pop'--
495            # the object is the first arg passed to the method
496            # while the value is the second, and last arg.
497            my_zipcode_field => sub { my $val = pop;  return $val =~ '/^\d{5}$/' },
498
499            # OR you can reference a subroutine, which should work like the one above
500            my_zipcode_field => \&my_validation_routine,
501
502            # An example of setting the constraint name.
503            my_zipcode_field => sub {
504               my ($dfv, $val) = @_;
505               $dfv->set_current_constraint_name('my_constraint_name');
506               return $val =~ '/^\d{5}$/'
507            },
508
509       o   an array reference
510
511           An array reference is used to apply multiple constraints to a
512           single field. Any of the above options are valid entries the array.
513           See "MULTIPLE CONSTRAINTS" below.
514
515           For more details see "VALIDATING INPUT BASED ON MULTIPLE FIELDS".
516
517   constraint_method_regexp_map
518        use Data::FormValidator::Constraints qw(:closures);
519
520        # In your profile.
521        constraint_method_regexp_map => {
522            # All fields that end in _postcode have the 'postcode' constraint applied.
523            qr/_postcode$/    => postcode(),
524        },
525
526       A hash ref where the keys are the regular expressions to use and the
527       values are the constraints to apply.
528
529       If one or more constraints have already been defined for a given field
530       using "constraint_methods", "constraint_method_regexp_map" will add an
531       additional constraint for that field for each regular expression that
532       matches.
533
534   untaint_all_constraints
535        untaint_all_constraints => 1,
536
537       If this field is set, all form data that passes a constraint will be
538       untainted.  The untainted data will be returned in the valid hash.
539       Untainting is based on the pattern match used by the constraint.  Note
540       that some constraint routines may not provide untainting.
541
542       See Writing your own constraint routines for more information.
543
544       This is overridden by "untaint_constraint_fields" and
545       "untaint_regexp_map".
546
547   untaint_constraint_fields
548        untaint_constraint_fields => [qw(zipcode state)],
549
550       Specifies that one or more fields will be untainted if they pass their
551       constraint(s). This can be set to a single field name or an array
552       reference of field names. The untainted data will be returned in the
553       valid hash.
554
555       This overrides the untaint_all_constraints flag.
556
557   untaint_regexp_map
558        untaint_regexp_map => [qr/some_field_\d/],
559
560       Specifies that certain fields will be untainted if they pass their
561       constraints and match one of the regular expressions supplied. This can
562       be set to a single regex, or an array reference of regexes. The
563       untainted data will be returned in the valid hash.
564
565       The above example would untaint the fields named "some_field_1", and
566       "some_field_2" but not "some_field".
567
568       This overrides the untaint_all_constraints flag.
569
570   missing_optional_valid
571        missing_optional_valid => 1
572
573       This can be set to a true value to cause optional fields with empty
574       values to be included in the valid hash. By default they are not
575       included-- this is the historical behavior.
576
577       This is an important flag if you are using the contents of an "update"
578       form to update a record in a database. Without using the option, fields
579       that have been set back to "blank" may fail to get updated.
580
581   validator_packages
582        # load all the constraints and filters from these modules
583        validator_packages => [qw(Data::FormValidator::Constraints::Upload)],
584
585       This key is used to define other packages which contain constraint
586       routines or filters.  Set this key to a single package name, or an
587       arrayref of several. All of its constraint and filter routines
588       beginning with 'match_', 'valid_' and 'filter_' will be imported into
589       Data::FormValidator.  This lets you reference them in a constraint with
590       just their name, just like built-in routines.  You can even override
591       the provided validators.
592
593       See Writing your own constraint routines documentation for more
594       information
595
596   msgs
597       This key is used to define parameters related to formatting error
598       messages returned to the user.
599
600       By default, invalid fields have the message "Invalid" associated with
601       them while missing fields have the message "Missing" associated with
602       them.
603
604       In the simplest case, nothing needs to be defined here, and the default
605       values will be used.
606
607       The default formatting applied is designed for display in an XHTML web
608       page.  That formatting is as followings:
609
610           <span style="color:red;font-weight:bold" class="dfv_errors">* %s</span>
611
612       The %s will be replaced with the message. The effect is that the
613       message will appear in bold red with an asterisk before it. This style
614       can be overridden by simply defining "dfv_errors" appropriately in a
615       style sheet, or by providing a new format string.
616
617       Here's a more complex example that shows how to provide your own
618       default message strings, as well as providing custom messages per
619       field, and handling multiple constraints:
620
621        msgs => {
622
623            # set a custom error prefix, defaults to none
624            prefix=> 'error_',
625
626            # Set your own "Missing" message, defaults to "Missing"
627            missing => 'Not Here!',
628
629            # Default invalid message, default's to "Invalid"
630            invalid => 'Problematic!',
631
632            # message separator for multiple messages
633            # Defaults to ' '
634            invalid_separator => ' <br /> ',
635
636            # formatting string, default given above.
637            format => 'ERROR: %s',
638
639            # Error messages, keyed by constraint name
640            # Your constraints must be named to use this.
641            constraints => {
642                            'date_and_time' => 'Not a valid time format',
643                            # ...
644            },
645
646            # This token will be included in the hash if there are
647            # any errors returned. This can be useful with templating
648            # systems like HTML::Template
649            # The 'prefix' setting does not apply here.
650            # defaults to undefined
651            any_errors => 'some_errors',
652        }
653
654       The hash that's prepared can be retrieved through the "msgs" method
655       described in the Data::FormValidator::Results documentation.
656
657   msgs - callback
658       This is a new feature. While it expected to be forward-compatible, it
659       hasn't yet received the testing the rest of the API has.
660
661       If the built-in message generation doesn't suit you, it is also
662       possible to provide your own by specifying a code reference:
663
664        msgs  =>  \&my_msgs_callback
665
666       This will be called as a Data::FormValidator::Results method.  It may
667       receive as arguments an additional hash reference of control
668       parameters, corresponding to the key names usually used in the "msgs"
669       area of the profile. You can ignore this information if you'd like.
670
671       If you have an alternative error message handler you'd like to share,
672       stick in the "Data::FormValidator::ErrMsgs" name space and upload it to
673       CPAN.
674
675   debug
676       This method is used to print details about what is going on to STDERR.
677
678       Currently only level '1' is used. It provides information about which
679       fields matched constraint_regexp_map.
680
681   A shortcut for array refs
682       A number of parts of the input profile specification include array
683       references as their values.  In any of these places, you can simply use
684       a string if you only need to specify one value. For example, instead of
685
686        filters => [ 'trim' ]
687
688       you can simply say
689
690        filters => 'trim'
691
692   A note on regular expression formats
693       In addition to using the preferred method of defining regular
694       expressions using "qr", a deprecated style of defining them as strings
695       is also supported.
696
697       Preferred:
698
699        qr/this is great/
700
701       Deprecated, but supported
702
703        'm/this still works/'
704

VALIDATING INPUT BASED ON MULTIPLE FIELDS

706       You can pass more than one value into a constraint routine.  For that,
707       the value of the constraint should be a hash reference. If you are
708       creating your own routines, be sure to read the section labeled
709       "WRITING YOUR OWN CONSTRAINT ROUTINES", in the
710       Data::FormValidator::Constraints documentation.  It describes a newer
711       and more flexible syntax.
712
713       Using the original syntax, one key should be named "constraint" and
714       should have a value set to the reference of the subroutine or the name
715       of a built-in validator.  Another required key is "params". The value
716       of the "params" key is a reference to an array of the other elements to
717       use in the validation. If the element is a scalar, it is assumed to be
718       a field name. The field is known to Data::FormValidator, the value will
719       be filtered through any defined filters before it is passed in.  If the
720       value is a reference, the reference is passed directly to the routine.
721       Don't forget to include the name of the field to check in that list, if
722       you are using this syntax.
723
724       Example:
725
726        cc_no  => {
727            constraint  => "cc_number",
728            params         => [ qw( cc_no cc_type ) ],
729        },
730

MULTIPLE CONSTRAINTS

732       Multiple constraints can be applied to a single field by defining the
733       value of the constraint to be an array reference. Each of the values in
734       this array can be any of the constraint types defined above.
735
736       When using multiple constraints it is important to return the name of
737       the constraint that failed so you can distinguish between them. To do
738       that, either use a named constraint, or use the hash ref method of
739       defining a constraint and include a "name" key with a value set to the
740       name of your constraint.  Here's an example:
741
742         my_zipcode_field => [
743             'zip',
744             {
745               constraint_method =>  '/^406/',
746               name              =>  'starts_with_406',
747             }
748         ],
749
750       You can use an array reference with a single constraint in it if you
751       just want to have the name of your failed constraint returned in the
752       above fashion.
753
754       Read about the validate() function above to see how multiple
755       constraints are returned differently with that method.
756

ADVANCED VALIDATION

758       For even more advanced validation, you will likely want to read the
759       documentation for other modules in this distribution, linked below.
760       Also keep in mind that the  Data::FormValidator profile structure is
761       just another data structure. There is no reason why it needs to be
762       defined statically. The profile could also be built on the fly with
763       custom Perl code.
764

BACKWARDS COMPATIBILITY

766   validate()
767           my( $valids, $missings, $invalids, $unknowns ) =
768               Data::FormValidator->validate( \%input_hash, \%dfv_profile);
769
770       validate() provides a deprecated alternative to check(). It has the
771       same input syntax, but returns a four element array, described as
772       follows
773
774       valids
775           This is a hash reference to the valid fields which were submitted
776           in the data. The data may have been modified by the various filters
777           specified.
778
779       missings
780           This is a reference to an array which contains the name of the
781           missing fields. Those are the fields that the user forget to fill
782           or filled with spaces. These fields may comes from the required
783           list or the dependencies list.
784
785       invalids
786           This is a reference to an array which contains the name of the
787           fields which failed one or more of their constraint checks.
788
789           Fields defined with multiple constraints will have an array ref
790           returned in the @invalids array instead of a string. The first
791           element in this array is the name of the field, and the remaining
792           fields are the names of the failed constraints.
793
794       unknowns
795           This is a list of fields which are unknown to the profile. Whether
796           or not this indicates an error in the user input is application
797           dependent.
798
799   constraints (profile key)
800       This is a supported but deprecated profile key. Using
801       "constraint_methods" is recommended instead, which provides a simpler,
802       more versatile interface.
803
804        constraints => {
805           cc_no      => {
806               constraint  => "cc_number",
807               params        => [ qw( cc_no cc_type ) ],
808           },
809           cc_type    => "cc_type",
810           cc_exp    => "cc_exp",
811         },
812
813       A hash ref which contains the constraints that will be used to check
814       whether or not the field contains valid data.
815
816       The keys in this hash are field names. The values can be any of the
817       following:
818
819       o   A named constraint.
820
821           Example:
822
823            my_zipcode_field     => 'zip',
824
825           See Data::FormValidator::Constraints for the details of which
826           built-in constraints that are available.
827
828   hashref style of specifying constraints
829       Using a hash reference to specify a constraint is an older technique
830       used to name a constraint or supply multiple parameters.
831
832       Both of these interface issues are now better addressed with
833       "constraint_methods" and "$self-\"name_this('foo')>.
834
835        # supply multiple parameters
836        cc_no  => {
837            constraint  => "cc_number",
838            params      => [ qw( cc_no cc_type ) ],
839        },
840
841        # name a constraint, useful for returning error messages
842        last_name => {
843            name => "ends_in_name",
844            constraint => qr/_name$/,
845        },
846
847       Using a hash reference for a constraint permits the passing of multiple
848       arguments. Required arguments are "constraint" or "constraint_method".
849       Optional arguments are "name" and "params".
850
851       A "name" on a constraints 'glues' the constraint to its error message
852       in the validator profile (refer "msgs" section below). If no "name" is
853       given then it will default to the value of "constraint" or
854       "constraint_method" IF they are NOT a CODE ref or a RegExp ref.
855
856       The "params" value is a reference to an array of the parameters to pass
857       to the constraint method.  If an element of the "params" list is a
858       scalar, it is assumed to be naming a key of the %input_hash and that
859       value is passed to the routine.  If the parameter is a reference, then
860       it is treated literally and passed unchanged to the routine.
861
862       If you are using the older "constraint" over the new
863       "constraint_method" then don't forget to include the name of the field
864       to check in the "params" list. "constraint_method" provides access to
865       this value via the "get_current_*" methods (refer
866       Data::FormValidator::Constraints)
867
868       For more details see "VALIDATING INPUT BASED ON MULTIPLE FIELDS".
869
870   constraint_regexp_map (profile key)
871       This is a supported but deprecated profile key. Using
872       "constraint_methods_regexp_map" is recommended instead.
873
874        constraint_regexp_map => {
875            # All fields that end in _postcode have the 'postcode' constraint applied.
876            qr/_postcode$/    => 'postcode',
877        },
878
879       A hash ref where the keys are the regular expressions to use and the
880       values are the constraints to apply.
881
882       If one or more constraints have already been defined for a given field
883       using "constraints", constraint_regexp_map will add an additional
884       constraint for that field for each regular expression that matches.
885

SEE ALSO

887       Other modules in this distribution:
888
889       Data::FormValidator::Constraints
890
891       Data::FormValidator::Constraints::Dates
892
893       Data::FormValidator::Constraints::Upload
894
895       Data::FormValidator::ConstraintsFactory
896
897       Data::FormValidator::Filters
898
899       Data::FormValidator::Results
900
901       A sample application by the maintainer:
902
903       Validating Web Forms with Perl,
904       <http://mark.stosberg.com/Tech/perl/form-validation/>
905
906       Related modules:
907
908       Data::FormValidator::Tutorial
909
910       Data::FormValidator::Util::HTML
911
912       CGI::Application::ValidateRM, a CGI::Application & Data::FormValidator
913       glue module
914
915       HTML::Template::Associate::FormValidator is designed to make some kinds
916       of integration with HTML::Template easier.
917
918       Params::Validate is useful for validating function parameters.
919
920       Regexp::Common, Data::Types, Data::Verify, Email::Valid,
921       String::Checker, CGI::ArgChecker, CGI::FormMagick::Validator,
922       CGI::Validate
923
924       Document Translations:
925
926       Japanese: <http://perldoc.jp/docs/modules/>
927
928       Distributions which include Data::FormValidator
929
930       FreeBSD includes a port named p5-Data-FormValidator
931
932       Debian GNU/Linux includes a port named libdata-formvalidator-perl
933

CREDITS

935       Some of these input validation functions have been taken from MiniVend
936       by Michael J. Heins.
937
938       The credit card checksum validation was taken from contribution by
939       Bruce Albrecht to the MiniVend program.
940

BUGS

942       Bug reports and patches are welcome. Reports which include a failing
943       Test::More style test are helpful and will receive priority.
944
945       <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Data-FormValidator>
946

CONTRIBUTING

948       This project is maintained on Github
949       <https://github.com/dnmfarrell/Data-FormValidator>.
950

AUTHOR

952       Currently maintained by David Farrell <dfarrell@cpan.org>
953
954       Parts Copyright 2001-2006 by Mark Stosberg <mark at summersault.com>,
955       (previous maintainer)
956
957       Copyright (c) 1999 Francis J. Lacoste and iNsu Innovations Inc.  All
958       rights reserved.  (Original Author)
959
960       Parts Copyright 1996-1999 by Michael J. Heins <mike@heins.net>
961
962       Parts Copyright 1996-1999 by Bruce Albrecht
963       <bruce.albrecht@seag.fingerhut.com>
964

LICENSE

966       This program is free software; you can redistribute it and/or modify it
967       under the terms as perl itself.
968
969
970
971perl v5.36.0                      2023-01-20            Data::FormValidator(3)
Impressum