1 package DBIx::Class::InflateColumn::DateTime;
5 use base qw/DBIx::Class/;
6 use Carp::Clan qw/^DBIx::Class/;
12 DBIx::Class::InflateColumn::DateTime - Auto-create DateTime objects from date and datetime columns.
16 Load this component and then declare one or more
17 columns to be of the datetime, timestamp or date datatype.
20 use base 'DBIx::Class::Core';
22 __PACKAGE__->load_components(qw/InflateColumn::DateTime/);
23 __PACKAGE__->add_columns(
24 starts_when => { data_type => 'datetime' }
25 create_date => { data_type => 'date' }
28 Then you can treat the specified column as a L<DateTime> object.
30 print "This event starts the month of ".
31 $event->starts_when->month_name();
33 If you want to set a specific timezone and locale for that field, use:
35 __PACKAGE__->add_columns(
36 starts_when => { data_type => 'datetime', timezone => "America/Chicago", locale => "de_DE" }
39 If you want to inflate no matter what data_type your column is,
40 use inflate_datetime or inflate_date:
42 __PACKAGE__->add_columns(
43 starts_when => { data_type => 'varchar', inflate_datetime => 1 }
46 __PACKAGE__->add_columns(
47 starts_when => { data_type => 'varchar', inflate_date => 1 }
50 It's also possible to explicitly skip inflation:
52 __PACKAGE__->add_columns(
53 starts_when => { data_type => 'datetime', inflate_datetime => 0 }
56 NOTE: Don't rely on C<InflateColumn::DateTime> to parse date strings for you.
57 The column is set directly for any non-references and C<InflateColumn::DateTime>
58 is completely bypassed. Instead, use an input parser to create a DateTime
59 object. For instance, if your user input comes as a 'YYYY-MM-DD' string, you can
60 use C<DateTime::Format::ISO8601> thusly:
62 use DateTime::Format::ISO8601;
63 my $dt = DateTime::Format::ISO8601->parse_datetime('YYYY-MM-DD');
67 This module figures out the type of DateTime::Format::* class to
68 inflate/deflate with based on the type of DBIx::Class::Storage::DBI::*
69 that you are using. If you switch from one database to a different
70 one your code should continue to work without modification (though note
71 that this feature is new as of 0.07, so it may not be perfect yet - bug
72 reports to the list very much welcome).
74 If the data_type of a field is C<date>, C<datetime> or C<timestamp> (or
75 a derivative of these datatypes, e.g. C<timestamp with timezone>), this
76 module will automatically call the appropriate parse/format method for
77 deflation/inflation as defined in the storage class. For instance, for
78 a C<datetime> field the methods C<parse_datetime> and C<format_datetime>
79 would be called on deflation/inflation. If the storage class does not
80 provide a specialized inflator/deflator, C<[parse|format]_datetime> will
81 be used as a fallback. See L<DateTime::Format> for more information on
84 For more help with using components, see L<DBIx::Class::Manual::Component/USING>.
88 __PACKAGE__->load_components(qw/InflateColumn/);
90 =head2 register_column
92 Chains with the L<DBIx::Class::Row/register_column> method, and sets
93 up datetime columns appropriately. This would not normally be
94 directly called by end users.
96 In the case of an invalid date, L<DateTime> will throw an exception. To
97 bypass these exceptions and just have the inflation return undef, use
98 the C<datetime_undef_if_invalid> option in the column info:
102 data_type => "datetime",
103 default_value => '0000-00-00',
105 datetime_undef_if_invalid => 1
110 sub register_column {
111 my ($self, $column, $info, @rest) = @_;
112 $self->next::method($column, $info, @rest);
113 return unless defined($info->{data_type});
117 for (qw/date datetime timestamp/) {
118 my $key = "inflate_${_}";
120 next unless exists $info->{$key};
121 return unless $info->{$key};
128 $type = lc($info->{data_type});
129 if ($type eq "timestamp with time zone" || $type eq "timestamptz") {
131 $info->{_ic_dt_method} ||= "timestamp_with_timezone";
132 } elsif ($type eq "timestamp without time zone") {
134 $info->{_ic_dt_method} ||= "timestamp_without_timezone";
135 } elsif ($type eq "smalldatetime") {
137 $info->{_ic_dt_method} ||= "smalldatetime";
141 if ($info->{extra}) {
142 if ( defined $info->{extra}{timezone} ) {
143 carp "Putting timezone into extra => { timezone => '...' } has been deprecated, ".
144 "please put it directly into the '$column' column definition.";
145 $info->{timezone} = $info->{extra}{timezone} unless defined $info->{timezone};
148 if ( defined $info->{extra}{locale} ) {
149 carp "Putting locale into extra => { locale => '...' } has been deprecated, ".
150 "please put it directly into the '$column' column definition.";
151 $info->{locale} = $info->{extra}{locale} unless defined $info->{locale};
155 my $undef_if_invalid = $info->{datetime_undef_if_invalid};
157 if ($type eq 'datetime' || $type eq 'date' || $type eq 'timestamp') {
158 # This shallow copy of %info avoids t/52_cycle.t treating
159 # the resulting deflator as a circular reference.
160 my %info = ( '_ic_dt_method' => $type , %{ $info } );
162 if (defined $info->{extra}{floating_tz_ok}) {
163 carp "Putting floating_tz_ok into extra => { floating_tz_ok => 1 } has been deprecated, ".
164 "please put it directly into the '$column' column definition.";
165 $info{floating_tz_ok} = $info->{extra}{floating_tz_ok};
168 $self->inflate_column(
172 my ($value, $obj) = @_;
175 { $obj->_inflate_to_datetime( $value, \%info ) }
177 $self->throw_exception ("Error while inflating ${value} for ${column} on ${self}: $_")
178 unless $undef_if_invalid;
183 ? $obj->_post_inflate_datetime( $dt, \%info )
188 my ($value, $obj) = @_;
190 $value = $obj->_pre_deflate_datetime( $value, \%info );
191 $obj->_deflate_from_datetime( $value, \%info );
198 sub _flate_or_fallback
200 my( $self, $value, $info, $method_fmt ) = @_;
202 my $parser = $self->_datetime_parser;
203 my $preferred_method = sprintf($method_fmt, $info->{ _ic_dt_method });
204 my $method = $parser->can($preferred_method) ? $preferred_method : sprintf($method_fmt, 'datetime');
205 return $parser->$method($value);
208 sub _inflate_to_datetime {
209 my( $self, $value, $info ) = @_;
210 return $self->_flate_or_fallback( $value, $info, 'parse_%s' );
213 sub _deflate_from_datetime {
214 my( $self, $value, $info ) = @_;
215 return $self->_flate_or_fallback( $value, $info, 'format_%s' );
218 sub _datetime_parser {
219 shift->result_source->storage->datetime_parser (@_);
222 sub _post_inflate_datetime {
223 my( $self, $dt, $info ) = @_;
225 $dt->set_time_zone($info->{timezone}) if defined $info->{timezone};
226 $dt->set_locale($info->{locale}) if defined $info->{locale};
231 sub _pre_deflate_datetime {
232 my( $self, $dt, $info ) = @_;
234 if (defined $info->{timezone}) {
235 carp "You're using a floating timezone, please see the documentation of"
236 . " DBIx::Class::InflateColumn::DateTime for an explanation"
237 if ref( $dt->time_zone ) eq 'DateTime::TimeZone::Floating'
238 and not $info->{floating_tz_ok}
239 and not $ENV{DBIC_FLOATING_TZ_OK};
241 $dt->set_time_zone($info->{timezone});
244 $dt->set_locale($info->{locale}) if defined $info->{locale};
254 If you have a datetime column with an associated C<timezone>, and subsequently
255 create/update this column with a DateTime object in the L<DateTime::TimeZone::Floating>
256 timezone, you will get a warning (as there is a very good chance this will not have the
257 result you expect). For example:
259 __PACKAGE__->add_columns(
260 starts_when => { data_type => 'datetime', timezone => "America/Chicago" }
263 my $event = $schema->resultset('EventTZ')->create({
264 starts_at => DateTime->new(year=>2007, month=>12, day=>31, ),
267 The warning can be avoided in several ways:
271 =item Fix your broken code
273 When calling C<set_time_zone> on a Floating DateTime object, the timezone is simply
274 set to the requested value, and B<no time conversion takes place>. It is always a good idea
275 to be supply explicit times to the database:
277 my $event = $schema->resultset('EventTZ')->create({
278 starts_at => DateTime->new(year=>2007, month=>12, day=>31, time_zone => "America/Chicago" ),
281 =item Suppress the check on per-column basis
283 __PACKAGE__->add_columns(
284 starts_when => { data_type => 'datetime', timezone => "America/Chicago", floating_tz_ok => 1 }
287 =item Suppress the check globally
289 Set the environment variable DBIC_FLOATING_TZ_OK to some true value.
293 Putting extra attributes like timezone, locale or floating_tz_ok into extra => {} has been
294 B<DEPRECATED> because this gets you into trouble using L<DBIx::Class::Schema::Versioned>.
295 Instead put it directly into the columns definition like in the examples above. If you still
296 use the old way you'll see a warning - please fix your code then!
302 =item More information about the add_columns method, and column metadata,
303 can be found in the documentation for L<DBIx::Class::ResultSource>.
305 =item Further discussion of problems inherent to the Floating timezone:
306 L<Floating DateTimes|DateTime/Floating_DateTimes>
307 and L<< $dt->set_time_zone|DateTime/"Set" Methods >>
313 Matt S. Trout <mst@shadowcatsystems.co.uk>
317 Aran Deltac <bluefeet@cpan.org>
321 You may distribute this code under the same terms as Perl itself.