1Data::FormValidator::CoUnssetrraCionnttsr:i:bDDuaattteaed:T:iPFmeoerr(lm3V)Daolciudmaetnotra:t:iCoonnstraints::DateTime(3)
2
3
4

NAME

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

DESCRIPTION

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

ABSTRACT

18         use Data::FormValidator;
19         use Data::FormValidator::Constraints::DateTime qw(:all);
20
21         # create our profile
22         my $profile = {
23             required                => [qw(my_date)],
24             constraint_methods      => {
25                 my_date   => to_datetime('%D'), # in the format MM/DD/YYYY
26             },
27             untaint_all_constraints => 1,
28         };
29
30         # validate 'my_date'
31         my $results = Data::FormValidator->check($my_input, $profile);
32
33         if( $results->success ) {
34           # if we got here then $results->valid('my_date')
35           # is a valid DateTime object
36           my $datetime = $results->valid('my_date');
37           .
38           .
39         }
40

STRPTIME FORMATS

42       Most of the validation routines provided by this module use strptime(3)
43       format strings to know what format your date string is in before we can
44       process it. You specify this format for each date you want to validate
45       using by passing it to constraint generation routine (see the example
46       above).
47
48       We use DateTime::Format::Strptime for this transformation.  If you need
49       a list of these formats (if you haven't yet committed them to memory)
50       you can see the strptime(3) man page (if you are on a *nix system) or
51       you can see the DateTime::Format::Strptime documentation.
52
53       There are however some routines that can live without the format param.
54       These include routines which try and validate according to rules for a
55       particular database ("to_mysql_*" and "to_pg_*"). If no format is
56       provided, then we will attempt to validate according to the rules for
57       that datatype in that database (using DateTime::Format::MySQL and
58       DateTime::Format::Pg).  Here are some examples:
59
60       without a format param
61
62        my $profile = {
63          required                => [qw(my_date)],
64          constraint_methods      => {
65              my_date => to_mysql_datetime(),
66          },
67        };
68
69       with a format param
70
71        my $profile = {
72          required                => [qw(my_date)],
73          constraint_methods      => {
74              my_date => to_mysql_datetime('%m/%d/%Y'),
75          },
76        };
77
78   DateTime::Format Objects
79       Using strptime(3) format strings gives a lot of flexibility, but
80       sometimes not enough. Suppose you have a web form that allows the user
81       to input a date in the format '11/21/2006' or simply '11/21/06'. A
82       simple format string is not enough. To take full advantage of the
83       DateTime project, any place that you can pass in a strptime(3) format
84       string, you can also pass in a DateTime::Format object. To solve the
85       above problem you might have code that looks like this:
86
87         # your formatter code
88         package MyProject::DateTime::FlexYear;
89         use DateTime::Format::Strptime;
90
91         use DateTime::Format::Builder (
92           parsers => {
93             parse_datetime => [
94               sub { eval { DateTime::Format::Strptime->new(pattern => '%m/%d/%Y')->parse_datetime($_[1]) } },
95               sub { eval { DateTime::Format::Strptime->new(pattern => '%m/%d/%y')->parse_datetime($_[1]) } },
96             ]
97           }
98         );
99
100         1;
101
102         # in your web validation code
103         my $profile = {
104           required           => [qw(my_date)],
105           constraint_methods => {
106               my_date => to_mysql_datetime(MyProject::DateTime::FlexYear->new()),
107           },
108         };
109

VALIDATION ROUTINES

111       Following is the list of validation routines that are provided by this
112       module.
113
114   to_datetime
115       The routine will validate the date aginst a strptime(3) format and
116       change the date string into a DateTime object. This routine must have
117       an accompanying strptime format param.
118
119       If the value is untainted (using "untaint_all_constraints" or
120       "untaint_constraint_fields", it will change the date string into a
121       DateTime object.
122
123   ymd_to_datetime
124       This routine is used to take multiple inputs (one each for the year,
125       month, and day) and combine them into a DateTime object, validate the
126       resulting date, and give you the resulting DateTime object in your
127       "valid()" results. It must recieve as "params" the year, month, and day
128       inputs in that order. You may also specify additional "params" that
129       will be interpretted as 'hour', 'minute' and 'second' values to use. If
130       none are provided, then the time '00:00:00' will be used.
131
132        my $profile = {
133          required                => [qw(my_year)],
134          constraint_methods      => {
135             my_year => ymd_to_datetime(qw(my_year my_month my_day my_hour my_min my_sec)),
136          },
137        };
138
139       If the value is untainted (using "untaint_all_constraints" or
140       "untaint_constraint_fields", it will change the date string into a
141       DateTime object.
142
143   before_today
144       This routine will validate the date and make sure it less than or equal
145       to today (using "DateTime->today"). It takes one param which is the
146       <strptime|DateTime::Format::Strptime> format string for the date.
147
148       If it validates and you tell D::FV to untaint this parameter it will be
149       converted into a DateTime object.
150
151        # make sure they weren't born in the future
152        my $profile = {
153          required                => [qw(birth_date)],
154          constraint_methods      => {
155             birth_date => before_today('%m/%d/%Y'),
156          },
157        };
158
159       If the value is untainted (using "untaint_all_constraints" or
160       "untaint_constraint_fields", it will change the date string into a
161       DateTime object.
162
163   after_today
164       This routine will validate the date and make sure it is greater than or
165       equal to today (using "DateTime->today()"). It takes only one param,
166       which is the strptime format for the date being validated.
167
168       If it validates and you tell D::FV to untaint this parameter it will be
169       converted into a DateTime object.
170
171        # make sure the project isn't already due
172        my $profile = {
173          required                => [qw(death_date)],
174          constraint_methods      => {
175             death_date => after_today('%m/%d/%Y'),
176          },
177          untaint_all_constraints => 1,
178        };
179
180       If the value is untainted (using "untaint_all_constraints" or
181       "untaint_constraint_fields", it will change the date string into a
182       DateTime object.
183
184   ymd_before_today
185       This routine will validate the date and make sure it less than or equal
186       to today (using "DateTime->today"). It works just like ymd_to_datetime
187       in the parameters it takes.
188
189       If it validates and you tell D::FV to untaint this parameter it will be
190       converted into a DateTime object.
191
192        # make sure they weren't born in the future
193        my $profile = {
194          required                => [qw(birth_date)],
195          constraint_methods      => {
196             birth_date => ymd_before_today(qw(dob_year dob_month dob_day)),
197          },
198          untaint_all_constraints => 1,
199        };
200
201       If the value is untainted (using "untaint_all_constraints" or
202       "untaint_constraint_fields", it will change the date string into a
203       DateTime object.
204
205   ymd_after_today
206       This routine will validate the date and make sure it greater than or
207       equal to today (using "DateTime->today"). It works just like
208       ymd_to_datetime in the parameters it takes.
209
210       If it validates and you tell D::FV to untaint this parameter it will be
211       converted into a DateTime object.
212
213        # make sure the project isn't already due
214        my $profile = {
215          required                => [qw(due_date)],
216          constraint_methods      => {
217             birth_date => ymd_after_today(qw(dob_year dob_month dob_day)),
218          },
219          untaint_all_constraints => 1,
220        };
221
222       If the value is untainted (using "untaint_all_constraints" or
223       "untaint_constraint_fields", it will change the date string into a
224       DateTime object.
225
226   before_datetime
227       This routine will validate the date and make sure it occurs before the
228       specified date. It takes two params:
229
230       •   first, the strptime format
231
232           (for both the date we are validating and also the date we want to
233           compare against)
234
235       •   second, the date we are comparing against.
236
237           This date we are comparing against can either be a specified date
238           (using a scalar ref), or a named parameter from your form (using a
239           scalar name).
240
241       If it validates and you tell D::FV to untaint this parameter it will be
242       converted into a DateTime object.
243
244        # make sure they were born before 1979
245        my $profile = {
246          required                => [qw(birth_date)],
247          constraint_methods      => {
248             birth_date => before_datetime('%m/%d/%Y', '01/01/1979'),
249          },
250          untaint_all_constraints => 1,
251        };
252
253       If the value is untainted (using "untaint_all_constraints" or
254       "untaint_constraint_fields", it will change the date string into a
255       DateTime object.
256
257   after_datetime
258       This routine will validate the date and make sure it occurs after the
259       specified date. It takes two params:
260
261       •   first, the strptime format
262
263           (for both the date we are validating and also the date we want to
264           compare against)
265
266       •   second, the date we are comparing against.
267
268           This date we are comparing against can either be a specified date
269           (using a scalar ref), or a named parameter from your form (using a
270           scalar name).
271
272        # make sure they died after they were born
273        my $profile = {
274          required                => [qw(birth_date death_date)],
275          constraint_methods      => {
276             death_date => after_datetime('%m/%d/%Y', 'birth_date'),
277          },
278          untaint_all_constraints => 1,
279        };
280
281       If the value is untainted (using "untaint_all_constraints" or
282       "untaint_constraint_fields", it will change the date string into a
283       DateTime object.
284
285   between_datetimes
286       This routine will validate the date and make sure it occurs after the
287       first specified date and before the second specified date. It takes
288       three params:
289
290       •   first, the strptime format
291
292           (for both the date we are validating and also the dates we want to
293           compare against)
294
295       •   second, the first date we are comparing against.
296
297       •   third, the second date we are comparing against.
298
299           This date (and the second) we are comparing against can either be a
300           specified date (using a scalar ref), or a named parameter from your
301           form (using a scalar name).
302
303        # make sure they died after they were born
304        my $profile = {
305          required                => [qw(birth_date death_date marriage_date)],
306          constraint_methods      => {
307             marriage_date => between_datetimes('%m/%d/%Y', 'birth_date', 'death_date'),
308          },
309          untaint_all_constraints => 1,
310        };
311
312       If the value is untainted (using "untaint_all_constraints" or
313       "untaint_constraint_fields", it will change the date string into a
314       DateTime object.
315
317   to_mysql_datetime
318       The routine will change the date string into a DATETIME datatype
319       suitable for MySQL. If you don't provide a format parameter then this
320       routine will just validate the data as a valid MySQL DATETIME datatype
321       (using DateTime::Format::MySQL).
322
323       If the value is untainted (using "untaint_all_constraints" or
324       "untaint_constraint_fields", it will change the date string into a
325       DateTime object.
326
327   to_mysql_date
328       The routine will change the date string into a DATE datatype suitable
329       for MySQL. If you don't provide a format param then this routine will
330       validate the data as a valid DATE datatype in MySQL (using
331       DateTime::Format::MySQL).
332
333       If the value is untainted (using "untaint_all_constraints" or
334       "untaint_constraint_fields", it will change the date string into a
335       DateTime object.
336
337   to_mysql_timestamp
338       The routine will change the date string into a TIMESTAMP datatype
339       suitable for MySQL. If you don't provide a format then the data will be
340       validated as a MySQL TIMESTAMP datatype.
341
342       If the value is untainted (using "untaint_all_constraints" or
343       "untaint_constraint_fields", it will change the date string into a
344       DateTime object.
345
346   to_pg_datetime
347       The routine will change the date string into a DATETIME datatype
348       suitable for PostgreSQL. If you don't provide a format then the data
349       will validated as a DATETIME datatype in PostgresSQL (using
350       DateTime::Format::Pg).
351
352       If the value is untainted (using "untaint_all_constraints" or
353       "untaint_constraint_fields", it will change the date string into a
354       DateTime object.
355

AUTHOR

357       Michael Peters <mpeters@plusthree.com>
358
359       Thanks to Plus Three, LP (http://www.plusthree.com) for sponsoring my
360       work on this module
361

CONTRIBUTORS

363       Mark Stosberg <mark@summersault.com>
364       Charles Frank <cfrank@plusthree.com>
365       Aaron Ross <aaronelliotross@gmail.com>
366

SUPPORT

368       This module is a part of the larger Data::FormValidator project. If you
369       have questions, comments, bug reports or feature requests, please join
370       the Data::FormValidator's mailing list.
371

CAVEAT

373       When passing parameters to typical Data::FormValidator constraints you
374       pass plain scalars to refer to query params and scalar-refs to refer to
375       literals. We get around that in this module by assuming everything
376       could be refering to a query param, and if one is not found, then it's
377       a literal. This works well unless you have query params with names like
378       '01/02/2005' or '%m/%d/%Y'.
379
380       And if you do, shame on you for having such horrible names.
381

SEE ALSO

383       Data::FormValidator, DateTime. DateTime::Format::Strptime,
384       DateTime::Format::MySQL, DateTime::Format::Pg
385
387       Copyright Michael Peters 2010, all rights reserved.
388
389       This library is free software; you can redistribute it and/or modify it
390       under the same terms as Perl itself.
391
392
393
394perl v5.36.0                     D2a0t2a2:-:0F7o-r2m2Validator::Constraints::DateTime(3)
Impressum