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;
# create our profile
my $profile = {
validator_packages => [qw(Data::FormValidator::Constraints::DateTime)],
required => [qw(my_date)],
constraints => {
# my_date is in the format MM/DD/YYYY
my_date => {
constraint_method => 'to_datetime',
params => [\'%D'], # some valid strptime format string
},
},
untaint_all_constraints => 1,
};
# validate 'my_date'
my $results = Data::FormValidator->check($my_input, $profile);
unless( $results->has_missing || $results->has_invalid ) {
# 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 the 'params' array ref (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 = {
validator_packages => [qw(Data::FormValidator::Constraints::DateTime)],
required => [qw(my_date)],
constraints => {
my_date => 'to_mysql_datetime',
},
};
with a format param
my $profile = {
validator_packages => [qw(Data::FormValidator::Constraints::DateTime)],
required => [qw(my_date)],
constraints => {
my_date => {
constraint_method => 'to_mysql_datetime',
params => [\'%m/%d/%Y'],
},
};
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 is the only routine that must have an accompanying format param.
ymd_to_datetime
This routine is used to take multiple inputs (one each for the year, month, and day) and combine them into a DateTime object, validate the resulting date, and give you the resulting DateTime object in your valid()
results. It must recieve as params
the year, month, and day inputs in that order. You may also specify additional params
that will be interpretted as 'hour', 'minute' and 'second' values to use. If none are provided, then the time '00:00:00' will be used.
my $profile = {
validator_packages => [qw(Data::FormValidator::Constraints::DateTime)],
required => [qw(my_year)],
constraints => {
my_year => {
constraint_method => 'ymd_to_datetime',
# my_hour, my_min, and my_sec are optional
params => [qw(my_year my_month my_day my_hour my_min my_sec)],
},
},
untaint_all_constraints => 1,
};
my $results = Data::FormValidator->check($data, $profile);
#if the date was valid, then we how have a DateTime object
my $datetime = $results->valid('my_year');
DATABASE VALIDATION ROUTINES
to_mysql_datetime
The routine will change the date string into a DATETIME datatype suitable for MySQL. If you don't provide a format parameter then this routine will just validate the data as a valid MySQL DATETIME datatype (using DateTime::Format::MySQL).
to_mysql_date
The routine will change the date string into a DATE datatype suitable for MySQL. If you don't provide a format param then this routine will validate the data as a valid DATE datatype in MySQL (using DateTime::Format::MySQL).
to_mysql_timestamp
The routine will change the date string into a TIMESTAMP datatype suitable for MySQL. If you don't provide a format then the data will be validated as a MySQL TIMESTAMP datatype.
to_pg_datetime
The routine will change the date string into a DATETIME datatype suitable for PostgreSQL. If you don't provide a format then the data will validated as a DATETIME datatype in PostgresSQL (using DateTime::Format::Pg).
AUTHOR
Michael Peters <mpeters@plusthree.com>
Thanks to Plus Three, LP (http://www.plusthree.com) for sponsoring my work on this module
CONTRIBUTORS
SUPPORT
This module is a part of the larger Data::FormValidator project. If you have questions, comments, bug reports or feature requests, please join the Data::FormValidator's mailing list.
SEE ALSO
Data::FormValidator, DateTime. DateTime::Format::Strptime, DateTime::Format::MySQL, DateTime::Format::Pg