NAME

Data::FormValidator::Constraints::DateTime - D::FV constraints for dates and times

DESCRIPTION

This package provides constraint routines for Data::FormValidator for dealing with dates and times. It provides an easy mechanism for validating dates of any format (using strptime(3)) and transforming those dates (as long as you 'untaint' the fields) into valid DateTime objects, or into strings that would be properly formatted for various database engines.

ABSTRACT

use Data::FormValidator;
use Data::FormValidator::Constraints::DateTime qw(:all);
  
# create our profile
my $profile = {
    required                => [qw(my_date)],
    constraint_methods      => {
        my_date   => to_datetime('%D'), # in the format MM/DD/YYYY
    },
    untaint_all_constraints => 1,
};

# validate 'my_date'
my $results = Data::FormValidator->check($my_input, $profile);

if( $results->success ) {
  # if we got here then $results->valid('my_date')
  # is a valid DateTime object 
  my $datetime = $results->valid('my_date');
  .
  .
}

STRPTIME FORMATS

Most of the validation routines provided by this module use strptime(3) format strings to know what format your date string is in before we can process it. You specify this format for each date you want to validate using by passing it to constraint generation routine (see the example above).

We use DateTime::Format::Strptime for this transformation. If you need a list of these formats (if you haven't yet committed them to memory) you can see the strptime(3) man page (if you are on a *nix system) or you can see the DateTime::Format::Strptime documentation.

There are however some routines that can live without the format param. These include routines which try and validate according to rules for a particular database (to_mysql_* and to_pg_*). If no format is provided, then we will attempt to validate according to the rules for that datatype in that database (using DateTime::Format::MySQL and DateTime::Format::Pg). Here are some examples:

without a format param

my $profile = {
  required                => [qw(my_date)],
  constraint_methods      => {
      my_date => to_mysql_datetime(),
  },
};

with a format param

my $profile = {
  required                => [qw(my_date)],
  constraint_methods      => {
      my_date => to_mysql_datetime('%m/%d/%Y'),
  },
};

DateTime::Format Objects

Using strptime(3) format strings gives a lot of flexibility, but sometimes not enough. Suppose you have a web form that allows the user to input a date in the format '11/21/2006' or simply '11/21/06'. A simple format string is not enough. To take full advantage of the DateTime project, any place that you can pass in a strptime(3) format string, you can also pass in a DateTime::Format object. To solve the above problem you might have code that looks like this:

# your formatter code
package MyProject::DateTime::FlexYear;
use DateTime::Format::Strptime;

use DateTime::Format::Builder (
  parsers => { 
    parse_datetime => [
      sub { eval { DateTime::Format::Strptime->new(pattern => '%m/%d/%Y')->parse_datetime($_[1]) } },
      sub { eval { DateTime::Format::Strptime->new(pattern => '%m/%d/%y')->parse_datetime($_[1]) } },
    ] 
  }
);

1;

# in your web validation code
my $profile = {
  required           => [qw(my_date)],
  constraint_methods => {
      my_date => to_mysql_datetime(MyProject::DateTime::FlexYear->new()),
  },
};

VALIDATION ROUTINES

Following is the list of validation routines that are provided by this module.

to_datetime

The routine will validate the date aginst a strptime(3) format and change the date string into a DateTime object. This routine must have an accompanying strptime format param.