From: Dagfinn Ilmari Mannsåker Date: Tue, 17 May 2016 15:33:27 +0000 (+0100) Subject: Harmonize time zone spelling in InflateColumn::DateTime X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=eef9b484;p=dbsrgits%2FDBIx-Class-Historic.git Harmonize time zone spelling in InflateColumn::DateTime The rest of the DateTime ecosystem consistently uses "time zone" and "time_zone", so use that in InflateColumn::DateTime too "timezone" is still accepted for backwards compatibility --- diff --git a/Changes b/Changes index b002e57..871b012 100644 --- a/Changes +++ b/Changes @@ -34,6 +34,8 @@ Revision history for DBIx::Class - When using non-scalars (e.g. arrays) as literal bind values it is no longer necessary to explicitly specify a bindtype (this turned out to be a mostly useless overprotection) + - InflateColumn::DateTime now accepts the ecosystem-standard option + 'time_zone', in addition to the DBIC-only 'timezone' (GH#28) - DBIx::Class::Optional::Dependencies now properly understands combinations of requirements and does the right thing with e.g. ->req_list_for([qw( rdbms_oracle ic_dt )]) bringing in the Oracle diff --git a/lib/DBIx/Class/InflateColumn/DateTime.pm b/lib/DBIx/Class/InflateColumn/DateTime.pm index bb6223d..4f08c1f 100644 --- a/lib/DBIx/Class/InflateColumn/DateTime.pm +++ b/lib/DBIx/Class/InflateColumn/DateTime.pm @@ -31,12 +31,16 @@ 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: +If you want to set a specific time zone and locale for that field, use: __PACKAGE__->add_columns( - starts_when => { data_type => 'datetime', timezone => "America/Chicago", locale => "de_DE" } + starts_when => { data_type => 'datetime', time_zone => "America/Chicago", locale => "de_DE" } ); +Note: DBIC before 0.082900 only accepted C, and silently discarded +any C arguments. For backwards compatibility, C will +continue being accepted as a synonym for C. + If you want to inflate no matter what data_type your column is, use inflate_datetime or inflate_date: @@ -73,7 +77,7 @@ 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 +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 @@ -152,7 +156,7 @@ sub register_column { } if ($info->{extra}) { - for my $slot (qw/timezone locale floating_tz_ok/) { + for my $slot (qw/time_zone 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."; @@ -161,6 +165,12 @@ sub register_column { } } + if ( defined $info->{timezone} ) { + $self->throw_exception("Cannot specify both 'timezone' and 'time_zone' in '$column' column defintion.") + if defined $info->{time_zone}; + $info->{time_zone} = delete $info->{timezone}; + } + # shallow copy to avoid unfounded(?) Devel::Cycle complaints my $infcopy = {%$info}; @@ -225,7 +235,7 @@ sub _datetime_parser { sub _post_inflate_datetime { my( $self, $dt, $info ) = @_; - $dt->set_time_zone($info->{timezone}) if defined $info->{timezone}; + $dt->set_time_zone($info->{time_zone}) if defined $info->{time_zone}; $dt->set_locale($info->{locale}) if defined $info->{locale}; return $dt; @@ -234,14 +244,14 @@ sub _post_inflate_datetime { sub _pre_deflate_datetime { my( $self, $dt, $info ) = @_; - if (defined $info->{timezone}) { - carp "You're using a floating timezone, please see the documentation of" + if (defined $info->{time_zone}) { + carp "You're using a floating time zone, 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}); + $dt->set_time_zone($info->{time_zone}); } $dt->set_locale($info->{locale}) if defined $info->{locale}; @@ -254,13 +264,13 @@ __END__ =head1 USAGE NOTES -If you have a datetime column with an associated C, and subsequently +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 +time zone, 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" } + starts_when => { data_type => 'datetime', time_zone => "America/Chicago" } ); my $event = $schema->resultset('EventTZ')->create({ @@ -273,7 +283,7 @@ The warning can be avoided in several ways: =item Fix your broken code -When calling C on a Floating DateTime object, the timezone is simply +When calling C on a Floating DateTime object, the time zone is simply set to the requested value, and B. It is always a good idea to be supply explicit times to the database: @@ -284,7 +294,7 @@ to be supply explicit times to the database: =item Suppress the check on per-column basis __PACKAGE__->add_columns( - starts_when => { data_type => 'datetime', timezone => "America/Chicago", floating_tz_ok => 1 } + starts_when => { data_type => 'datetime', time_zone => "America/Chicago", floating_tz_ok => 1 } ); =item Suppress the check globally @@ -293,7 +303,7 @@ 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 +Putting extra attributes like time_zone, 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! @@ -305,7 +315,7 @@ use the old way you'll see a warning - please fix your code then! =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: +=item Further discussion of problems inherent to the Floating time zone: L and L<< $dt->set_time_zone|DateTime/"Set" Methods >> diff --git a/t/icdt/offline_mysql.t b/t/icdt/offline_mysql.t index a865ef5..c9d5197 100644 --- a/t/icdt/offline_mysql.t +++ b/t/icdt/offline_mysql.t @@ -20,7 +20,7 @@ use DBIx::Class::_Util 'sigwarn_silencer'; my $schema = DBICTest->init_schema(); -# Test "timezone" parameter +# Test "time_zone" parameter foreach my $tbl (qw/EventTZ EventTZDeprecated/) { my $event_tz = $schema->resultset($tbl)->create({ starts_at => DateTime->new(year=>2007, month=>12, day=>31, time_zone => "America/Chicago" ), @@ -34,25 +34,25 @@ foreach my $tbl (qw/EventTZ EventTZDeprecated/) { is ($event_tz->created_on->month_name, "January", 'Default locale loaded: month_name'); my $starts_at = $event_tz->starts_at; - is("$starts_at", '2007-12-31T00:00:00', 'Correct date/time using timezone'); + is("$starts_at", '2007-12-31T00:00:00', 'Correct date/time using time zone'); my $created_on = $event_tz->created_on; - is("$created_on", '2006-01-31T12:34:56', 'Correct timestamp using timezone'); - is($event_tz->created_on->time_zone->name, "America/Chicago", "Correct timezone"); + is("$created_on", '2006-01-31T12:34:56', 'Correct timestamp using time zone'); + is($event_tz->created_on->time_zone->name, "America/Chicago", "Correct time zone"); my $loaded_event = $schema->resultset($tbl)->find( $event_tz->id ); isa_ok($loaded_event->starts_at, 'DateTime', 'DateTime returned'); $starts_at = $loaded_event->starts_at; - is("$starts_at", '2007-12-31T00:00:00', 'Loaded correct date/time using timezone'); - is($starts_at->time_zone->name, 'America/Chicago', 'Correct timezone'); + is("$starts_at", '2007-12-31T00:00:00', 'Loaded correct date/time using time zone'); + is($starts_at->time_zone->name, 'America/Chicago', 'Correct time zone'); isa_ok($loaded_event->created_on, 'DateTime', 'DateTime returned'); $created_on = $loaded_event->created_on; - is("$created_on", '2006-01-31T12:34:56', 'Loaded correct timestamp using timezone'); - is($created_on->time_zone->name, 'America/Chicago', 'Correct timezone'); + is("$created_on", '2006-01-31T12:34:56', 'Loaded correct timestamp using time zone'); + is($created_on->time_zone->name, 'America/Chicago', 'Correct time zone'); - # Test floating timezone warning + # Test floating time zone warning # We expect one warning SKIP: { skip "ENV{DBIC_FLOATING_TZ_OK} was set, skipping", 1 if $ENV{DBIC_FLOATING_TZ_OK}; @@ -63,8 +63,8 @@ foreach my $tbl (qw/EventTZ EventTZDeprecated/) { created_on => DateTime->new(year=>2006, month=>1, day=>31, hour => 13, minute => 34, second => 56 ), }); }, - qr/You're using a floating timezone, please see the documentation of DBIx::Class::InflateColumn::DateTime for an explanation/, - 'Floating timezone warning' + qr/You're using a floating time zone, please see the documentation of DBIx::Class::InflateColumn::DateTime for an explanation/, + 'Floating time zone warning' ); }; diff --git a/t/lib/DBICTest/Schema/EventTZ.pm b/t/lib/DBICTest/Schema/EventTZ.pm index 4c6c48a..d635868 100644 --- a/t/lib/DBICTest/Schema/EventTZ.pm +++ b/t/lib/DBICTest/Schema/EventTZ.pm @@ -11,7 +11,9 @@ __PACKAGE__->table('event'); __PACKAGE__->add_columns( id => { data_type => 'integer', is_auto_increment => 1 }, - starts_at => { data_type => 'datetime', timezone => "America/Chicago", locale => 'de_DE', datetime_undef_if_invalid => 1 }, + starts_at => { data_type => 'datetime', time_zone => "America/Chicago", locale => 'de_DE', datetime_undef_if_invalid => 1 }, + + # DO NOT change 'timezone' - there to test the legacy syntax created_on => { data_type => 'timestamp', timezone => "America/Chicago", floating_tz_ok => 1 }, ); diff --git a/t/lib/DBICTest/Schema/EventTZDeprecated.pm b/t/lib/DBICTest/Schema/EventTZDeprecated.pm index c66cd07..70ac7c7 100644 --- a/t/lib/DBICTest/Schema/EventTZDeprecated.pm +++ b/t/lib/DBICTest/Schema/EventTZDeprecated.pm @@ -11,7 +11,9 @@ __PACKAGE__->table('event'); __PACKAGE__->add_columns( id => { data_type => 'integer', is_auto_increment => 1 }, - starts_at => { data_type => 'datetime', extra => { timezone => "America/Chicago", locale => 'de_DE' } }, + starts_at => { data_type => 'datetime', extra => { time_zone => "America/Chicago", locale => 'de_DE' } }, + + # DO NOT change 'timezone' - there to test the legacy syntax created_on => { data_type => 'timestamp', extra => { timezone => "America/Chicago", floating_tz_ok => 1 } }, ); diff --git a/t/lib/DBICTest/Schema/EventTZPg.pm b/t/lib/DBICTest/Schema/EventTZPg.pm index 1f191af..07a2d1f 100644 --- a/t/lib/DBICTest/Schema/EventTZPg.pm +++ b/t/lib/DBICTest/Schema/EventTZPg.pm @@ -11,8 +11,8 @@ __PACKAGE__->table('event'); __PACKAGE__->add_columns( id => { data_type => 'integer', is_auto_increment => 1 }, - starts_at => { data_type => 'datetime', timezone => "America/Chicago", locale => 'de_DE' }, - created_on => { data_type => 'timestamp with time zone', timezone => "America/Chicago" }, + starts_at => { data_type => 'datetime', time_zone => "America/Chicago", locale => 'de_DE' }, + created_on => { data_type => 'timestamp with time zone', time_zone => "America/Chicago" }, ts_without_tz => { data_type => 'timestamp without time zone' }, );