FV_length_between(1,23)

FV_max_length(23)

FV_min_length(1)

  use Data::FormValidator::Constraints qw(
    FV_length_between
    FV_min_length
    FV_max_length
  );

  constraint_methods => {

    # specify a min and max, inclusive
    last_name        => FV_length_between(1,23),

  }

Specify a length constraint for a field.

These constraints have a different naming convention because they are higher-order functions. They take input and return a code reference to a standard constraint method. A constraint name of "length_between", "min_length", or "max_length" will be set, corresponding to the function name you choose.

The checks are all inclusive, so a max length of '100' will allow the length 100.

Length is measured in perl characters as opposed to bytes or anything else.

This constraint will untaint your data if you have untainting turned on. However, a length check alone may not be enough to insure the safety of the data you are receiving. Using additional constraints to check the data is encouraged.

FV_eq_with

  use Data::FormValidator::Constraints qw( FV_eq_with );

  constraint_methods => {
    password  => FV_eq_with('password_confirm'),
  }

Compares the current field to another field. A constraint name of "eq_with" will be set.

FV_num_values

    use Data::FormValidator::Constraints qw ( FV_num_values );

    constraint_methods => {
        attachments => FV_num_values(4),
    }

Checks the number of values in the array named by this param. Note that this is useful for making sure that only one value was passed for a given param (by supplying a size argument of 1). A constraint name of "num_values" will be set.

FV_num_values_between

    use Data::FormValidator::Constraints qw ( FV_num_values_between );

    constraint_methods => {
        attachments => FV_num_values_between(1,4),
    }

Checks that the number of values in the array named by this param is between the supplied bounds (inclusively). A constraint name of "num_values_between" will be set.

email

Look elsewhere if you want something super fancy that matches every possible variation that is valid in the RFC, or runs out and checks some MX records.

state_or_province

state

province

zip_or_postcode

postcode

zip

phone

american_phone

cc_number

 constraint_methods => {
    cc_no      => cc_number({fields => ['cc_type']}),
  }

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 catching typos. IT DOESN'T CHECK IF THERE IS AN ACCOUNT ASSOCIATED WITH THE NUMBER.

cc_exp

cc_type

ip_address

New School Constraints Overview

The most flexible way to create constraints to use closures-- a normal seeming outer subroutine which returns a customized DFV method subroutine as a result. It's easy to do. These "constraint methods" can be named whatever you like, and imported normally into the name space where the profile is located.

Let's look at an example.

  # Near your profile
  # Of course, you don't have to export/import if your constraints are in the same
  # package as the profile.
  use My::Constraints 'coolness';

  # In your profile
  constraint_methods => {
    email            => email(),
    prospective_date => coolness( 40, 60,
        {fields => [qw/personality smarts good_looks/]}
    ),
  }

Let's look at how this complex "coolness" constraint method works. The interface asks for users to define minimum and maximum coolness values, as well as declaring three data field names that we should peek into to look their values.

Here's what the code might look like:

  sub coolness {
    my ($min_cool,$max_cool, $attrs) = @_;
    my ($personality,$smarts,$looks) = @{ $attrs->{fields} } if $attrs->{fields};
    return sub {
        my $dfv = shift;

        # Name it to refer to in the 'msgs' system.
        $dfv->name_this('coolness');

        # value of 'prospective_date' parameter
        my $val = $dfv->get_current_constraint_value();

        # get other data to refer to
        my $data = $dfv->get_filtered_data;

        my $has_all_three = ($data->{$personality} && $data->{$smarts} && $data->{$looks});
        return ( ($val >= $min_cool) && ($val <= $max_cool) && $has_all_three );
    }
  }

Old School Constraints

See also the "validator_packages" option in the input profile, for loading sets of old school constraints from other packages.

Old school 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.

Example:

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

Using that 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 even 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".

Methods available for use inside of constraints

get_input_data()

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

Examples:

 # Raw and uncensored
 my $data = $self->get_input_data;

 # tamed to be a hashref, if it wasn't already
 my $data = $self->get_input_data( as_hashref => 1 );

get_filtered_data()

 my $data = $self->get_filtered_data;

Returns the valid filtered data as a hashref, regardless of whether it started out as a CGI.pm compatible object. Multiple values are expressed as array references.

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 Data::FormValidator::Constraints::Upload

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 its name. It's used internally as part of the interface to the Regexp::Commmon regular expressions.

untainted_constraint_value()

   return $dfv->untainted_constraint_value($match);

If you have written a constraint which untaints, use this method to return the untainted result. It will prepare the right result whether the user has requested untainting or not.

name_this()

set_current_constraint_name()

Sets the name of the current constraint being applied.

Example:

 sub my_constraint {
    my @outer_params = @_;
    return sub {
        my $dfv = shift;
        $dfv->set_current_constraint_name('my_constraint');
        my @params = @outer_params;
        # do something constraining here...
    }
 }

By returning a closure which uses this method, you can build an advanced named constraint in your profile, before you actually have access to the DFV object that will be used later. See Data::FormValidator::Constraints::Upload for an example.

"name_this" is a provided as a shorter synonym.

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

Constraints available in other modules

Data::FormValidator::Constraints::Upload - validate the bytes, format and dimensions of file uploads

Data::FormValidator::Constraints::DateTime - A newer DateTime constraint module. May save you a step of transforming the date into a more useful format after it's validated.

Data::FormValidator::Constraints::Dates - the original DFV date constraint module. Try the newer one first!

Data::FormValidator::Constraints::Japanese - Japan-specific constraints

Data::FormValidator::Constraints::MethodsFactory - a useful collection of tools generate more complex constraints. Recommended!

Related modules in this package

Data::FormValidator::Filters - transform data before constraints are applied

Data::FormValidator::ConstraintsFactory - This is a historical collection of constraints that suffer from cumbersome names. They are worth reviewing though-- "make_and_constraint" will allow one to validate against a list of constraints and shortcircuit if the first one fails. That's perfect if the second constraint depends on the first one having passed. For a modern version of this toolkit, see Data::FormValidator::Constraints::MethodsFactory.

Data::FormValidator