Commit | Line | Data |
445e5e31 |
1 | package DBIx::Class::InflateColumn::DateTime; |
2 | |
3 | use strict; |
4 | use warnings; |
5 | use base qw/DBIx::Class/; |
70c28808 |
6 | use DBIx::Class::Carp; |
ddcc02d1 |
7 | use DBIx::Class::_Util 'dbic_internal_try'; |
ed7ab0f4 |
8 | use Try::Tiny; |
fd323bf1 |
9 | use namespace::clean; |
445e5e31 |
10 | |
0b375b68 |
11 | =head1 NAME |
12 | |
5d0a2955 |
13 | DBIx::Class::InflateColumn::DateTime - Auto-create DateTime objects from date and datetime columns. |
0b375b68 |
14 | |
15 | =head1 SYNOPSIS |
16 | |
fd323bf1 |
17 | Load this component and then declare one or more |
679a304a |
18 | columns to be of the datetime, timestamp or date datatype. |
0b375b68 |
19 | |
20 | package Event; |
d88ecca6 |
21 | use base 'DBIx::Class::Core'; |
22 | |
23 | __PACKAGE__->load_components(qw/InflateColumn::DateTime/); |
0b375b68 |
24 | __PACKAGE__->add_columns( |
25 | starts_when => { data_type => 'datetime' } |
9c71b5e2 |
26 | create_date => { data_type => 'date' } |
0b375b68 |
27 | ); |
28 | |
29 | Then you can treat the specified column as a L<DateTime> object. |
30 | |
31 | print "This event starts the month of ". |
32 | $event->starts_when->month_name(); |
33 | |
eef9b484 |
34 | If you want to set a specific time zone and locale for that field, use: |
dda9af55 |
35 | |
36 | __PACKAGE__->add_columns( |
eef9b484 |
37 | starts_when => { data_type => 'datetime', time_zone => "America/Chicago", locale => "de_DE" } |
dda9af55 |
38 | ); |
39 | |
eef9b484 |
40 | Note: DBIC before 0.082900 only accepted C<timezone>, and silently discarded |
41 | any C<time_zone> arguments. For backwards compatibility, C<timezone> will |
591df363 |
42 | continue being accepted as a synonym for C<time_zone>, and the value will |
43 | continue to be available in the |
44 | L<< C<column_info> hash|DBIx::Class::ResultSource/column_info >> |
45 | under both names. |
eef9b484 |
46 | |
a97fe7e0 |
47 | If you want to inflate no matter what data_type your column is, |
48 | use inflate_datetime or inflate_date: |
49 | |
50 | __PACKAGE__->add_columns( |
51 | starts_when => { data_type => 'varchar', inflate_datetime => 1 } |
52 | ); |
d4daee7b |
53 | |
a97fe7e0 |
54 | __PACKAGE__->add_columns( |
55 | starts_when => { data_type => 'varchar', inflate_date => 1 } |
56 | ); |
57 | |
ff8a6e3b |
58 | It's also possible to explicitly skip inflation: |
d4daee7b |
59 | |
ff8a6e3b |
60 | __PACKAGE__->add_columns( |
61 | starts_when => { data_type => 'datetime', inflate_datetime => 0 } |
62 | ); |
63 | |
8bf37b16 |
64 | NOTE: Don't rely on C<InflateColumn::DateTime> to parse date strings for you. |
65 | The column is set directly for any non-references and C<InflateColumn::DateTime> |
66 | is completely bypassed. Instead, use an input parser to create a DateTime |
67 | object. For instance, if your user input comes as a 'YYYY-MM-DD' string, you can |
68 | use C<DateTime::Format::ISO8601> thusly: |
d6aed638 |
69 | |
70 | use DateTime::Format::ISO8601; |
71 | my $dt = DateTime::Format::ISO8601->parse_datetime('YYYY-MM-DD'); |
72 | |
0b375b68 |
73 | =head1 DESCRIPTION |
74 | |
fd323bf1 |
75 | This module figures out the type of DateTime::Format::* class to |
76 | inflate/deflate with based on the type of DBIx::Class::Storage::DBI::* |
77 | that you are using. If you switch from one database to a different |
5d0a2955 |
78 | one your code should continue to work without modification (though note |
79 | that this feature is new as of 0.07, so it may not be perfect yet - bug |
80 | reports to the list very much welcome). |
0b375b68 |
81 | |
9c71b5e2 |
82 | If the data_type of a field is C<date>, C<datetime> or C<timestamp> (or |
eef9b484 |
83 | a derivative of these datatypes, e.g. C<timestamp with time zone>), this |
9c71b5e2 |
84 | module will automatically call the appropriate parse/format method for |
85 | deflation/inflation as defined in the storage class. For instance, for |
86 | a C<datetime> field the methods C<parse_datetime> and C<format_datetime> |
87 | would be called on deflation/inflation. If the storage class does not |
88 | provide a specialized inflator/deflator, C<[parse|format]_datetime> will |
5529838f |
89 | be used as a fallback. See L<DateTime/Formatters And Stringification> |
90 | for more information on date formatting. |
9c71b5e2 |
91 | |
943f93f2 |
92 | For more help with using components, see L<DBIx::Class::Manual::Component/USING>. |
de78905b |
93 | |
0b375b68 |
94 | =cut |
95 | |
445e5e31 |
96 | __PACKAGE__->load_components(qw/InflateColumn/); |
97 | |
9b83fccd |
98 | =head2 register_column |
99 | |
100 | Chains with the L<DBIx::Class::Row/register_column> method, and sets |
101 | up datetime columns appropriately. This would not normally be |
102 | directly called by end users. |
103 | |
33a126ef |
104 | In the case of an invalid date, L<DateTime> will throw an exception. To |
105 | bypass these exceptions and just have the inflation return undef, use |
106 | the C<datetime_undef_if_invalid> option in the column info: |
d4daee7b |
107 | |
33a126ef |
108 | "broken_date", |
109 | { |
110 | data_type => "datetime", |
111 | default_value => '0000-00-00', |
112 | is_nullable => 1, |
113 | datetime_undef_if_invalid => 1 |
114 | } |
115 | |
9b83fccd |
116 | =cut |
117 | |
445e5e31 |
118 | sub register_column { |
119 | my ($self, $column, $info, @rest) = @_; |
49bceca3 |
120 | |
445e5e31 |
121 | $self->next::method($column, $info, @rest); |
bb90689c |
122 | |
49bceca3 |
123 | my $requested_type; |
bbe0a14d |
124 | for (qw/datetime timestamp date/) { |
bb90689c |
125 | my $key = "inflate_${_}"; |
bbe0a14d |
126 | if (exists $info->{$key}) { |
bb90689c |
127 | |
bbe0a14d |
128 | # this bailout is intentional |
129 | return unless $info->{$key}; |
49bceca3 |
130 | |
bbe0a14d |
131 | $requested_type = $_; |
132 | last; |
133 | } |
bb90689c |
134 | } |
135 | |
bbe0a14d |
136 | return if (!$requested_type and !$info->{data_type}); |
137 | |
138 | my $data_type = lc( $info->{data_type} || '' ); |
49bceca3 |
139 | |
140 | # _ic_dt_method will follow whatever the registration requests |
141 | # thus = instead of ||= |
142 | if ($data_type eq 'timestamp with time zone' || $data_type eq 'timestamptz') { |
143 | $info->{_ic_dt_method} = 'timestamp_with_timezone'; |
144 | } |
145 | elsif ($data_type eq 'timestamp without time zone') { |
146 | $info->{_ic_dt_method} = 'timestamp_without_timezone'; |
147 | } |
148 | elsif ($data_type eq 'smalldatetime') { |
149 | $info->{_ic_dt_method} = 'smalldatetime'; |
150 | } |
151 | elsif ($data_type =~ /^ (?: date | datetime | timestamp ) $/x) { |
152 | $info->{_ic_dt_method} = $data_type; |
153 | } |
bbe0a14d |
154 | elsif ($requested_type) { |
49bceca3 |
155 | $info->{_ic_dt_method} = $requested_type; |
bb90689c |
156 | } |
bbe0a14d |
157 | else { |
158 | return; |
159 | } |
dda9af55 |
160 | |
226d1c35 |
161 | if ($info->{extra}) { |
eef9b484 |
162 | for my $slot (qw/time_zone timezone locale floating_tz_ok/) { |
226d1c35 |
163 | if ( defined $info->{extra}{$slot} ) { |
164 | carp "Putting $slot into extra => { $slot => '...' } has been deprecated, ". |
165 | "please put it directly into the '$column' column definition."; |
166 | $info->{$slot} = $info->{extra}{$slot} unless defined $info->{$slot}; |
167 | } |
1c2ffef9 |
168 | } |
8d689133 |
169 | } |
d4daee7b |
170 | |
591df363 |
171 | # Store the time zone under both 'timezone' for backwards compatibility and |
172 | # 'time_zone' for DateTime ecosystem consistency |
eef9b484 |
173 | if ( defined $info->{timezone} ) { |
591df363 |
174 | $self->throw_exception("Conflicting 'timezone' and 'time_zone' values in '$column' column defintion.") |
175 | if defined $info->{time_zone} and $info->{time_zone} ne $info->{timezone}; |
176 | $info->{time_zone} = $info->{timezone}; |
177 | } |
178 | elsif ( defined $info->{time_zone} ) { |
179 | $info->{timezone} = $info->{time_zone}; |
eef9b484 |
180 | } |
181 | |
226d1c35 |
182 | # shallow copy to avoid unfounded(?) Devel::Cycle complaints |
183 | my $infcopy = {%$info}; |
184 | |
185 | $self->inflate_column( |
186 | $column => |
187 | { |
188 | inflate => sub { |
189 | my ($value, $obj) = @_; |
190 | |
24f5cbcb |
191 | # propagate for error reporting |
192 | $infcopy->{__dbic_colname} = $column; |
193 | |
194 | my $dt = $obj->_inflate_to_datetime( $value, $infcopy ); |
226d1c35 |
195 | |
196 | return (defined $dt) |
197 | ? $obj->_post_inflate_datetime( $dt, $infcopy ) |
198 | : undef |
199 | ; |
200 | }, |
201 | deflate => sub { |
202 | my ($value, $obj) = @_; |
203 | |
204 | $value = $obj->_pre_deflate_datetime( $value, $infcopy ); |
205 | $obj->_deflate_from_datetime( $value, $infcopy ); |
206 | }, |
207 | } |
208 | ); |
445e5e31 |
209 | } |
210 | |
ab969dd4 |
211 | sub _flate_or_fallback |
212 | { |
213 | my( $self, $value, $info, $method_fmt ) = @_; |
214 | |
215 | my $parser = $self->_datetime_parser; |
216 | my $preferred_method = sprintf($method_fmt, $info->{ _ic_dt_method }); |
24f5cbcb |
217 | my $method = $parser->can($preferred_method) || sprintf($method_fmt, 'datetime'); |
218 | |
ddcc02d1 |
219 | return dbic_internal_try { |
24f5cbcb |
220 | $parser->$method($value); |
221 | } |
222 | catch { |
e705f529 |
223 | $self->throw_exception ("Error while inflating '$value' for $info->{__dbic_colname} on ${self}: $_") |
24f5cbcb |
224 | unless $info->{datetime_undef_if_invalid}; |
225 | undef; # rv |
226 | }; |
ab969dd4 |
227 | } |
228 | |
229 | sub _inflate_to_datetime { |
230 | my( $self, $value, $info ) = @_; |
231 | return $self->_flate_or_fallback( $value, $info, 'parse_%s' ); |
232 | } |
233 | |
234 | sub _deflate_from_datetime { |
235 | my( $self, $value, $info ) = @_; |
236 | return $self->_flate_or_fallback( $value, $info, 'format_%s' ); |
237 | } |
abc914bd |
238 | |
445e5e31 |
239 | sub _datetime_parser { |
e5053694 |
240 | shift->result_source->schema->storage->datetime_parser (@_); |
445e5e31 |
241 | } |
242 | |
f856fe01 |
243 | sub _post_inflate_datetime { |
244 | my( $self, $dt, $info ) = @_; |
245 | |
eef9b484 |
246 | $dt->set_time_zone($info->{time_zone}) if defined $info->{time_zone}; |
c3ed0bde |
247 | $dt->set_locale($info->{locale}) if defined $info->{locale}; |
f856fe01 |
248 | |
249 | return $dt; |
250 | } |
251 | |
252 | sub _pre_deflate_datetime { |
253 | my( $self, $dt, $info ) = @_; |
254 | |
eef9b484 |
255 | if (defined $info->{time_zone}) { |
256 | carp "You're using a floating time zone, please see the documentation of" |
f856fe01 |
257 | . " DBIx::Class::InflateColumn::DateTime for an explanation" |
258 | if ref( $dt->time_zone ) eq 'DateTime::TimeZone::Floating' |
259 | and not $info->{floating_tz_ok} |
260 | and not $ENV{DBIC_FLOATING_TZ_OK}; |
261 | |
eef9b484 |
262 | $dt->set_time_zone($info->{time_zone}); |
f856fe01 |
263 | } |
264 | |
c3ed0bde |
265 | $dt->set_locale($info->{locale}) if defined $info->{locale}; |
f856fe01 |
266 | |
267 | return $dt; |
268 | } |
269 | |
445e5e31 |
270 | 1; |
0b375b68 |
271 | __END__ |
272 | |
45147005 |
273 | =head1 USAGE NOTES |
274 | |
eef9b484 |
275 | If you have a datetime column with an associated C<time_zone>, and subsequently |
45147005 |
276 | create/update this column with a DateTime object in the L<DateTime::TimeZone::Floating> |
eef9b484 |
277 | time zone, you will get a warning (as there is a very good chance this will not have the |
45147005 |
278 | result you expect). For example: |
279 | |
280 | __PACKAGE__->add_columns( |
eef9b484 |
281 | starts_when => { data_type => 'datetime', time_zone => "America/Chicago" } |
45147005 |
282 | ); |
283 | |
284 | my $event = $schema->resultset('EventTZ')->create({ |
285 | starts_at => DateTime->new(year=>2007, month=>12, day=>31, ), |
286 | }); |
287 | |
288 | The warning can be avoided in several ways: |
289 | |
290 | =over |
291 | |
292 | =item Fix your broken code |
293 | |
eef9b484 |
294 | When calling C<set_time_zone> on a Floating DateTime object, the time zone is simply |
45147005 |
295 | set to the requested value, and B<no time conversion takes place>. It is always a good idea |
296 | to be supply explicit times to the database: |
297 | |
298 | my $event = $schema->resultset('EventTZ')->create({ |
299 | starts_at => DateTime->new(year=>2007, month=>12, day=>31, time_zone => "America/Chicago" ), |
300 | }); |
301 | |
302 | =item Suppress the check on per-column basis |
303 | |
304 | __PACKAGE__->add_columns( |
eef9b484 |
305 | starts_when => { data_type => 'datetime', time_zone => "America/Chicago", floating_tz_ok => 1 } |
45147005 |
306 | ); |
307 | |
308 | =item Suppress the check globally |
309 | |
310 | Set the environment variable DBIC_FLOATING_TZ_OK to some true value. |
311 | |
312 | =back |
313 | |
eef9b484 |
314 | Putting extra attributes like time_zone, locale or floating_tz_ok into extra => {} has been |
92ed0695 |
315 | B<DEPRECATED> because this gets you into trouble using L<DBIx::Class::Schema::Versioned>. |
316 | Instead put it directly into the columns definition like in the examples above. If you still |
317 | use the old way you'll see a warning - please fix your code then! |
45147005 |
318 | |
0b375b68 |
319 | =head1 SEE ALSO |
320 | |
321 | =over 4 |
322 | |
fd323bf1 |
323 | =item More information about the add_columns method, and column metadata, |
0b375b68 |
324 | can be found in the documentation for L<DBIx::Class::ResultSource>. |
325 | |
eef9b484 |
326 | =item Further discussion of problems inherent to the Floating time zone: |
9361b05d |
327 | L<Floating DateTimes|DateTime/Floating DateTimes> |
45147005 |
328 | and L<< $dt->set_time_zone|DateTime/"Set" Methods >> |
329 | |
0b375b68 |
330 | =back |
331 | |
a2bd3796 |
332 | =head1 FURTHER QUESTIONS? |
0b375b68 |
333 | |
a2bd3796 |
334 | Check the list of L<additional DBIC resources|DBIx::Class/GETTING HELP/SUPPORT>. |
0b375b68 |
335 | |
a2bd3796 |
336 | =head1 COPYRIGHT AND LICENSE |
0b375b68 |
337 | |
a2bd3796 |
338 | This module is free software L<copyright|DBIx::Class/COPYRIGHT AND LICENSE> |
339 | by the L<DBIx::Class (DBIC) authors|DBIx::Class/AUTHORS>. You can |
340 | redistribute it and/or modify it under the same terms as the |
341 | L<DBIx::Class library|DBIx::Class/COPYRIGHT AND LICENSE>. |