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

NAME
SYNOPSIS
DESCRIPTION
REGEXP::COMMON SUPPORT
PROCEDURAL INTERFACE
WRITING YOUR OWN CONSTRAINT ROUTINES
SEE ALSO
CREDITS
AUTHORS
COPYRIGHT

NAME

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

SYNOPSIS

In an Data::FormValidator profile:

    constraints  =>
        {
            email       => "email",
            fax         => "american_phone",
            phone       => "american_phone",
            state       => "state",
        },

DESCRIPTION

Those are the builtin constraints that can be specified by name in the input profiles.

email

Checks if the email LOOKS LIKE an email address. This checks if the input contains one @, and a two level domain name. The address portion is checked quite liberally. For example, all those probably invalid address would pass the test :

    nobody@top.domain
    %?&/$()@nowhere.net
    guessme@guess.m

state_or_province

This one checks if the input correspond to an american state or a canadian province.

state

This one checks if the input is a valid two letter abbreviation of an american state.

province

This checks if the input is a two letter canadian province abbreviation.

zip_or_postcode

This constraints checks if the input is an american zipcode or a canadian postal code.

postcode

This constraints checks if the input is a valid Canadian postal code.

zip

This input validator checks if the input is a valid american zipcode : 5 digits followed by an optional mailbox number.

phone

This one checks if the input looks like a phone number, (if it contains at least 6 digits.)

american_phone

This constraints checks if the number is a possible North American style of phone number : (XXX) XXX-XXXX. It has to contains 7 or more digits.

cc_number

This is takes two parameters, the credit card number and the credit cart type. You should take the hash reference option for using that constraint.

The number is checked only for plausibility, it checks if the number could be valid for a type of card by checking the checksum and looking at the number of digits and the number of digits of the number.

This functions is only good at weeding typos and such. IT DOESN'T CHECK IF THERE IS AN ACCOUNT ASSOCIATED WITH THE NUMBER.

cc_exp

This one checks if the input is in the format MM/YY or MM/YYYY and if the MM part is a valid month (1-12) and if that date is not in the past.

cc_type

This one checks if the input field starts by M(asterCard), V(isa), A(merican express) or D(iscovery).

ip_address

This checks if the input is formatted like an IP address (v4)

REGEXP::COMMON SUPPORT

Data::FormValidator also includes built-in support for using any of regular expressions in the Regexp::Common manpage as named constraints. Simply use the name of regular expression you want. This works whether you want to untaint the data or not. For example:

 constraints => {
        my_ip_address => 'RE_net_IPv4',
 }

Some Regexp::Common regular expressions support additional flags that are expected to be passed into the routine as arguments. We support this as well. Just use hash style method of declaring a constraint, and the params key:

 constraints => {
        my_ip_address => {
                constraint => 'RE_net_IPv4',
                params => [ \'-sep'=> \' ' ],
        }
 }

Yes, it's a bit strange that you have pass the values to param by reference using the backslash (``\''). This is necessary to preserve some important backward compatibility that I haven't figured out how to work around yet.

Be sure to check out the the Regexp::Common manpage syntax for how its syntax works. It will make more sense to add future regular expressions to Regexp::Common rather than to Data::FormValidator.

PROCEDURAL INTERFACE

You may also call these functions directly through the procedural interface by either importing them directly or importing the whole :validators group. This is useful if you want to use the built-in validators out of the usual profile specification interface.

For example, if you want to access the email validator directly, you could either do:

    use Data::FormValidator::Constraints (qw/valid_email/);
    or
    use Data::FormValidator::Constraints (:validators);

    if (valid_email($email)) {
      # do something with the email address
    }

Notice that when you call validators directly, you'll need to prefix the validator name with ``valid_''

Each validator also has a version that returns the untainted value if the validation succeeded. You may call these functions directly through the procedural interface by either importing them directly or importing the :matchers group. For example if you want to untaint a value with the email validator directly you may:

    if ($email = match_email($email)) {
        system("echo $email");
    }
    else {
        die "Unable to validate email";
    }

Notice that when you call validators directly and want them to return an untainted value, you'll need to prefix the validator name with ``match_''

WRITING YOUR OWN CONSTRAINT ROUTINES

It's easy to create your own module of constraint routines. The easiest approach to this may be to check the source code of the Data::FormValidator module for example syntax. Also notice the validator_packages option in the input profile.

You will find that constraint routines are named two ways. Some are named with the prefix match_ while others start with valid_. The difference is that the match_ routines are built to untaint the data and return a safe version of it if it validates, while valid_ routines simply return a true value if the validation succeeds and false otherwise.

It is preferable to write match_ routines that untaint data for the extra security benefits. Plus, Data::FormValidator will AUTOLOAD a valid_ version if anyone tries to use it, so you only need to write one routine to cover both cases.

Usually constraint routines only need one input, the value being specified. However, sometimes more than one value is needed. For that, the following syntax is recommended for calling the routines:

Example:

                image_field  => {  
                        constraint_method  => 'max_image_dimensions',
                        params => [\100,\200],
                },

Using this syntax, the first parameter that will be passed to the routine is the Data::FormValidator object. The remaining parameters will come from the params array. Strings will be replaced by the values of fields with the same names, and references will be passed directly.

In addition to constraint_method, there is also an older technique using the name constraint instead. Routines that are designed to work with constraint don't have access to Data::FormValidator object, which means users need to pass in the name of the field being validated. Besides adding unnecessary syntax to the user interface, it won't work in conjunction with constraint_regexp_map.

A few useful methods to use on the Data::FormValidator::Results object are available to you to use inside of your routine.

get_input_data

Returns the raw input data. This may be a CGI object if that's what was used in the constraint routine.

Example

 my $data = $self->get_input_data;

get_current_constraint_field

Returns the name of the current field being tested in the constraint.

Example:

 my $field = $self->get_current_constraint_field;

This reduces the number of parameters that need to be passed into the routine and allows multi-valued constraints to be used with constraint_regexp_map.

For complete examples of multi-valued constraints, see the Data::FormValidator::Constraints::Upload manpage

get_current_constraint_value

Returns the name of the current value being tested in the constraint.

Example:

 my $value = $self->get_current_constraint_value;

This reduces the number of parameters that need to be passed into the routine and allows multi-valued constraints to be used with constraint_regexp_map.

get_current_constraint_name

Returns the name of the current constraint being applied

Example:

 my $value = $self->get_current_constraint_name;

This is useful for building a constraint on the fly based on it's name. It's used internally as part of the interface to the the Regexp::Commmon manpage regular expressions.

The meta() method may also be useful to communicate meta data that may have been found. See the Data::FormValidator::Results manpage for documentation of that method.

CREDITS

Some of those input validation functions have been taken from MiniVend by Michael J. Heins <mike@heins.net>

The credit card checksum validation was taken from contribution by Bruce Albrecht <bruce.albrecht@seag.fingerhut.com> to the MiniVend program.

AUTHORS

    Francis J. Lacoste <francis.lacoste@iNsu.COM>
    Michael J. Heins <mike@heins.net>
    Bruce Albrecht  <bruce.albrecht@seag.fingerhut.com>

COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the terms as perl itself.

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