phpman > perldoc > Data::FormValidator::Constraints(3pm)

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

SYNOPSIS
     use Data::FormValidator::Constraints qw(:closures);

    In an Data::FormValidator profile:

        constraint_methods => {
            email   => email(),
            phone   => american_phone(),
            first_names =>  {
               constraint_method => FV_max_length(3),
               name => 'my_custom_name',
           },
        },
        msgs => {
           constraints => {
                my_custom_name => 'My message',
           },
        },

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

    Be sure to check out the SEE ALSO section for even more pre-packaged constraints you can use.

  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
    Checks if the email LOOKS LIKE an email address. This should be sufficient 99% of the time.

    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
    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 constraint references the value of a credit card type field.

     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
    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 a dotted decimal IP address (v4). For other kinds of
    IP address method, See Regexp::Common::net which provides several more options. "REGEXP::COMMON
    SUPPORT" explains how we easily integrate with Regexp::Common.

RENAMING BUILT-IN CONSTAINTS
    If you'd like, you can rename any of the built-in constraints. Just define the constraint_method
    and name in a hashref, like this:

            constraint_methods => {
                first_names =>  {
                    constraint_method => FV_max_length(3),
                    name => 'custom_length',
                }
            },

REGEXP::COMMON SUPPORT
    Data::FormValidator also includes built-in support for using any of regular expressions in
    Regexp::Common 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:

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

     constraint_methods => {
        my_ip_address => FV_net_IPv4(),

        # An example with parameters
        other_ip      => FV_net_IPv4(-sep=>' '),
     }

    Notice that the routines are named with the prefix "FV_" instead of "RE_" now. This is simply a
    visual cue that these are slightly modified versions. We've made a wrapper for each
    Regexp::Common routine so that it can be used as a named constraint like this.

    Be sure to check out the Regexp::Common 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
  New School Constraints Overview
    This is the current recommended way to write constraints. See also "Old School Constraints".

    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
    Here is documentation on how old school constraints are created. These are supported, but the
    new school style documented above is recommended.

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

    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.

BACKWARDS COMPATIBILITY
    Prior to Data::FormValidator 4.00, constraints were specified a bit differently. This older
    style is still supported.

    It was not necessary to explicitly load some constraints into your name space, and the names
    were given as strings, like this:

        constraints  => {
            email         => 'email',
            fax           => 'american_phone',
            phone         => 'american_phone',
            state         => 'state',
            my_ip_address => 'RE_net_IPv4',
            other_ip => {
                constraint => 'RE_net_IPv4',
                params => [ \'-sep'=> \' ' ],
            },
            my_cc_no      => {
                constraint => 'cc_number',
                params => [qw/cc_no cc_type/],
            }
        },

SEE ALSO
  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

CREDITS
    Some of those input validation functions have been taken from MiniVend by Michael J. Heins

    The credit card checksum validation was taken from contribution by Bruce Albrecht to the
    MiniVend program.

AUTHORS
        Francis J. Lacoste
        Michael J. Heins
        Bruce Albrecht
        Mark Stosberg

COPYRIGHT
    Copyright (c) 1999 iNsu Innovations Inc. All rights reserved.

    Parts Copyright 1996-1999 by Michael J. Heins Parts Copyright 1996-1999 by Bruce Albrecht Parts
    Copyright 2005-2009 by Mark Stosberg

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