Merge 'trunk' into 'sqla_1.50_compat'
[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/;
6
0b375b68 7=head1 NAME
8
5d0a2955 9DBIx::Class::InflateColumn::DateTime - Auto-create DateTime objects from date and datetime columns.
0b375b68 10
11=head1 SYNOPSIS
12
13Load this component and then declare one or more
679a304a 14columns 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 22NOTE: You B<must> load C<InflateColumn::DateTime> B<before> C<Core>. See
23L<DBIx::Class::Manual::Component> for details.
24
0b375b68 25Then 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
dda9af55 30If you want to set a specific timezone for that field, use:
31
32 __PACKAGE__->add_columns(
33 starts_when => { data_type => 'datetime', extra => { timezone => "America/Chicago" } }
34 );
35
a97fe7e0 36If you want to inflate no matter what data_type your column is,
37use 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 47It'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
55This module figures out the type of DateTime::Format::* class to
56inflate/deflate with based on the type of DBIx::Class::Storage::DBI::*
57that you are using. If you switch from one database to a different
5d0a2955 58one your code should continue to work without modification (though note
59that this feature is new as of 0.07, so it may not be perfect yet - bug
60reports to the list very much welcome).
0b375b68 61
943f93f2 62For 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
72Chains with the L<DBIx::Class::Row/register_column> method, and sets
73up datetime columns appropriately. This would not normally be
74directly called by end users.
75
33a126ef 76In the case of an invalid date, L<DateTime> will throw an exception. To
77bypass these exceptions and just have the inflation return undef, use
78the 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 90sub 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
97 for (qw/date datetime/) {
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});
109 $type = 'datetime' if ($type =~ /^timestamp/);
110 }
111
dda9af55 112 my $timezone;
113 if ( exists $info->{extra} and exists $info->{extra}{timezone} and defined $info->{extra}{timezone} ) {
114 $timezone = $info->{extra}{timezone};
115 }
116
dceeddc7 117 my $undef_if_invalid = $info->{datetime_undef_if_invalid};
118
bb90689c 119 if ($type eq 'datetime' || $type eq 'date') {
c209c4fd 120 my ($parse, $format) = ("parse_${type}", "format_${type}");
45147005 121
122 # This assignment must happen here, otherwise Devel::Cycle treats
123 # the resulting deflator as a circular reference (go figure):
124 #
125 # Cycle #1
126 # DBICTest::Schema A->{source_registrations} => %B
127 # %B->{Event} => DBIx::Class::ResultSource::Table C
128 # DBIx::Class::ResultSource::Table C->{_columns} => %D
129 # %D->{created_on} => %E
130 # %E->{_inflate_info} => %F
131 # %F->{deflate} => &G
132 # closure &G, $info => $H
133 # $H => %E
134 #
135 my $floating_tz_ok = $info->{extra}{floating_tz_ok};
136
445e5e31 137 $self->inflate_column(
138 $column =>
139 {
140 inflate => sub {
141 my ($value, $obj) = @_;
33a126ef 142 my $dt = eval { $obj->_datetime_parser->$parse($value); };
dceeddc7 143 die "Error while inflating ${value} for ${column} on ${self}: $@"
144 if $@ and not $undef_if_invalid;
dda9af55 145 $dt->set_time_zone($timezone) if $timezone;
146 return $dt;
445e5e31 147 },
148 deflate => sub {
149 my ($value, $obj) = @_;
47cd9169 150 if ($timezone) {
151 warn "You're using a floating timezone, please see the documentation of"
152 . " DBIx::Class::InflateColumn::DateTime for an explanation"
153 if ref( $value->time_zone ) eq 'DateTime::TimeZone::Floating'
154 and not $floating_tz_ok
155 and not $ENV{DBIC_FLOATING_TZ_OK};
156 $value->set_time_zone($timezone);
157 }
c209c4fd 158 $obj->_datetime_parser->$format($value);
445e5e31 159 },
160 }
161 );
162 }
163}
164
165sub _datetime_parser {
166 my $self = shift;
167 if (my $parser = $self->__datetime_parser) {
168 return $parser;
169 }
170 my $parser = $self->result_source->storage->datetime_parser(@_);
171 return $self->__datetime_parser($parser);
172}
173
1741;
0b375b68 175__END__
176
45147005 177=head1 USAGE NOTES
178
179If you have a datetime column with the C<timezone> extra setting, and subsenquently
180create/update this column with a DateTime object in the L<DateTime::TimeZone::Floating>
181timezone, you will get a warning (as there is a very good chance this will not have the
182result you expect). For example:
183
184 __PACKAGE__->add_columns(
185 starts_when => { data_type => 'datetime', extra => { timezone => "America/Chicago" } }
186 );
187
188 my $event = $schema->resultset('EventTZ')->create({
189 starts_at => DateTime->new(year=>2007, month=>12, day=>31, ),
190 });
191
192The warning can be avoided in several ways:
193
194=over
195
196=item Fix your broken code
197
198When calling C<set_time_zone> on a Floating DateTime object, the timezone is simply
199set to the requested value, and B<no time conversion takes place>. It is always a good idea
200to be supply explicit times to the database:
201
202 my $event = $schema->resultset('EventTZ')->create({
203 starts_at => DateTime->new(year=>2007, month=>12, day=>31, time_zone => "America/Chicago" ),
204 });
205
206=item Suppress the check on per-column basis
207
208 __PACKAGE__->add_columns(
209 starts_when => { data_type => 'datetime', extra => { timezone => "America/Chicago", floating_tz_ok => 1 } }
210 );
211
212=item Suppress the check globally
213
214Set the environment variable DBIC_FLOATING_TZ_OK to some true value.
215
216=back
217
218
219
0b375b68 220=head1 SEE ALSO
221
222=over 4
223
224=item More information about the add_columns method, and column metadata,
225 can be found in the documentation for L<DBIx::Class::ResultSource>.
226
45147005 227=item Further discussion of problems inherent to the Floating timezone:
228 L<Floating DateTimes|DateTime/Floating_DateTimes>
229 and L<< $dt->set_time_zone|DateTime/"Set" Methods >>
230
0b375b68 231=back
232
233=head1 AUTHOR
234
235Matt S. Trout <mst@shadowcatsystems.co.uk>
236
237=head1 CONTRIBUTORS
238
239Aran Deltac <bluefeet@cpan.org>
240
241=head1 LICENSE
242
243You may distribute this code under the same terms as Perl itself.
244