man > Data::FormValidator

man perldoc info pydoc3 ri search

📘 NAME

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

🚀 Quick Reference

Use Case	Command	Description
Basic validation	Data::FormValidator->check(\%input, \%profile)	🟢 Returns a Results object with has_invalid, has_missing, valid, invalid, missing
Define required fields	required => [qw/field1 field2/]	🔴 Missing fields reported
Define optional fields	optional => [qw/field1 field2/]	🟡 Only checked if submitted
Apply constraints	constraint_methods => { email => email() }	✅ Use built-in or custom constraints
Dependencies	dependencies => { "field" => [qw/dep1 dep2/] }	🔗 If field present, dependents become required
Set defaults	defaults => { country => "USA" }	📥 Missing fields get default values
Apply filters	filters => ['trim']	🧹 Pre-process all fields
Custom error messages	msgs => { invalid => 'Invalid!', constraints => { 'name' => 'msg' } }	🗣️ Override default messages
Multiple constraints per field	field => [ \&constraint1, qr/regex/ ]	🔢 Apply several checks
Untaint validated data	untaint_all_constraints => 1	🔒 Automatically untaint passed values

📖 SYNOPSIS

use Data::FormValidator;

my $results = Data::FormValidator->check(\%input_hash, \%dfv_profile);

if ($results->has_invalid or $results->has_missing) {
    # do something with $results->invalid, $results->missing
    # or  $results->msgs
}
else {
    # do something with $results->valid
}

📝 DESCRIPTION

Data::FormValidator's main aim is to make input validation expressible in a simple format. It lets you define profiles which declare the required and optional fields and any constraints they might have. The results are provided as an object, making it easy to handle missing and invalid results, return error messages, or process the valid data.

🔍 VALIDATING INPUT

✅ check()

my $results = Data::FormValidator->check(\%input_hash, \%dfv_profile);

"check" is the recommended method. It returns a Data::FormValidator::Results object. The first argument is a hash reference or a CGI-like object with a param() method. The second is a profile reference.

⚠️ validate() (deprecated)

my( $valids, $missings, $invalids, $unknowns ) =
    Data::FormValidator->validate( \%input_hash, \%dfv_profile);

Returns a four-element array:

• valids – hashref of valid fields
• missings – arrayref of missing field names
• invalids – arrayref of fields that failed constraints
• unknowns – list of fields not in profile

🔧 new()

Advanced usage – loading multiple profiles, or applying defaults. Example:

