Commit | Line | Data |
445e5e31 |
1 | package DBIx::Class::InflateColumn::DateTime; |
2 | |
3 | use strict; |
4 | use warnings; |
5 | use base qw/DBIx::Class/; |
6 | |
0b375b68 |
7 | =head1 NAME |
8 | |
5d0a2955 |
9 | DBIx::Class::InflateColumn::DateTime - Auto-create DateTime objects from date and datetime columns. |
0b375b68 |
10 | |
11 | =head1 SYNOPSIS |
12 | |
13 | Load this component and then declare one or more |
679a304a |
14 | columns to be of the datetime, timestamp or date datatype. |
0b375b68 |
15 | |
16 | package Event; |
517d5d64 |
17 | __PACKAGE__->load_components(qw/InflateColumn::DateTime Core/); |
0b375b68 |
18 | __PACKAGE__->add_columns( |
19 | starts_when => { data_type => 'datetime' } |
20 | ); |
21 | |
2c96eeed |
22 | NOTE: You B<must> load C<InflateColumn::DateTime> B<before> C<Core>. See |
23 | L<DBIx::Class::Manual::Component> for details. |
24 | |
0b375b68 |
25 | Then you can treat the specified column as a L<DateTime> object. |
26 | |
27 | print "This event starts the month of ". |
28 | $event->starts_when->month_name(); |
29 | |
8d689133 |
30 | If you want to set a specific timezone and locale for that field, use: |
dda9af55 |
31 | |
32 | __PACKAGE__->add_columns( |
92ed0695 |
33 | starts_when => { data_type => 'datetime', timezone => "America/Chicago", locale => "de_DE" } |
dda9af55 |
34 | ); |
35 | |
a97fe7e0 |
36 | If you want to inflate no matter what data_type your column is, |
37 | use inflate_datetime or inflate_date: |
38 | |
39 | __PACKAGE__->add_columns( |
40 | starts_when => { data_type => 'varchar', inflate_datetime => 1 } |
41 | ); |
42 | |
43 | __PACKAGE__->add_columns( |
44 | starts_when => { data_type => 'varchar', inflate_date => 1 } |
45 | ); |
46 | |
ff8a6e3b |
47 | It's also possible to explicitly skip inflation: |
48 | |
49 | __PACKAGE__->add_columns( |
50 | starts_when => { data_type => 'datetime', inflate_datetime => 0 } |
51 | ); |
52 | |
0b375b68 |
53 | =head1 DESCRIPTION |
54 | |
55 | This module figures out the type of DateTime::Format::* class to |
56 | inflate/deflate with based on the type of DBIx::Class::Storage::DBI::* |
57 | that you are using. If you switch from one database to a different |
5d0a2955 |
58 | one your code should continue to work without modification (though note |
59 | that this feature is new as of 0.07, so it may not be perfect yet - bug |
60 | reports to the list very much welcome). |
0b375b68 |
61 | |
943f93f2 |
62 | For more help with using components, see L<DBIx::Class::Manual::Component/USING>. |
de78905b |
63 | |
0b375b68 |
64 | =cut |
65 | |
445e5e31 |
66 | __PACKAGE__->load_components(qw/InflateColumn/); |
67 | |
68 | __PACKAGE__->mk_group_accessors('simple' => '__datetime_parser'); |
69 | |
9b83fccd |
70 | =head2 register_column |
71 | |
72 | Chains with the L<DBIx::Class::Row/register_column> method, and sets |
73 | up datetime columns appropriately. This would not normally be |
74 | directly called by end users. |
75 | |
33a126ef |
76 | In the case of an invalid date, L<DateTime> will throw an exception. To |
77 | bypass these exceptions and just have the inflation return undef, use |
78 | the C<datetime_undef_if_invalid> option in the column info: |
79 | |
80 | "broken_date", |
81 | { |
82 | data_type => "datetime", |
83 | default_value => '0000-00-00', |
84 | is_nullable => 1, |
85 | datetime_undef_if_invalid => 1 |
86 | } |
87 | |
9b83fccd |
88 | =cut |
89 | |
445e5e31 |
90 | sub register_column { |
91 | my ($self, $column, $info, @rest) = @_; |
92 | $self->next::method($column, $info, @rest); |
c209c4fd |
93 | return unless defined($info->{data_type}); |
bb90689c |
94 | |
95 | my $type; |
96 | |
abc914bd |
97 | for (qw/date datetime timestamp/) { |
bb90689c |
98 | my $key = "inflate_${_}"; |
99 | |
100 | next unless exists $info->{$key}; |
101 | return unless $info->{$key}; |
102 | |
103 | $type = $_; |
104 | last; |
105 | } |
106 | |
107 | unless ($type) { |
108 | $type = lc($info->{data_type}); |
bb90689c |
109 | } |
110 | |
dda9af55 |
111 | my $timezone; |
8d689133 |
112 | if ( defined $info->{extra}{timezone} ) { |
92ed0695 |
113 | warn "Putting timezone into extra => { timezone => '...' } has been deprecated, ". |
114 | "please put it directly into the columns definition."; |
dda9af55 |
115 | $timezone = $info->{extra}{timezone}; |
116 | } |
117 | |
8d689133 |
118 | my $locale; |
119 | if ( defined $info->{extra}{locale} ) { |
92ed0695 |
120 | warn "Putting locale into extra => { locale => '...' } has been deprecated, ". |
121 | "please put it directly into the columns definition."; |
8d689133 |
122 | $locale = $info->{extra}{locale}; |
123 | } |
92ed0695 |
124 | |
125 | $locale = $info->{locale} if defined $info->{locale}; |
126 | $timezone = $info->{timezone} if defined $info->{timezone}; |
8d689133 |
127 | |
dceeddc7 |
128 | my $undef_if_invalid = $info->{datetime_undef_if_invalid}; |
129 | |
abc914bd |
130 | if ($type eq 'datetime' || $type eq 'date' || $type eq 'timestamp') { |
c209c4fd |
131 | my ($parse, $format) = ("parse_${type}", "format_${type}"); |
45147005 |
132 | |
133 | # This assignment must happen here, otherwise Devel::Cycle treats |
134 | # the resulting deflator as a circular reference (go figure): |
135 | # |
136 | # Cycle #1 |
137 | # DBICTest::Schema A->{source_registrations} => %B |
138 | # %B->{Event} => DBIx::Class::ResultSource::Table C |
139 | # DBIx::Class::ResultSource::Table C->{_columns} => %D |
140 | # %D->{created_on} => %E |
141 | # %E->{_inflate_info} => %F |
142 | # %F->{deflate} => &G |
143 | # closure &G, $info => $H |
144 | # $H => %E |
145 | # |
92ed0695 |
146 | my $floating_tz_ok; |
147 | if (defined $info->{extra}{floating_tz_ok}) { |
148 | warn "Putting floating_tz_ok into extra => { floating_tz_ok => 1 } has been deprecated, ". |
149 | "please put it directly into the columns definition."; |
150 | $floating_tz_ok = $info->{extra}{floating_tz_ok}; |
151 | } |
152 | $floating_tz_ok = $info->{floating_tz_ok} if defined $info->{floating_tz_ok}; |
45147005 |
153 | |
445e5e31 |
154 | $self->inflate_column( |
155 | $column => |
156 | { |
157 | inflate => sub { |
158 | my ($value, $obj) = @_; |
abc914bd |
159 | my $parser = $obj->_datetime_parser; |
160 | my $parser_method = $parser->can($parse) ? $parse : "parse_datetime"; |
161 | my $dt = eval { $parser->$parser_method($value); }; |
dceeddc7 |
162 | die "Error while inflating ${value} for ${column} on ${self}: $@" |
163 | if $@ and not $undef_if_invalid; |
dda9af55 |
164 | $dt->set_time_zone($timezone) if $timezone; |
8d689133 |
165 | $dt->set_locale($locale) if $locale; |
dda9af55 |
166 | return $dt; |
445e5e31 |
167 | }, |
168 | deflate => sub { |
169 | my ($value, $obj) = @_; |
abc914bd |
170 | my $parser = $obj->_datetime_parser; |
171 | my $parser_method = $parser->can($format) ? $format : "format_datetime"; |
47cd9169 |
172 | if ($timezone) { |
173 | warn "You're using a floating timezone, please see the documentation of" |
174 | . " DBIx::Class::InflateColumn::DateTime for an explanation" |
175 | if ref( $value->time_zone ) eq 'DateTime::TimeZone::Floating' |
176 | and not $floating_tz_ok |
177 | and not $ENV{DBIC_FLOATING_TZ_OK}; |
178 | $value->set_time_zone($timezone); |
8d689133 |
179 | $value->set_locale($locale) if $locale; |
47cd9169 |
180 | } |
abc914bd |
181 | $parser->$parser_method($value); |
445e5e31 |
182 | }, |
183 | } |
184 | ); |
185 | } |
186 | } |
187 | |
abc914bd |
188 | |
445e5e31 |
189 | sub _datetime_parser { |
190 | my $self = shift; |
191 | if (my $parser = $self->__datetime_parser) { |
192 | return $parser; |
193 | } |
194 | my $parser = $self->result_source->storage->datetime_parser(@_); |
195 | return $self->__datetime_parser($parser); |
196 | } |
197 | |
198 | 1; |
0b375b68 |
199 | __END__ |
200 | |
45147005 |
201 | =head1 USAGE NOTES |
202 | |
203 | If you have a datetime column with the C<timezone> extra setting, and subsenquently |
204 | create/update this column with a DateTime object in the L<DateTime::TimeZone::Floating> |
205 | timezone, you will get a warning (as there is a very good chance this will not have the |
206 | result you expect). For example: |
207 | |
208 | __PACKAGE__->add_columns( |
92ed0695 |
209 | starts_when => { data_type => 'datetime', timezone => "America/Chicago" } |
45147005 |
210 | ); |
211 | |
212 | my $event = $schema->resultset('EventTZ')->create({ |
213 | starts_at => DateTime->new(year=>2007, month=>12, day=>31, ), |
214 | }); |
215 | |
216 | The warning can be avoided in several ways: |
217 | |
218 | =over |
219 | |
220 | =item Fix your broken code |
221 | |
222 | When calling C<set_time_zone> on a Floating DateTime object, the timezone is simply |
223 | set to the requested value, and B<no time conversion takes place>. It is always a good idea |
224 | to be supply explicit times to the database: |
225 | |
226 | my $event = $schema->resultset('EventTZ')->create({ |
227 | starts_at => DateTime->new(year=>2007, month=>12, day=>31, time_zone => "America/Chicago" ), |
228 | }); |
229 | |
230 | =item Suppress the check on per-column basis |
231 | |
232 | __PACKAGE__->add_columns( |
92ed0695 |
233 | starts_when => { data_type => 'datetime', timezone => "America/Chicago", floating_tz_ok => 1 } |
45147005 |
234 | ); |
235 | |
236 | =item Suppress the check globally |
237 | |
238 | Set the environment variable DBIC_FLOATING_TZ_OK to some true value. |
239 | |
240 | =back |
241 | |
92ed0695 |
242 | Putting extra attributes like timezone, locale or floating_tz_ok into extra => {} has been |
243 | B<DEPRECATED> because this gets you into trouble using L<DBIx::Class::Schema::Versioned>. |
244 | Instead put it directly into the columns definition like in the examples above. If you still |
245 | use the old way you'll see a warning - please fix your code then! |
45147005 |
246 | |
0b375b68 |
247 | =head1 SEE ALSO |
248 | |
249 | =over 4 |
250 | |
251 | =item More information about the add_columns method, and column metadata, |
252 | can be found in the documentation for L<DBIx::Class::ResultSource>. |
253 | |
45147005 |
254 | =item Further discussion of problems inherent to the Floating timezone: |
255 | L<Floating DateTimes|DateTime/Floating_DateTimes> |
256 | and L<< $dt->set_time_zone|DateTime/"Set" Methods >> |
257 | |
0b375b68 |
258 | =back |
259 | |
260 | =head1 AUTHOR |
261 | |
262 | Matt S. Trout <mst@shadowcatsystems.co.uk> |
263 | |
264 | =head1 CONTRIBUTORS |
265 | |
266 | Aran Deltac <bluefeet@cpan.org> |
267 | |
268 | =head1 LICENSE |
269 | |
270 | You may distribute this code under the same terms as Perl itself. |
271 | |