# man > Data::FormValidator

---
type: CommandReference
command: Data::FormValidator
mode: perldoc
section: 3pm
source: perldoc
---

## Quick Reference
- `my $results = Data::FormValidator->check(\%input, \%profile);` — validate input, get results object
- `if ($results->has_invalid or $results->has_missing) { ... }` — check for errors
- `my $profile = { required => [qw(fullname email)], optional => [qw(phone)], constraint_methods => { email => email() } };` — minimal profile
- `my ($v, $m, $i, $u) = Data::FormValidator->validate(\%input, \%profile);` — deprecated array return
- `my $dfv = Data::FormValidator->new({ prof1 => \%p1, prof2 => \%p2 }); $dfv->check(\%input, 'prof1');` — multiple profiles
- `filters => ['trim'],` — apply built-in filter to all fields
- `constraint_methods => { cc_no => cc_number({fields => ['cc_type']}) }` — constraint using multiple fields
- `msgs => { invalid => 'Error', format => '* %s' }` — custom error messages

## Name
Validates user input (usually from an HTML form) based on input profile.

## Synopsis
perl
use Data::FormValidator;

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

if ($results->has_invalid or $results->has_missing) {
    # handle $results->invalid, $results->missing, $results->msgs
}
else {
    # use $results->valid
}
## Methods
- `check(\%input, \%profile)` — main interface, returns `Data::FormValidator::Results` object. First argument is a hashref or a CGI‑like object with a `param()` method. Second is the profile.
- `validate(\%input, \%profile)` — deprecated, same input, returns a four‑element array: `($valid, $missing, $invalid, $unknown)`.
- `new($profiles, $defaults)` — creates an object for advanced use: multiple named profiles and/or global defaults.
  ```perl
  my $dfv = Data::FormValidator->new({
      profile_1 => { ... },
      profile_2 => { ... },
  });
  my $results = $dfv->check(\%input, 'profile_1');
  
  Second argument is a hashref of default profile keys that will be merged into every subsequent `check()` call.

## Input Profile Keys

### required
- `required` (arrayref) — field names that must be present and non‑blank.
- `required_regexp` (regexp) — pattern for extra required fields.
- `require_some` (hashref) — groups where a minimum number of fields must be supplied.
  ```perl
  require_some => {
      address_group => [ 2, qw(city state zipcode) ],
  },
  
### optional
- `optional` (arrayref) — fields that may be present and will be validated.
- `optional_regexp` (regexp) — pattern for extra optional fields.
- `dependent_optionals` — optional fields triggered by another field. Supports array, hash (value‑equals‑key), or coderef.
  ```perl
  dependent_optionals => {
      delivery_address => [qw(delivery_notes)],
      delivery_type => { collection => [qw(collection_notes)] },
  }
  
### dependencies
- `dependencies` — fields required when a given field is present. Values can be an arrayref, hashref (field must equal key), or coderef.
  ```perl
  dependencies => {
      cc_no => [ qw(cc_type cc_exp) ],
      pay_type => { check => [qw(check_no)] },
      cc_type => sub {
          my ($dfv, $type) = @_;
          return [ 'cc_cvv' ] if $type eq 'VISA' || $type eq 'MASTERCARD';
          return [];
      },
  }
  
- `dependency_groups` — interdependent required groups.
  ```perl
  dependency_groups => {
      password_group => [qw(password password_confirmation)],
  }
  
- `dependencies_regexp` — regexp mapping to dependent fields (coderef returns arrayref).
- `dependent_require_some` — like `require_some` but triggered by another field.

### defaults
- `defaults` (hashref) — default values for missing fields. Values can be coderefs receiving the results object.
- `defaults_regexp_map` — map regexes to default values for matching optional/required fields (useful for checkboxes).

### filters
- `filters` (arrayref) — filters applied to **all** fields before constraints. Can be built‑in names (`trim`, `digit`) or coderefs.
- `field_filters` (hashref) — per‑field filters.
- `field_filter_regexp_map` (hashref) — regexp‑based filter mapping.
  
All filters modify the values returned in the valid hash. See `Data::FormValidator::Filters`.

### constraint_methods
- `constraint_methods` (hashref) — field‑by‑field constraint assignment. Values can be:
  - a named constraint (e.g. `email()` from `:closures`)
  - a regular expression (`qr/^\d{5}$/`)
  - a coderef (receives `$dfv, $value`)
  - an arrayref for multiple constraints
- `constraint_method_regexp_map` — regexp‑based constraint mapping (additional constraints).

**Multi‑field constraints** use a specialised syntax in `constraint_methods`:
perl
cc_no => cc_number({fields => ['cc_type']})
**Multiple constraints** use an arrayref; named constraints allow identifying which failed:
perl
zip => [ 'zip', { constraint_method => qr/^406/, name => 'starts_with_406' } ],
**Untainting:**
- `untaint_all_constraints` — if true, all valid fields are untainted.
- `untaint_constraint_fields` (arrayref) — specific fields to untaint.
- `untaint_regexp_map` (arrayref of regexes) — fields matching a regex are untainted.

### msgs
Customise error messages. The results object’s `msgs` method returns a hash keyed by field name, with messages for missing/invalid. Configuration keys:
- `missing` — string for missing fields (default: `'Missing'`)
- `invalid` — string for invalid fields (default: `'Invalid'`)
- `prefix` — prefix for field names (e.g. `'error_'`)
- `invalid_separator` — string between multiple messages (default: `' '`)
- `format` — printf‑style format string (default: `'* %s'` wrapped in red bold style)
- `constraints` — hash mapping constraint names to error messages
- `any_errors` — token inserted in the hash if any errors exist
- You can also provide a coderef callback as the value of `msgs` for complete control.

### Other keys
- `missing_optional_valid` — include empty optional fields in the valid hash (useful for update forms).
- `validator_packages` — arrayref of packages to import constraint/filter routines from.
- `debug` — set to `1` to print debug information to STDERR.

## Deprecated Features
- `validate()` — returns `($valid, $missing, $invalid, $unknown)`.
- `constraints` (profile key) — older constraint definition style using hashref with `constraint`, `params`, `name`.
- `constraint_regexp_map` — older equivalent of `constraint_method_regexp_map`.

## See Also
- [Data::FormValidator::Constraints](http://localhost/phpMan.php/perldoc/Data%3A%3AFormValidator%3A%3AConstraints/markdown)
- [Data::FormValidator::Filters](http://localhost/phpMan.php/perldoc/Data%3A%3AFormValidator%3A%3AFilters/markdown)
- [Data::FormValidator::Results](http://localhost/phpMan.php/perldoc/Data%3A%3AFormValidator%3A%3AResults/markdown)
- [Data::FormValidator::Constraints::Dates](http://localhost/phpMan.php/perldoc/Data%3A%3AFormValidator%3A%3AConstraints%3A%3ADates/markdown)
- [Data::FormValidator::Constraints::Upload](http://localhost/phpMan.php/perldoc/Data%3A%3AFormValidator%3A%3AConstraints%3A%3AUpload/markdown)
- [CGI::Application::ValidateRM](http://localhost/phpMan.php/perldoc/CGI%3A%3AApplication%3A%3AValidateRM/markdown), [HTML::Template::Associate::FormValidator](http://localhost/phpMan.php/perldoc/HTML%3A%3ATemplate%3A%3AAssociate%3A%3AFormValidator/markdown)
- [Validating Web Forms with Perl](http://mark.stosberg.com/Tech/perl/form-validation/)