.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Data::FormValidator::Constraints::DateTime 3pm" .TH Data::FormValidator::Constraints::DateTime 3pm "2021-01-08" "perl v5.32.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Data::FormValidator::Constraints::DateTime \- D::FV constraints for dates and times .SH "DESCRIPTION" .IX Header "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 \fBstrptime\fR\|(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. .SH "ABSTRACT" .IX Header "ABSTRACT" .Vb 2 \& 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(\*(Aq%D\*(Aq), # in the format MM/DD/YYYY \& }, \& untaint_all_constraints => 1, \& }; \& \& # validate \*(Aqmy_date\*(Aq \& my $results = Data::FormValidator\->check($my_input, $profile); \& \& if( $results\->success ) { \& # if we got here then $results\->valid(\*(Aqmy_date\*(Aq) \& # is a valid DateTime object \& my $datetime = $results\->valid(\*(Aqmy_date\*(Aq); \& . \& . \& } .Ve .SH "STRPTIME FORMATS" .IX Header "STRPTIME FORMATS" Most of the validation routines provided by this module use \&\fBstrptime\fR\|(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). .PP 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 \fBstrptime\fR\|(3) man page (if you are on a *nix system) or you can see the DateTime::Format::Strptime documentation. .PP 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 (\f(CW\*(C`to_mysql_*\*(C'\fR and \&\f(CW\*(C`to_pg_*\*(C'\fR). 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: .PP without a format param .PP .Vb 6 \& my $profile = { \& required => [qw(my_date)], \& constraint_methods => { \& my_date => to_mysql_datetime(), \& }, \& }; .Ve .PP with a format param .PP .Vb 6 \& my $profile = { \& required => [qw(my_date)], \& constraint_methods => { \& my_date => to_mysql_datetime(\*(Aq%m/%d/%Y\*(Aq), \& }, \& }; .Ve .SS "DateTime::Format Objects" .IX Subsection "DateTime::Format Objects" Using \fBstrptime\fR\|(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 \fBstrptime\fR\|(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: .PP .Vb 3 \& # 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 => \*(Aq%m/%d/%Y\*(Aq)\->parse_datetime($_[1]) } }, \& sub { eval { DateTime::Format::Strptime\->new(pattern => \*(Aq%m/%d/%y\*(Aq)\->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()), \& }, \& }; .Ve .SH "VALIDATION ROUTINES" .IX Header "VALIDATION ROUTINES" Following is the list of validation routines that are provided by this module. .SS "to_datetime" .IX Subsection "to_datetime" The routine will validate the date aginst a \fBstrptime\fR\|(3) format and change the date string into a DateTime object. This routine \fBmust\fR have an accompanying strptime format param. .PP If the value is untainted (using \f(CW\*(C`untaint_all_constraints\*(C'\fR or \&\f(CW\*(C`untaint_constraint_fields\*(C'\fR, it will change the date string into a DateTime object. .SS "ymd_to_datetime" .IX Subsection "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 \f(CW\*(C`valid()\*(C'\fR results. It must receive as \f(CW\*(C`params\*(C'\fR the year, month, and day inputs in that order. You may also specify additional \f(CW\*(C`params\*(C'\fR 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. .PP .Vb 6 \& 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)), \& }, \& }; .Ve .PP If the value is untainted (using \f(CW\*(C`untaint_all_constraints\*(C'\fR or \&\f(CW\*(C`untaint_constraint_fields\*(C'\fR, it will change the date string into a DateTime object. .SS "before_today" .IX Subsection "before_today" This routine will validate the date and make sure it less than or equal to today (using \f(CW\*(C`DateTime\->today\*(C'\fR). It takes one param which is the format string for the date. .PP If it validates and you tell D::FV to untaint this parameter it will be converted into a DateTime object. .PP .Vb 7 \& # make sure they weren\*(Aqt born in the future \& my $profile = { \& required => [qw(birth_date)], \& constraint_methods => { \& birth_date => before_today(\*(Aq%m/%d/%Y\*(Aq), \& }, \& }; .Ve .PP If the value is untainted (using \f(CW\*(C`untaint_all_constraints\*(C'\fR or \&\f(CW\*(C`untaint_constraint_fields\*(C'\fR, it will change the date string into a DateTime object. .SS "after_today" .IX Subsection "after_today" This routine will validate the date and make sure it is greater than or equal to today (using \f(CW\*(C`DateTime\->today()\*(C'\fR). It takes only one param, which is the strptime format for the date being validated. .PP If it validates and you tell D::FV to untaint this parameter it will be converted into a DateTime object. .PP .Vb 8 \& # make sure the project isn\*(Aqt already due \& my $profile = { \& required => [qw(death_date)], \& constraint_methods => { \& death_date => after_today(\*(Aq%m/%d/%Y\*(Aq), \& }, \& untaint_all_constraints => 1, \& }; .Ve .PP If the value is untainted (using \f(CW\*(C`untaint_all_constraints\*(C'\fR or \&\f(CW\*(C`untaint_constraint_fields\*(C'\fR, it will change the date string into a DateTime object. .SS "ymd_before_today" .IX Subsection "ymd_before_today" This routine will validate the date and make sure it less than or equal to today (using \f(CW\*(C`DateTime\->today\*(C'\fR). It works just like ymd_to_datetime in the parameters it takes. .PP If it validates and you tell D::FV to untaint this parameter it will be converted into a DateTime object. .PP .Vb 8 \& # make sure they weren\*(Aqt 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, \& }; .Ve .PP If the value is untainted (using \f(CW\*(C`untaint_all_constraints\*(C'\fR or \&\f(CW\*(C`untaint_constraint_fields\*(C'\fR, it will change the date string into a DateTime object. .SS "ymd_after_today" .IX Subsection "ymd_after_today" This routine will validate the date and make sure it greater than or equal to today (using \f(CW\*(C`DateTime\->today\*(C'\fR). It works just like ymd_to_datetime in the parameters it takes. .PP If it validates and you tell D::FV to untaint this parameter it will be converted into a DateTime object. .PP .Vb 8 \& # make sure the project isn\*(Aqt 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, \& }; .Ve .PP If the value is untainted (using \f(CW\*(C`untaint_all_constraints\*(C'\fR or \&\f(CW\*(C`untaint_constraint_fields\*(C'\fR, it will change the date string into a DateTime object. .SS "before_datetime" .IX Subsection "before_datetime" This routine will validate the date and make sure it occurs before the specified date. It takes two params: .IP "\(bu" 4 first, the strptime format .Sp (for both the date we are validating and also the date we want to compare against) .IP "\(bu" 4 second, the date we are comparing against. .Sp 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). .PP If it validates and you tell D::FV to untaint this parameter it will be converted into a DateTime object. .PP .Vb 8 \& # make sure they were born before 1979 \& my $profile = { \& required => [qw(birth_date)], \& constraint_methods => { \& birth_date => before_datetime(\*(Aq%m/%d/%Y\*(Aq, \*(Aq01/01/1979\*(Aq), \& }, \& untaint_all_constraints => 1, \& }; .Ve .PP If the value is untainted (using \f(CW\*(C`untaint_all_constraints\*(C'\fR or \&\f(CW\*(C`untaint_constraint_fields\*(C'\fR, it will change the date string into a DateTime object. .SS "after_datetime" .IX Subsection "after_datetime" This routine will validate the date and make sure it occurs after the specified date. It takes two params: .IP "\(bu" 4 first, the strptime format .Sp (for both the date we are validating and also the date we want to compare against) .IP "\(bu" 4 second, the date we are comparing against. .Sp 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). .PP .Vb 8 \& # make sure they died after they were born \& my $profile = { \& required => [qw(birth_date death_date)], \& constraint_methods => { \& death_date => after_datetime(\*(Aq%m/%d/%Y\*(Aq, \*(Aqbirth_date\*(Aq), \& }, \& untaint_all_constraints => 1, \& }; .Ve .PP If the value is untainted (using \f(CW\*(C`untaint_all_constraints\*(C'\fR or \&\f(CW\*(C`untaint_constraint_fields\*(C'\fR, it will change the date string into a DateTime object. .SS "between_datetimes" .IX Subsection "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: .IP "\(bu" 4 first, the strptime format .Sp (for both the date we are validating and also the dates we want to compare against) .IP "\(bu" 4 second, the first date we are comparing against. .IP "\(bu" 4 third, the second date we are comparing against. .Sp 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). .PP .Vb 8 \& # make sure they died after they were born \& my $profile = { \& required => [qw(birth_date death_date marriage_date)], \& constraint_methods => { \& marriage_date => between_datetimes(\*(Aq%m/%d/%Y\*(Aq, \*(Aqbirth_date\*(Aq, \*(Aqdeath_date\*(Aq), \& }, \& untaint_all_constraints => 1, \& }; .Ve .PP If the value is untainted (using \f(CW\*(C`untaint_all_constraints\*(C'\fR or \&\f(CW\*(C`untaint_constraint_fields\*(C'\fR, it will change the date string into a DateTime object. .SH "DATABASE RELATED VALIDATION ROUTINES" .IX Header "DATABASE RELATED VALIDATION ROUTINES" .SS "to_mysql_datetime" .IX Subsection "to_mysql_datetime" The routine will change the date string into a \s-1DATETIME\s0 datatype suitable for MySQL. If you don't provide a format parameter then this routine will just validate the data as a valid MySQL \s-1DATETIME\s0 datatype (using DateTime::Format::MySQL). .PP If the value is untainted (using \f(CW\*(C`untaint_all_constraints\*(C'\fR or \&\f(CW\*(C`untaint_constraint_fields\*(C'\fR, it will change the date string into a DateTime object. .SS "to_mysql_date" .IX Subsection "to_mysql_date" The routine will change the date string into a \s-1DATE\s0 datatype suitable for MySQL. If you don't provide a format param then this routine will validate the data as a valid \s-1DATE\s0 datatype in MySQL (using DateTime::Format::MySQL). .PP If the value is untainted (using \f(CW\*(C`untaint_all_constraints\*(C'\fR or \&\f(CW\*(C`untaint_constraint_fields\*(C'\fR, it will change the date string into a DateTime object. .SS "to_mysql_timestamp" .IX Subsection "to_mysql_timestamp" The routine will change the date string into a \s-1TIMESTAMP\s0 datatype suitable for MySQL. If you don't provide a format then the data will be validated as a MySQL \s-1TIMESTAMP\s0 datatype. .PP If the value is untainted (using \f(CW\*(C`untaint_all_constraints\*(C'\fR or \&\f(CW\*(C`untaint_constraint_fields\*(C'\fR, it will change the date string into a DateTime object. .SS "to_pg_datetime" .IX Subsection "to_pg_datetime" The routine will change the date string into a \s-1DATETIME\s0 datatype suitable for PostgreSQL. If you don't provide a format then the data will validated as a \s-1DATETIME\s0 datatype in PostgreSQL (using DateTime::Format::Pg). .PP If the value is untainted (using \f(CW\*(C`untaint_all_constraints\*(C'\fR or \&\f(CW\*(C`untaint_constraint_fields\*(C'\fR, it will change the date string into a DateTime object. .SH "AUTHOR" .IX Header "AUTHOR" Michael Peters .PP Thanks to Plus Three, \s-1LP\s0 (http://www.plusthree.com) for sponsoring my work on this module .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" .IP "Mark Stosberg " 4 .IX Item "Mark Stosberg " .PD 0 .IP "Charles Frank " 4 .IX Item "Charles Frank " .IP "Aaron Ross " 4 .IX Item "Aaron Ross " .PD .SH "SUPPORT" .IX Header "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. .SH "CAVEAT" .IX Header "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 \f(CW\*(Aq01/02/2005\*(Aq\fR or \f(CW\*(Aq%m/%d/%Y\*(Aq\fR. .PP And if you do, shame on you for having such horrible names. .SH "SEE ALSO" .IX Header "SEE ALSO" Data::FormValidator, DateTime. DateTime::Format::Strptime, DateTime::Format::MySQL, DateTime::Format::Pg .SH "COPYRIGHT & LICENSE" .IX Header "COPYRIGHT & LICENSE" Copyright Michael Peters 2010, all rights reserved. .PP This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.