- Add _post_inflate_datetime and _pre_deflate_datetime to InflateColumn::DateTime...
[dbsrgits/DBIx-Class-Historic.git] / lib / DBIx / Class / InflateColumn / DateTime.pm
CommitLineData
445e5e31 1package DBIx::Class::InflateColumn::DateTime;
2
3use strict;
4use warnings;
5use base qw/DBIx::Class/;
341d5ede 6use Carp::Clan qw/^DBIx::Class/;
445e5e31 7
0b375b68 8=head1 NAME
9
5d0a2955 10DBIx::Class::InflateColumn::DateTime - Auto-create DateTime objects from date and datetime columns.
0b375b68 11
12=head1 SYNOPSIS
13
14Load this component and then declare one or more
679a304a 15columns 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
26Then 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 31If 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 37If you want to inflate no matter what data_type your column is,
38use 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 48It'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 54NOTE: Don't rely on C<InflateColumn::DateTime> to parse date strings for you.
55The column is set directly for any non-references and C<InflateColumn::DateTime>
56is completely bypassed. Instead, use an input parser to create a DateTime
57object. For instance, if your user input comes as a 'YYYY-MM-DD' string, you can
58use 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
65This module figures out the type of DateTime::Format::* class to
66inflate/deflate with based on the type of DBIx::Class::Storage::DBI::*
67that you are using. If you switch from one database to a different
5d0a2955 68one your code should continue to work without modification (though note
69that this feature is new as of 0.07, so it may not be perfect yet - bug
70reports to the list very much welcome).
0b375b68 71
9c71b5e2 72If the data_type of a field is C<date>, C<datetime> or C<timestamp> (or
f59e543b 73a derivative of these datatypes, e.g. C<timestamp with timezone>), this
9c71b5e2 74module will automatically call the appropriate parse/format method for
75deflation/inflation as defined in the storage class. For instance, for
76a C<datetime> field the methods C<parse_datetime> and C<format_datetime>
77would be called on deflation/inflation. If the storage class does not
78provide a specialized inflator/deflator, C<[parse|format]_datetime> will
79be used as a fallback. See L<DateTime::Format> for more information on
80date formatting.
81
943f93f2 82For 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
90Chains with the L<DBIx::Class::Row/register_column> method, and sets
91up datetime columns appropriately. This would not normally be
92directly called by end users.
93
33a126ef 94In the case of an invalid date, L<DateTime> will throw an exception. To
95bypass these exceptions and just have the inflation return undef, use
96the 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 108sub 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
dda9af55 139 my $timezone;
8d689133 140 if ( defined $info->{extra}{timezone} ) {
341d5ede 141 carp "Putting timezone into extra => { timezone => '...' } has been deprecated, ".
6c9d0c63 142 "please put it directly into the '$column' column definition.";
dda9af55 143 $timezone = $info->{extra}{timezone};
144 }
145
8d689133 146 my $locale;
147 if ( defined $info->{extra}{locale} ) {
341d5ede 148 carp "Putting locale into extra => { locale => '...' } has been deprecated, ".
6c9d0c63 149 "please put it directly into the '$column' column definition.";
8d689133 150 $locale = $info->{extra}{locale};
151 }
d4daee7b 152
92ed0695 153 $locale = $info->{locale} if defined $info->{locale};
154 $timezone = $info->{timezone} if defined $info->{timezone};
8d689133 155
dceeddc7 156 my $undef_if_invalid = $info->{datetime_undef_if_invalid};
157
abc914bd 158 if ($type eq 'datetime' || $type eq 'date' || $type eq 'timestamp') {
ab969dd4 159 # This shallow copy of %info avoids t/52_cycle.t treating
160 # the resulting deflator as a circular reference.
161 my %info = ( '_ic_dt_method' => $type , %{ $info } );
162
92ed0695 163 if (defined $info->{extra}{floating_tz_ok}) {
341d5ede 164 carp "Putting floating_tz_ok into extra => { floating_tz_ok => 1 } has been deprecated, ".
6c9d0c63 165 "please put it directly into the '$column' column definition.";
b1e4a1df 166 $info{floating_tz_ok} = $info->{extra}{floating_tz_ok};
92ed0695 167 }
45147005 168
445e5e31 169 $self->inflate_column(
170 $column =>
171 {
172 inflate => sub {
173 my ($value, $obj) = @_;
40f75181 174
ab969dd4 175 my $dt = eval { $obj->_inflate_to_datetime( $value, \%info ) };
40f75181 176 if (my $err = $@ ) {
177 return undef if ($undef_if_invalid);
178 $self->throw_exception ("Error while inflating ${value} for ${column} on ${self}: $err");
179 }
180
f856fe01 181 return $obj->_post_inflate_datetime( $dt, \%info );
445e5e31 182 },
183 deflate => sub {
184 my ($value, $obj) = @_;
f856fe01 185
186 $value = $obj->_pre_deflate_datetime( $value, \%info );
ab969dd4 187 $obj->_deflate_from_datetime( $value, \%info );
445e5e31 188 },
189 }
190 );
191 }
192}
193
ab969dd4 194sub _flate_or_fallback
195{
196 my( $self, $value, $info, $method_fmt ) = @_;
197
198 my $parser = $self->_datetime_parser;
199 my $preferred_method = sprintf($method_fmt, $info->{ _ic_dt_method });
200 my $method = $parser->can($preferred_method) ? $preferred_method : sprintf($method_fmt, 'datetime');
201 return $parser->$method($value);
202}
203
204sub _inflate_to_datetime {
205 my( $self, $value, $info ) = @_;
206 return $self->_flate_or_fallback( $value, $info, 'parse_%s' );
207}
208
209sub _deflate_from_datetime {
210 my( $self, $value, $info ) = @_;
211 return $self->_flate_or_fallback( $value, $info, 'format_%s' );
212}
abc914bd 213
445e5e31 214sub _datetime_parser {
f568d83b 215 shift->result_source->storage->datetime_parser (@_);
445e5e31 216}
217
f856fe01 218sub _post_inflate_datetime {
219 my( $self, $dt, $info ) = @_;
220
221 my $timezone;
222 if (exists $info->{timezone}) {
223 $timezone = $info->{timezone};
224 }
225 elsif (exists $info->{extra} and exists $info->{extra}{timezone}) {
226 $timezone = $info->{extra}{timezone};
227 }
228
229 my $locale;
230 if (exists $info->{locale}) {
231 $locale = $info->{locale};
232 }
233 elsif (exists $info->{extra} and exists $info->{extra}{locale}) {
234 $locale = $info->{extra}{locale};
235 }
236
237 $dt->set_time_zone($timezone) if $timezone;
238 $dt->set_locale($locale) if $locale;
239
240 return $dt;
241}
242
243sub _pre_deflate_datetime {
244 my( $self, $dt, $info ) = @_;
245
246 my $timezone;
247 if (exists $info->{timezone}) {
248 $timezone = $info->{timezone};
249 }
250 elsif (exists $info->{extra} and exists $info->{extra}{timezone}) {
251 $timezone = $info->{extra}{timezone};
252 }
253
254 my $locale;
255 if (exists $info->{locale}) {
256 $locale = $info->{locale};
257 }
258 elsif (exists $info->{extra} and exists $info->{extra}{locale}) {
259 $locale = $info->{extra}{locale};
260 }
261
262 if ($timezone) {
263 carp "You're using a floating timezone, please see the documentation of"
264 . " DBIx::Class::InflateColumn::DateTime for an explanation"
265 if ref( $dt->time_zone ) eq 'DateTime::TimeZone::Floating'
266 and not $info->{floating_tz_ok}
267 and not $ENV{DBIC_FLOATING_TZ_OK};
268
269 $dt->set_time_zone($timezone);
270 }
271
272 $dt->set_locale($locale) if $locale;
273
274 return $dt;
275}
276
445e5e31 2771;
0b375b68 278__END__
279
45147005 280=head1 USAGE NOTES
281
97983826 282If you have a datetime column with an associated C<timezone>, and subsequently
45147005 283create/update this column with a DateTime object in the L<DateTime::TimeZone::Floating>
284timezone, you will get a warning (as there is a very good chance this will not have the
285result you expect). For example:
286
287 __PACKAGE__->add_columns(
92ed0695 288 starts_when => { data_type => 'datetime', timezone => "America/Chicago" }
45147005 289 );
290
291 my $event = $schema->resultset('EventTZ')->create({
292 starts_at => DateTime->new(year=>2007, month=>12, day=>31, ),
293 });
294
295The warning can be avoided in several ways:
296
297=over
298
299=item Fix your broken code
300
301When calling C<set_time_zone> on a Floating DateTime object, the timezone is simply
302set to the requested value, and B<no time conversion takes place>. It is always a good idea
303to be supply explicit times to the database:
304
305 my $event = $schema->resultset('EventTZ')->create({
306 starts_at => DateTime->new(year=>2007, month=>12, day=>31, time_zone => "America/Chicago" ),
307 });
308
309=item Suppress the check on per-column basis
310
311 __PACKAGE__->add_columns(
92ed0695 312 starts_when => { data_type => 'datetime', timezone => "America/Chicago", floating_tz_ok => 1 }
45147005 313 );
314
315=item Suppress the check globally
316
317Set the environment variable DBIC_FLOATING_TZ_OK to some true value.
318
319=back
320
92ed0695 321Putting extra attributes like timezone, locale or floating_tz_ok into extra => {} has been
322B<DEPRECATED> because this gets you into trouble using L<DBIx::Class::Schema::Versioned>.
323Instead put it directly into the columns definition like in the examples above. If you still
324use the old way you'll see a warning - please fix your code then!
45147005 325
0b375b68 326=head1 SEE ALSO
327
328=over 4
329
330=item More information about the add_columns method, and column metadata,
331 can be found in the documentation for L<DBIx::Class::ResultSource>.
332
45147005 333=item Further discussion of problems inherent to the Floating timezone:
334 L<Floating DateTimes|DateTime/Floating_DateTimes>
335 and L<< $dt->set_time_zone|DateTime/"Set" Methods >>
336
0b375b68 337=back
338
339=head1 AUTHOR
340
341Matt S. Trout <mst@shadowcatsystems.co.uk>
342
343=head1 CONTRIBUTORS
344
345Aran Deltac <bluefeet@cpan.org>
346
347=head1 LICENSE
348
349You may distribute this code under the same terms as Perl itself.
350