Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Data::FormValidator::CUserrContributed:PerlVDlidator::Constraints::DateTime(3)

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.

       If the value is untainted (using	"untaint_all_constraints" or
       "untaint_constraint_fields", it will change the date string into	a
       DateTime	object.

   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 = {
	  required		  => [qw(my_year)],
	  constraint_methods	  => {
	     my_year =>	ymd_to_datetime(qw(my_year my_month my_day my_hour my_min my_sec)),
	  },
	};

       If the value is untainted (using	"untaint_all_constraints" or
       "untaint_constraint_fields", it will change the date string into	a
       DateTime	object.

   before_today
       This routine will validate the date and make sure it less than or equal
       to today	(using "DateTime->today"). It takes one	param which is the
       <strptime|DateTime::Format::Strptime> format string for the date.

       If it validates and you tell D::FV to untaint this parameter it will be
       converted into a	DateTime object.

	# make sure they weren't born in the future
	my $profile = {
	  required		  => [qw(birth_date)],
	  constraint_methods	  => {
	     birth_date	=> before_today('%m/%d/%Y'),
	  },
	};

       If the value is untainted (using	"untaint_all_constraints" or
       "untaint_constraint_fields", it will change the date string into	a
       DateTime	object.

   after_today
       This routine will validate the date and make sure it is greater than or
       equal to	today (using "DateTime->today()"). It takes only one param,
       which is	the strptime format for	the date being validated.

       If it validates and you tell D::FV to untaint this parameter it will be
       converted into a	DateTime object.

	# make sure the	project	isn't already due
	my $profile = {
	  required		  => [qw(death_date)],
	  constraint_methods	  => {
	     death_date	=> after_today('%m/%d/%Y'),
	  },
	  untaint_all_constraints => 1,
	};

       If the value is untainted (using	"untaint_all_constraints" or
       "untaint_constraint_fields", it will change the date string into	a
       DateTime	object.

   ymd_before_today
       This routine will validate the date and make sure it less than or equal
       to today	(using "DateTime->today"). It works just like ymd_to_datetime
       in the parameters it takes.

       If it validates and you tell D::FV to untaint this parameter it will be
       converted into a	DateTime object.

	# make sure they weren't born in the future
	my $profile = {
	  required		  => [qw(birth_date)],
	  constraint_methods	  => {
	     birth_date	=> ymd_before_today(qw(dob_year	dob_month dob_day)),
	  },
	  untaint_all_constraints => 1,
	};

       If the value is untainted (using	"untaint_all_constraints" or
       "untaint_constraint_fields", it will change the date string into	a
       DateTime	object.

   ymd_after_today
       This routine will validate the date and make sure it greater than or
       equal to	today (using "DateTime->today"). It works just like
       ymd_to_datetime in the parameters it takes.

       If it validates and you tell D::FV to untaint this parameter it will be
       converted into a	DateTime object.

	# make sure the	project	isn't already due
	my $profile = {
	  required		  => [qw(due_date)],
	  constraint_methods	  => {
	     birth_date	=> ymd_after_today(qw(dob_year dob_month dob_day)),
	  },
	  untaint_all_constraints => 1,
	};

       If the value is untainted (using	"untaint_all_constraints" or
       "untaint_constraint_fields", it will change the date string into	a
       DateTime	object.

   before_datetime
       This routine will validate the date and make sure it occurs before the
       specified date. It takes	two params:

       o   first, the strptime format

	   (for	both the date we are validating	and also the date we want to
	   compare against)

       o   second, the date we are comparing against.

	   This	date we	are comparing against can either be a specified	date
	   (using a scalar ref), or a named parameter from your	form (using a
	   scalar name).

       If it validates and you tell D::FV to untaint this parameter it will be
       converted into a	DateTime object.

	# make sure they were born before 1979
	my $profile = {
	  required		  => [qw(birth_date)],
	  constraint_methods	  => {
	     birth_date	=> before_datetime('%m/%d/%Y', '01/01/1979'),
	  },
	  untaint_all_constraints => 1,
	};

       If the value is untainted (using	"untaint_all_constraints" or
       "untaint_constraint_fields", it will change the date string into	a
       DateTime	object.

   after_datetime
       This routine will validate the date and make sure it occurs after the
       specified date. It takes	two params:

       o   first, the strptime format

	   (for	both the date we are validating	and also the date we want to
	   compare against)

       o   second, the date we are comparing against.

	   This	date we	are comparing against can either be a specified	date
	   (using a scalar ref), or a named parameter from your	form (using a
	   scalar name).

	# make sure they died after they were born
	my $profile = {
	  required		  => [qw(birth_date death_date)],
	  constraint_methods	  => {
	     death_date	=> after_datetime('%m/%d/%Y', 'birth_date'),
	  },
	  untaint_all_constraints => 1,
	};

       If the value is untainted (using	"untaint_all_constraints" or
       "untaint_constraint_fields", it will change the date string into	a
       DateTime	object.

   between_datetimes
       This routine will validate the date and make sure it occurs after the
       first specified date and	before the second specified date. It takes
       three params:

       o   first, the strptime format

	   (for	both the date we are validating	and also the dates we want to
	   compare against)

       o   second, the first date we are comparing against.

       o   third, the second date we are comparing against.

	   This	date (and the second) we are comparing against can either be a
	   specified date (using a scalar ref),	or a named parameter from your
	   form	(using a scalar	name).

	# make sure they died after they were born
	my $profile = {
	  required		  => [qw(birth_date death_date marriage_date)],
	  constraint_methods	  => {
	     marriage_date => between_datetimes('%m/%d/%Y', 'birth_date', 'death_date'),
	  },
	  untaint_all_constraints => 1,
	};

       If the value is untainted (using	"untaint_all_constraints" or
       "untaint_constraint_fields", it will change the date string into	a
       DateTime	object.

DATABASE RELATED 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).

       If the value is untainted (using	"untaint_all_constraints" or
       "untaint_constraint_fields", it will change the date string into	a
       DateTime	object.

   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).

       If the value is untainted (using	"untaint_all_constraints" or
       "untaint_constraint_fields", it will change the date string into	a
       DateTime	object.

   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.

       If the value is untainted (using	"untaint_all_constraints" or
       "untaint_constraint_fields", it will change the date string into	a
       DateTime	object.

   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).

       If the value is untainted (using	"untaint_all_constraints" or
       "untaint_constraint_fields", it will change the date string into	a
       DateTime	object.

AUTHOR
       Michael Peters <mpeters@plusthree.com>

       Thanks to Plus Three, LP	(http://www.plusthree.com) for sponsoring my
       work on this module

CONTRIBUTORS
       Mark Stosberg <mark@summersault.com>
       Charles Frank <cfrank@plusthree.com>
       Aaron Ross <aaronelliotross@gmail.com>

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.

CAVEAT
       When passing parameters to typical Data::FormValidator constraints you
       pass plain scalars to refer to query params and scalar-refs to refer to
       literals. We get	around that in this module by assuming everything
       could be	refering to a query param, and if one is not found, then it's
       a literal. This works well unless you have query	params with names like
       '01/02/2005' or '%m/%d/%Y'.

       And if you do, shame on you for having such horrible names.

SEE ALSO
       Data::FormValidator, DateTime. DateTime::Format::Strptime,
       DateTime::Format::MySQL,	DateTime::Format::Pg

COPYRIGHT & LICENSE
       Copyright Michael Peters	2010, all rights reserved.

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

perl v5.32.1			 Data::FormValidator::Constraints::DateTime(3)

NAME | DESCRIPTION | ABSTRACT | STRPTIME FORMATS | VALIDATION ROUTINES | DATABASE RELATED VALIDATION ROUTINES | AUTHOR | CONTRIBUTORS | SUPPORT | CAVEAT | SEE ALSO | COPYRIGHT & LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Data::FormValidator::Constraints::DateTime&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help