1Data::FormValidator::CoUnssetrraCionnttsr:i:bDDuaattteaed:T:iPFmeoerr(lm3V)Daolciudmaetnotra:t:iCoonnstraints::DateTime(3)
2
6 Data::FormValidator::Constraints::DateTime - D::FV constraints for
7 dates and times
8
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
18 use Data::FormValidator;
19 use Data::FormValidator::Constraints::DateTime qw(:all);
20 # 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 # validate 'my_date'
31 my $results = Data::FormValidator->check($my_input, $profile);
32 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
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 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 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 without a format param
61 my $profile = {
63 required => [qw(my_date)],
64 constraint_methods => {
65 my_date => to_mysql_datetime(),
66 },
67 };
68 with a format param
70 my $profile = {
72 required => [qw(my_date)],
73 constraint_methods => {
74 my_date => to_mysql_datetime('%m/%d/%Y'),
75 },
76 };
77 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 # your formatter code
88 package MyProject::DateTime::FlexYear;
89 use DateTime::Format::Strptime;
90 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 1;
101 # 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
111 Following is the list of validation routines that are provided by this
112 module.
113 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 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 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 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 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 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 If it validates and you tell D::FV to untaint this parameter it will be
149 converted into a DateTime object.
150 # 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 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 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 If it validates and you tell D::FV to untaint this parameter it will be
169 converted into a DateTime object.
170 # 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 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 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 If it validates and you tell D::FV to untaint this parameter it will be
190 converted into a DateTime object.
191 # 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 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 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 If it validates and you tell D::FV to untaint this parameter it will be
211 converted into a DateTime object.
212 # 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 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 before_datetime
227 This routine will validate the date and make sure it occurs before the
228 specified date. It takes two params:
229 • first, the strptime format
231 (for both the date we are validating and also the date we want to
233 compare against)
234 • second, the date we are comparing against.
236 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 If it validates and you tell D::FV to untaint this parameter it will be
242 converted into a DateTime object.
243 # 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 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 after_datetime
258 This routine will validate the date and make sure it occurs after the
259 specified date. It takes two params:
260 • first, the strptime format
262 (for both the date we are validating and also the date we want to
264 compare against)
265 • second, the date we are comparing against.
267 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 # 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 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 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 • first, the strptime format
291 (for both the date we are validating and also the dates we want to
293 compare against)
294 • second, the first date we are comparing against.
296 • third, the second date we are comparing against.
298 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 # 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 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 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 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 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 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 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 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 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
357 Michael Peters <mpeters@plusthree.com>
358 Thanks to Plus Three, LP (http://www.plusthree.com) for sponsoring my
360 work on this module
361
363 Mark Stosberg <mark@summersault.com>
364 Charles Frank <cfrank@plusthree.com>
365 Aaron Ross <aaronelliotross@gmail.com>
366
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
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 And if you do, shame on you for having such horrible names.
381
383 Data::FormValidator, DateTime. DateTime::Format::Strptime,
384 DateTime::Format::MySQL, DateTime::Format::Pg
385
387 Copyright Michael Peters 2010, all rights reserved.
388 This library is free software; you can redistribute it and/or modify it
390 under the same terms as Perl itself.
391perl v5.36.0 D2a0t2a3:-:0F1o-r2m0Validator::Constraints::DateTime(3)