X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FDBIx%2FClass%2FInflateColumn%2FDateTime.pm;h=c35f151962d3464e461cfe786aa39c64d98cdd92;hb=49bceca3dbc42bc27720f777f336619bd2792943;hp=6ae4d4271d72394d07f0c19be34f90939d76f7d5;hpb=c209c4fd7348bf4e5d730d3e79f345d25628ae55;p=dbsrgits%2FDBIx-Class.git diff --git a/lib/DBIx/Class/InflateColumn/DateTime.pm b/lib/DBIx/Class/InflateColumn/DateTime.pm index 6ae4d42..c35f151 100644 --- a/lib/DBIx/Class/InflateColumn/DateTime.pm +++ b/lib/DBIx/Class/InflateColumn/DateTime.pm @@ -3,20 +3,26 @@ package DBIx::Class::InflateColumn::DateTime; use strict; use warnings; use base qw/DBIx::Class/; +use Carp::Clan qw/^DBIx::Class/; +use Try::Tiny; +use namespace::clean; =head1 NAME -DBIx::Class::InflateColumn::DateTime - Auto-create DateTime objects from datetime columns. +DBIx::Class::InflateColumn::DateTime - Auto-create DateTime objects from date and datetime columns. =head1 SYNOPSIS -Load this component and then declare one or more -columns to be of the datetime datatype. +Load this component and then declare one or more +columns to be of the datetime, timestamp or date datatype. package Event; + use base 'DBIx::Class::Core'; + __PACKAGE__->load_components(qw/InflateColumn::DateTime/); __PACKAGE__->add_columns( starts_when => { data_type => 'datetime' } + create_date => { data_type => 'date' } ); Then you can treat the specified column as a L object. @@ -24,69 +30,277 @@ Then you can treat the specified column as a L object. print "This event starts the month of ". $event->starts_when->month_name(); +If you want to set a specific timezone and locale for that field, use: + + __PACKAGE__->add_columns( + starts_when => { data_type => 'datetime', timezone => "America/Chicago", locale => "de_DE" } + ); + +If you want to inflate no matter what data_type your column is, +use inflate_datetime or inflate_date: + + __PACKAGE__->add_columns( + starts_when => { data_type => 'varchar', inflate_datetime => 1 } + ); + + __PACKAGE__->add_columns( + starts_when => { data_type => 'varchar', inflate_date => 1 } + ); + +It's also possible to explicitly skip inflation: + + __PACKAGE__->add_columns( + starts_when => { data_type => 'datetime', inflate_datetime => 0 } + ); + +NOTE: Don't rely on C to parse date strings for you. +The column is set directly for any non-references and C +is completely bypassed. Instead, use an input parser to create a DateTime +object. For instance, if your user input comes as a 'YYYY-MM-DD' string, you can +use C thusly: + + use DateTime::Format::ISO8601; + my $dt = DateTime::Format::ISO8601->parse_datetime('YYYY-MM-DD'); + =head1 DESCRIPTION -This module figures out the type of DateTime::Format::* class to -inflate/deflate with based on the type of DBIx::Class::Storage::DBI::* -that you are using. If you switch from one database to a different -one your code will continue to work without modification. +This module figures out the type of DateTime::Format::* class to +inflate/deflate with based on the type of DBIx::Class::Storage::DBI::* +that you are using. If you switch from one database to a different +one your code should continue to work without modification (though note +that this feature is new as of 0.07, so it may not be perfect yet - bug +reports to the list very much welcome). + +If the data_type of a field is C, C or C (or +a derivative of these datatypes, e.g. C), this +module will automatically call the appropriate parse/format method for +deflation/inflation as defined in the storage class. For instance, for +a C field the methods C and C +would be called on deflation/inflation. If the storage class does not +provide a specialized inflator/deflator, C<[parse|format]_datetime> will +be used as a fallback. See L for more information on +date formatting. + +For more help with using components, see L. =cut __PACKAGE__->load_components(qw/InflateColumn/); -__PACKAGE__->mk_group_accessors('simple' => '__datetime_parser'); - =head2 register_column Chains with the L method, and sets up datetime columns appropriately. This would not normally be directly called by end users. +In the case of an invalid date, L will throw an exception. To +bypass these exceptions and just have the inflation return undef, use +the C option in the column info: + + "broken_date", + { + data_type => "datetime", + default_value => '0000-00-00', + is_nullable => 1, + datetime_undef_if_invalid => 1 + } + =cut sub register_column { my ($self, $column, $info, @rest) = @_; + $self->next::method($column, $info, @rest); + return unless defined($info->{data_type}); - my $type = lc($info->{data_type}); - if ($type eq 'datetime' || $type eq 'date') { - my ($parse, $format) = ("parse_${type}", "format_${type}"); - $self->inflate_column( - $column => - { - inflate => sub { - my ($value, $obj) = @_; - $obj->_datetime_parser->$parse($value); - }, - deflate => sub { - my ($value, $obj) = @_; - $obj->_datetime_parser->$format($value); - }, - } - ); + + my $requested_type; + for (qw/date datetime timestamp/) { + my $key = "inflate_${_}"; + + next unless exists $info->{$key}; + + return if ! $info->{$key}; + + $requested_type = $_; + last; + } + + my $data_type = lc($info->{data_type} || ''); + + # _ic_dt_method will follow whatever the registration requests + # thus = instead of ||= + if ($data_type eq 'timestamp with time zone' || $data_type eq 'timestamptz') { + $info->{_ic_dt_method} = 'timestamp_with_timezone'; } + elsif ($data_type eq 'timestamp without time zone') { + $info->{_ic_dt_method} = 'timestamp_without_timezone'; + } + elsif ($data_type eq 'smalldatetime') { + $info->{_ic_dt_method} = 'smalldatetime'; + } + elsif ($data_type =~ /^ (?: date | datetime | timestamp ) $/x) { + $info->{_ic_dt_method} = $data_type; + } + else { + $info->{_ic_dt_method} = $requested_type; + } + + return unless $info->{_ic_dt_method}; + + if ($info->{extra}) { + for my $slot (qw/timezone locale floating_tz_ok/) { + if ( defined $info->{extra}{$slot} ) { + carp "Putting $slot into extra => { $slot => '...' } has been deprecated, ". + "please put it directly into the '$column' column definition."; + $info->{$slot} = $info->{extra}{$slot} unless defined $info->{$slot}; + } + } + } + + # shallow copy to avoid unfounded(?) Devel::Cycle complaints + my $infcopy = {%$info}; + + $self->inflate_column( + $column => + { + inflate => sub { + my ($value, $obj) = @_; + + my $dt = try + { $obj->_inflate_to_datetime( $value, $infcopy ) } + catch { + $self->throw_exception ("Error while inflating ${value} for ${column} on ${self}: $_") + unless $infcopy->{datetime_undef_if_invalid}; + undef; # rv + }; + + return (defined $dt) + ? $obj->_post_inflate_datetime( $dt, $infcopy ) + : undef + ; + }, + deflate => sub { + my ($value, $obj) = @_; + + $value = $obj->_pre_deflate_datetime( $value, $infcopy ); + $obj->_deflate_from_datetime( $value, $infcopy ); + }, + } + ); +} + +sub _flate_or_fallback +{ + my( $self, $value, $info, $method_fmt ) = @_; + + my $parser = $self->_datetime_parser; + my $preferred_method = sprintf($method_fmt, $info->{ _ic_dt_method }); + my $method = $parser->can($preferred_method) ? $preferred_method : sprintf($method_fmt, 'datetime'); + return $parser->$method($value); +} + +sub _inflate_to_datetime { + my( $self, $value, $info ) = @_; + return $self->_flate_or_fallback( $value, $info, 'parse_%s' ); +} + +sub _deflate_from_datetime { + my( $self, $value, $info ) = @_; + return $self->_flate_or_fallback( $value, $info, 'format_%s' ); } sub _datetime_parser { - my $self = shift; - if (my $parser = $self->__datetime_parser) { - return $parser; + shift->result_source->storage->datetime_parser (@_); +} + +sub _post_inflate_datetime { + my( $self, $dt, $info ) = @_; + + $dt->set_time_zone($info->{timezone}) if defined $info->{timezone}; + $dt->set_locale($info->{locale}) if defined $info->{locale}; + + return $dt; +} + +sub _pre_deflate_datetime { + my( $self, $dt, $info ) = @_; + + if (defined $info->{timezone}) { + carp "You're using a floating timezone, please see the documentation of" + . " DBIx::Class::InflateColumn::DateTime for an explanation" + if ref( $dt->time_zone ) eq 'DateTime::TimeZone::Floating' + and not $info->{floating_tz_ok} + and not $ENV{DBIC_FLOATING_TZ_OK}; + + $dt->set_time_zone($info->{timezone}); } - my $parser = $self->result_source->storage->datetime_parser(@_); - return $self->__datetime_parser($parser); + + $dt->set_locale($info->{locale}) if defined $info->{locale}; + + return $dt; } 1; __END__ +=head1 USAGE NOTES + +If you have a datetime column with an associated C, and subsequently +create/update this column with a DateTime object in the L +timezone, you will get a warning (as there is a very good chance this will not have the +result you expect). For example: + + __PACKAGE__->add_columns( + starts_when => { data_type => 'datetime', timezone => "America/Chicago" } + ); + + my $event = $schema->resultset('EventTZ')->create({ + starts_at => DateTime->new(year=>2007, month=>12, day=>31, ), + }); + +The warning can be avoided in several ways: + +=over + +=item Fix your broken code + +When calling C on a Floating DateTime object, the timezone is simply +set to the requested value, and B. It is always a good idea +to be supply explicit times to the database: + + my $event = $schema->resultset('EventTZ')->create({ + starts_at => DateTime->new(year=>2007, month=>12, day=>31, time_zone => "America/Chicago" ), + }); + +=item Suppress the check on per-column basis + + __PACKAGE__->add_columns( + starts_when => { data_type => 'datetime', timezone => "America/Chicago", floating_tz_ok => 1 } + ); + +=item Suppress the check globally + +Set the environment variable DBIC_FLOATING_TZ_OK to some true value. + +=back + +Putting extra attributes like timezone, locale or floating_tz_ok into extra => {} has been +B because this gets you into trouble using L. +Instead put it directly into the columns definition like in the examples above. If you still +use the old way you'll see a warning - please fix your code then! + =head1 SEE ALSO =over 4 -=item More information about the add_columns method, and column metadata, +=item More information about the add_columns method, and column metadata, can be found in the documentation for L. +=item Further discussion of problems inherent to the Floating timezone: + L + and L<< $dt->set_time_zone|DateTime/"Set" Methods >> + =back =head1 AUTHOR