NAME

Data::FormValidator::Profile - Profile object for Data::FormValidator

SYNOPSIS

use Data::FormValidator;
use Data::FormValidator::Profile;

# create a new DFV::Profile object
my $profile = Data::FormValidator::Profile->new( {
    optional  => [qw( this that )],
    required  => [qw( some other thing )],
    } );

# query the optional/required fields in the profile
my @optional = $profile->optional();
my @required = $profile->required();

# reduce the profile to just a limited set of fields
$profile->only( qw(this that) );

# remove fields from the profile
$profile->remove( qw(some other thing) );

# add a new field to the profile
$profile->add( 'username',
    required    => 1,
    filters     => 'trim',
    constraints => FV_max_length(32),
    msgs => {
        constraints => {
            max_length => 'too big',
        },
    },
);

# call chaining, to make manipulation quicker
$profile->only(qw( this that other ))
  ->remove(qw( that ))
  ->add(qw( foo ))
  ->check({ this => 'is a test' });

# use the profile to validate data
my $res = $profile->check({ this => 'is a test' });
# ... or
$res = Data::FormValidator->check(
  { this => 'is a test' },
  $profile->profile(),
);

DESCRIPTION

Data::FormValidator::Profile provides an interface to help manage Data::FormValidator profiles.

I found that I was frequently using Data::FormValidator profiles to help define my DB constraints and validation rules, but that depending on the context I was working in I may only be manipulating a small handful of the fields at any given point. Although I could query my DB layer to get the default validation profile, I was really only concerned with the rules for two or three fields. Thus, Data::FormValidator::Profile, to help make it easier to trim profiles to include only certain sets of fields in the profile.

Limitations

All said, though, Data::FormValidator::Profile has some limitations that you need to be aware of.

• It only removes fields from the following profile attributes:

  required
  optional
  defaults
  field_filters
  constraints
  constraint_methods
  

  NO effort is made to update dependencies, groups, require_some, or anything based on a regexp match. Yes, that does mean that this module is limited in its usefulness if you've got really fancy Data::FormValidator profiles. That said, though, I'm not using anything that fancy, so it works for me.

• To use the profile with Data::FormValidator, use either the form of:

  $profile->check($data)
  

  or

  Data::FormValidator->check($data, $profile->profile)
  

  Data::FormValidator won't accept a blessed object when calling Data::FormValidator->check(), so you need to call $profile->profile() to turn the profile into a HASHREF first.

  Unless you're doing anything fancier and you've got an actual Data::FormValidator object that you're working with, its easier/simpler to just call $profile->check($data); that's the recommended interface.

METHODS

• new()

  Creates a new DFV::Profile object, based on the given profile (which can be provided either as a HASH or a HASHREF).

• check($data)

  Checks the given $data against the profile. This method simply acts as a short-hand to Data::FormValidator->check($data,$profile->profile).

• profile()

  Returns the actual profile, as a hash-ref. You need to call this method when you want to send the profile through to Data::FormValidator to do data validation.

• required()

  Returns the list of "required" fields in the validation profile.

• optional()

  Returns the list of "optional" fields in the validation profile.

• only(@fields)

  Reduces the profile so that it only contains information on the given list of @fields.

  Returns $self, to support call-chaining.

• remove(@fields)

  Removes any of the given @fields from the profile.

  Returns $self, to support call-chaining.

• make_optional(@fields)

  Ensures that the given set of @fields are set as being optional (even if they were previously described as being required fields).

  Returns $self, to support call-chaining.

• make_required(@fields)

  Ensures that the given set of @fields are set as being required (even if they were previously described as being optional fields).

  Returns $self, to support call-chaining.

• set(%options)

  Explicitly sets one or more %options into the profile. Useful when you KNOW exactly what you want to add/do to the profile.

  Returns $self, to support call-chaining.

• add($field, %args)

  Adds the given $field to the validation profile, and sets up additional validation rules as per the provided %args.

  If the field already exists in the profile, this method throws a fatal exception.

  Returns $self, to support call-chaining.

  Acceptable %args include:

  • required

    If non-zero, specifies that the field is required and is not an optional field (default is to be optional)

  • default

    Default value for the field.

  • dependencies

    "dependencies" for this field. Replaces existing value.

  • filters

    "field_filters" to be applied. Replaces existing value.

  • constraints

    "constraint_methods" for this field. Replaces existing value.

  • msgs

    Hash-ref of "constraint messages" that are related to this field. Replaces existing values.

  Here's an example to help show how the %args are mapped into a validation profile:

  $profile->add(
      'username',
      required    => 1,
      filters     => ['trim', 'lc'],
      constraints => FV_length_between(4,32),
      msgs => {
          length_between => 'Username must be 4-32 chars in length.',
          },
      );

  becomes:

  {
      required => [qw( username )],
      field_filters => {
          username => ['trim', 'lc'],
      },
      constraint_methods => {
          username => FV_length_between(4,32),
      },
      msgs => {
          constraints => {
              length_between => 'Username must be ...',
          },
      },
  }

AUTHOR

Graham TerMarsch (cpan@howlingfrog.com)

COPYRIGHT

Copyright (C) 2008, Graham TerMarsch. All Rights Reserved.

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

SEE ALSO

Data::FormValidator.