my $dfv = Data::FormValidator->new({
    profile_1 => { # usual profile definition here },
    profile_2 => { # another profile definition },
});

Then call $dfv->check(\%input, 'profile_1').

📋 INPUT PROFILE SPECIFICATION

An input profile is a hash reference containing one or more of the following keys:

🔴 required

Array reference of field names that must be present. Missing fields are reported.

🔴 required_regexp

required_regexp => qr/city|state|zipcode/,

Regular expression to specify additional required fields.

🔴 require_some

require_some => {
    city_or_state_or_zipcode => [ 2, qw/city state zipcode/ ],
}

Hash of groups where at least n fields from the group must be filled.

🟡 optional

optional => [qw/meat coffee chocolate/],

These fields MAY be present; if so, they are validated.

🟡 optional_regexp

optional_regexp => qr/_province$/,

Regex to mark additional optional fields.

🔗 dependencies

dependencies => {
    "cc_no" => [ qw( cc_type cc_exp ) ],
    "pay_type" => {
        check => [ qw( check_no ) ],
    },
    "cc_type" => sub {
        my $dfv  = shift;
        my $type = shift;
        return [ 'cc_cvv' ] if ($type eq "VISA" || $type eq "MASTERCARD");
        return [ ];
    },
},

Makes fields required when a specific optional field is present. Can be array, hash (value‑dependent), or code ref.

🔗 dependency_groups

dependency_groups => {
    password_group => [qw/password password_confirmation/],
}

If any field in the group is filled, all become required.

🔗 dependencies_regexp

dependencies_regexp => {
    qr/Line\d+\_ItemType$/ => sub {
        my $dfv = shift;
        my $itemtype = shift;
        my $field = shift;
        if ($type eq 'NeedsBatteries') {
            my ($prefix, $suffix) = split(/\_/, $field);
            return([$prefix . '_add_batteries']);
        } else {
            return([]);
        }
    },
},

Regex‑based dependencies for dynamic field names.

🟡 dependent_optionals

dependent_optionals => {
    "delivery_address" => [ qw( delivery_notes ) ],
    "delivery_type" => {
        collection => [ qw( collection_notes ) ],
    },
    "callback_type" => sub {
        my $dfv = shift;
        my $type = shift;
        if ($type eq 'phone' || $type eq 'email') {
            return(['additional_notes']);
        } else {
            return([]);
        }
    },
},

Makes optional fields conditionally required when another optional field is present.

🔗 dependent_require_some

dependent_require_some => {
    AddressID => sub {
        my $dfv = shift;
        my $value = shift;
        if ($value eq 'new') {
            return({
                house_name_or_number => [ 1, 'HouseName', 'HouseNumber' ],
            });
        } else {
            return;
        }
    },
}

Conditionally applies require_some logic based on another field's value.

📥 defaults

defaults => {
    country => "USA",
},

Default values for missing fields. Values can be code refs.

📥 defaults_regexp_map

defaults_regexp_map => {
    qr/^opt_/ => 1,
},

Set defaults for fields matching a regex (e.g., unchecked checkboxes).

🧹 filters

filters => ['trim'],

Array of filters applied to ALL optional and required fields before constraints.

🧹 field_filters

field_filters => {
    cc_no => ['digit'],
},

Per‑field filters.

🧹 field_filter_regexp_map

field_filter_regexp_map => {
    qr/_name$/ => ['ucfirst'],
},

Apply filters to fields matching a regex.

✅ constraint_methods

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

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

Hash ref of field names to constraints. Values can be:

• Named constraint (e.g., zip())
• Regex (qr/^\d{5}$/)
• Subroutine reference
• Array reference for multiple constraints

✅ constraint_method_regexp_map

constraint_method_regexp_map => {
    qr/_postcode$/ => postcode(),
},

Apply constraints to fields matching a regex.

🔒 untaint_all_constraints

untaint_all_constraints => 1,

Untaint all data that passes constraints.

🔒 untaint_constraint_fields

untaint_constraint_fields => [qw(zipcode state)],

Untaint specific fields.

🔒 untaint_regexp_map

untaint_regexp_map => [qr/some_field_\d/],

Untaint fields matching a regex.

🟢 missing_optional_valid

missing_optional_valid => 1

Include optional fields with empty values in the valid hash.

📦 validator_packages

validator_packages => [qw(Data::FormValidator::Constraints::Upload)],

Load additional constraint and filter packages.

🗣️ msgs

msgs => {
    prefix => 'error_',
    missing => 'Not Here!',
    invalid => 'Problematic!',
    invalid_separator => ' <br /> ',
    format => 'ERROR: %s',
    constraints => {
        'date_and_time' => 'Not a valid time format',
    },
    any_errors => 'some_errors',
}

Custom error message formatting. Also supports a callback: msgs => \&my_msgs_callback.

🐛 debug

debug => 1,

Prints debug info to STDERR.

📌 A shortcut for array refs

Where an array ref is expected, you can use a single string: filters => 'trim' instead of filters => ['trim'].

📌 A note on regular expression formats

Both qr// and deprecated string style ('m/.../') are supported.

🔗 VALIDATING INPUT BASED ON MULTIPLE FIELDS

To pass multiple values to a constraint, use a hash reference:

cc_no => {
    constraint  => "cc_number",
    params      => [ qw( cc_no cc_type ) ],
},

See Data::FormValidator::Constraints for the newer syntax.

🔢 MULTIPLE CONSTRAINTS

Use an array reference to apply multiple constraints to a single field:

my_zipcode_field => [
    'zip',
    {
        constraint_method => '/^406/',
        name              => 'starts_with_406',
    }
],

Each can be a named constraint, regex, or subroutine. Use name to distinguish failures.

🧠 ADVANCED VALIDATION

See other modules in the distribution. Profiles can be built dynamically with Perl code.

🔄 BACKWARDS COMPATIBILITY

⚠️ validate()

Deprecated alternative to check(). Returns four array elements as described previously.

📌 constraints (profile key)

Deprecated – use constraint_methods instead.

constraints => {
    cc_no => {
        constraint  => "cc_number",
        params      => [ qw( cc_no cc_type ) ],
    },
    cc_type => "cc_type",
    cc_exp  => "cc_exp",
},

📌 Hashref style of specifying constraints

Older technique for naming constraints or supplying multiple parameters:

cc_no => {
    constraint  => "cc_number",
    params      => [ qw( cc_no cc_type ) ],
},

last_name => {
    name => "ends_in_name",
    constraint => qr/_name$/,
},

📌 constraint_regexp_map (profile key)

Deprecated – use constraint_methods_regexp_map.

constraint_regexp_map => {
    qr/_postcode$/ => 'postcode',
},

📚 SEE ALSO

📦 Other modules in this distribution:

• Data::FormValidator::Constraints
• Data::FormValidator::Constraints::Dates
• Data::FormValidator::Constraints::Upload
• Data::FormValidator::ConstraintsFactory
• Data::FormValidator::Filters
• Data::FormValidator::Results

🌐 A sample application by the maintainer:

Validating Web Forms with Perl, http://mark.stosberg.com/Tech/perl/form-validation/

🔗 Related modules:

• Data::FormValidator::Tutorial
• Data::FormValidator::Util::HTML
• CGI::Application::ValidateRM
• HTML::Template::Associate::FormValidator
• Params::Validate
• Regexp::Common, Data::Types, Data::Verify, Email::Valid, String::Checker, CGI::ArgChecker, CGI::FormMagick::Validator, CGI::Validate

🌍 Document Translations:

Japanese: http://perldoc.jp/docs/modules/

📦 Distributions which include Data::FormValidator:

FreeBSD: p5-Data-FormValidator, Debian: libdata-formvalidator-perl

👏 CREDITS

Some input validation functions from MiniVend by Michael J. Heins. Credit card checksum validation from Bruce Albrecht.

🐛 BUGS

Bug reports and patches welcome. Tests with Test::More are helpful. http://rt.cpan.org/NoAuth/Bugs.html?Dist=Data-FormValidator

🤝 CONTRIBUTING

Maintained on Github: https://github.com/dnmfarrell/Data-FormValidator

👤 AUTHOR

Currently maintained by David Farrell <dfarrell AT cpan.org>. Parts Copyright 2001‑2006 Mark Stosberg. Copyright 1999 Francis J. Lacoste and iNsu Innovations Inc. Parts Copyright 1996‑1999 Michael J. Heins and Bruce Albrecht.

📄 LICENSE

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

📘 NAME 🚀 Quick Reference 📖 SYNOPSIS 📝 DESCRIPTION 🔍 VALIDATING INPUT 📋 INPUT PROFILE SPECIFICATION 🔗 VALIDATING INPUT BASED ON MULTIPLE FIELDS 🔢 MULTIPLE CONSTRAINTS 🧠 ADVANCED VALIDATION 🔄 BACKWARDS COMPATIBILITY 📚 SEE ALSO 👏 CREDITS 🐛 BUGS 🤝 CONTRIBUTING 👤 AUTHOR 📄 LICENSE