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