Data::...teTime(3pm)

okay bestie, welcome to Data::FormValidator::Constraints::DateTime(3pm) from the User Contributed Perl Documentation 💖 this is part 1 of 2, so we're diving in 🎀

✨ NAME ✨

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

💖 DESCRIPTION 💖

so Data::FormValidator::Constraints::DateTime is here to give Data::FormValidator some constraint routines for dates and times. It's giving 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. periodt 💅

🌈 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 in 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 by passing it to the constraint generation routine (see the example above 👀).

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

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 ✨

okay bestie, here's the lineup of validation routines this module hands you 🎀

🌸 to_datetime

this one validates your date against a strptime(3) format and then, boom, turns that date string into a DateTime object ✨ it has to have a strptime format param riding along with it, no exceptions, periodt.

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 one is giving "combine the squad" energy 💅 you feed it multiple inputs (one for the year, one for the month, one for the day), it smushes them together into a DateTime object, validates the resulting date, and hands you back the DateTime object in your valid() results. it must receive as params the year, month, and day inputs, in that order — no shuffling 🙅 you can also add extra params that get interpreted as 'hour', 'minute' and 'second' values to use. if you don't provide any of those, the time '00:00:00' gets 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 validates the date and makes sure it's 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 one validates the date and makes sure it's 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

validates the date and makes sure it's 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

validates the date and makes sure it's 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

validates the date and makes sure it happens before the specified date 🦋 it takes two params:

• first, the strptime format

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

• second, the date we are comparing against.

this date we're 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

validates the date and makes sure it happens after the specified date ✨ two params again:

• first, the strptime format

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

• second, the date we are comparing against.

this date we're 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

validates the date and makes sure it lands after the first specified date and before the second specified date 🎀 it takes three params:

• first, the strptime format

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

• second, the first date we are comparing against.
• 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

turns that date string into a DATETIME datatype that MySQL will actually accept 🐬 if you don't hand it a format parameter, it just validates 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

turns the date string into a DATE datatype suitable for MySQL 💖 if you don't provide a format param, it validates 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

turns the date string into a TIMESTAMP datatype suitable for MySQL 🌈 if you don't provide a format, the data gets 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

turns the date string into a DATETIME datatype suitable for PostgreSQL 🐘 if you don't provide a format, the data gets validated as a DATETIME datatype in PostgreSQL (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

okay so when you pass 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.

---

and that's the whole vibe bestie, we ate and left no crumbs 🎀 this page was served to you by perl v5.34.0, dated 2022-06-12, under the Data::...teTime(3pm) banner 💅 mwah, go validate something pretty ✨