[dbsrgits/DBIx-Class.git] / lib / DBIx / Class / InflateColumn / DateTime.pm

package DBIx::Class::InflateColumn::DateTime;

use strict;
use warnings;
use base qw/DBIx::Class/;
use Carp::Clan qw/^DBIx::Class/;
use Try::Tiny;

=head1 NAME

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, 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<DateTime> 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<InflateColumn::DateTime> to parse date strings for you.
The column is set directly for any non-references and C<InflateColumn::DateTime>
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<DateTime::Format::ISO8601> 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 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<date>, C<datetime> or C<timestamp> (or
a derivative of these datatypes, e.g. C<timestamp with timezone>), this
module will automatically call the appropriate parse/format method for
deflation/inflation as defined in the storage class. For instance, for
a C<datetime> field the methods C<parse_datetime> and C<format_datetime>
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<DateTime::Format> for more information on
date formatting.

For more help with using components, see L<DBIx::Class::Manual::Component/USING>.

=cut

__PACKAGE__->load_components(qw/InflateColumn/);

=head2 register_column

Chains with the L<DBIx::Class::Row/register_column> 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<DateTime> will throw an exception.  To
bypass these exceptions and just have the inflation return undef, use
the C<datetime_undef_if_invalid> 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;

  for (qw/date datetime timestamp/) {
    my $key = "inflate_${_}";

    next unless exists $info->{$key};
    return unless $info->{$key};

    $type = $_;
    last;
  }

  unless ($type) {
    $type = lc($info->{data_type});
    if ($type eq "timestamp with time zone" || $type eq "timestamptz") {
      $type = "timestamp";
      $info->{_ic_dt_method} ||= "timestamp_with_timezone";
    } elsif ($type eq "timestamp without time zone") {
      $type = "timestamp";
      $info->{_ic_dt_method} ||= "timestamp_without_timezone";
    } elsif ($type eq "smalldatetime") {
      $type = "datetime";
      $info->{_ic_dt_method} ||= "smalldatetime";
    }
  }

  if ( defined $info->{extra}{timezone} ) {
    carp "Putting timezone into extra => { timezone => '...' } has been deprecated, ".
         "please put it directly into the '$column' column definition.";
    $info->{timezone} = $info->{extra}{timezone} unless defined $info->{timezone};
  }

  if ( defined $info->{extra}{locale} ) {
    carp "Putting locale into extra => { locale => '...' } has been deprecated, ".
         "please put it directly into the '$column' column definition.";
    $info->{locale} = $info->{extra}{locale} unless defined $info->{locale};
  }

  my $undef_if_invalid = $info->{datetime_undef_if_invalid};

  if ($type eq 'datetime' || $type eq 'date' || $type eq 'timestamp') {
    # This shallow copy of %info avoids t/52_cycle.t treating
    # the resulting deflator as a circular reference.
    my %info = ( '_ic_dt_method' => $type , %{ $info } );

    if (defined $info->{extra}{floating_tz_ok}) {
      carp "Putting floating_tz_ok into extra => { floating_tz_ok => 1 } has been deprecated, ".
           "please put it directly into the '$column' column definition.";
      $info{floating_tz_ok} = $info->{extra}{floating_tz_ok};
    }

    $self->inflate_column(
      $column =>
        {
          inflate => sub {
            my ($value, $obj) = @_;

            my ($dt, $err);
            try { $dt = $obj->_inflate_to_datetime( $value, \%info ) }
            catch {
              $err = 1;
              if (! $undef_if_invalid) {
                $self->throw_exception ("Error while inflating ${value} for ${column} on ${self}: $_");
              }
            };
            return undef if $err;

            return $obj->_post_inflate_datetime( $dt, \%info );
          },
          deflate => sub {
            my ($value, $obj) = @_;

            $value = $obj->_pre_deflate_datetime( $value, \%info );
            $obj->_deflate_from_datetime( $value, \%info );
          },
        }
    );
  }
}

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 {
  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});
  }

  $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<timezone>, and subsequently
create/update this column with a DateTime object in the L<DateTime::TimeZone::Floating>
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<set_time_zone> on a Floating DateTime object, the timezone is simply
set to the requested value, and B<no time conversion takes place>. 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<DEPRECATED> because this gets you into trouble using L<DBIx::Class::Schema::Versioned>.
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, 
      can be found in the documentation for L<DBIx::Class::ResultSource>.

=item Further discussion of problems inherent to the Floating timezone:
      L<Floating DateTimes|DateTime/Floating_DateTimes> 
      and L<< $dt->set_time_zone|DateTime/"Set" Methods >>

=back

=head1 AUTHOR

Matt S. Trout <mst@shadowcatsystems.co.uk>

=head1 CONTRIBUTORS

Aran Deltac <bluefeet@cpan.org>

=head1 LICENSE

You may distribute this code under the same terms as Perl itself.
Commit	Line	Data
445e5e31	1	package DBIx::Class::InflateColumn::DateTime;
	2
	3	use strict;
	4	use warnings;
	5	use base qw/DBIx::Class/;
341d5ede	6	use Carp::Clan qw/^DBIx::Class/;
ed7ab0f4	7	use Try::Tiny;
445e5e31	8
0b375b68	9	=head1 NAME
0b375b68	10
5d0a2955	11	DBIx::Class::InflateColumn::DateTime - Auto-create DateTime objects from date and datetime columns.
0b375b68	12
	13	=head1 SYNOPSIS
	14
	15	Load this component and then declare one or more
679a304a	16	columns to be of the datetime, timestamp or date datatype.
0b375b68	17
0b375b68	18	package Event;
d88ecca6	19	use base 'DBIx::Class::Core';
	20
	21	__PACKAGE__->load_components(qw/InflateColumn::DateTime/);
0b375b68	22	__PACKAGE__->add_columns(
0b375b68	23	starts_when => { data_type => 'datetime' }
9c71b5e2	24	create_date => { data_type => 'date' }
0b375b68	25	);
	26
	27	Then you can treat the specified column as a L<DateTime> object.
	28
	29	print "This event starts the month of ".
	30	$event->starts_when->month_name();
	31
8d689133	32	If you want to set a specific timezone and locale for that field, use:
dda9af55	33
dda9af55	34	__PACKAGE__->add_columns(
92ed0695	35	starts_when => { data_type => 'datetime', timezone => "America/Chicago", locale => "de_DE" }
dda9af55	36	);
dda9af55	37
a97fe7e0	38	If you want to inflate no matter what data_type your column is,
	39	use inflate_datetime or inflate_date:
	40
	41	__PACKAGE__->add_columns(
	42	starts_when => { data_type => 'varchar', inflate_datetime => 1 }
	43	);
d4daee7b	44
a97fe7e0	45	__PACKAGE__->add_columns(
	46	starts_when => { data_type => 'varchar', inflate_date => 1 }
	47	);
	48
ff8a6e3b	49	It's also possible to explicitly skip inflation:
d4daee7b	50
ff8a6e3b	51	__PACKAGE__->add_columns(
	52	starts_when => { data_type => 'datetime', inflate_datetime => 0 }
	53	);
	54
8bf37b16	55	NOTE: Don't rely on C<InflateColumn::DateTime> to parse date strings for you.
	56	The column is set directly for any non-references and C<InflateColumn::DateTime>
	57	is completely bypassed. Instead, use an input parser to create a DateTime
	58	object. For instance, if your user input comes as a 'YYYY-MM-DD' string, you can
	59	use C<DateTime::Format::ISO8601> thusly:
d6aed638	60
	61	use DateTime::Format::ISO8601;
	62	my $dt = DateTime::Format::ISO8601->parse_datetime('YYYY-MM-DD');
	63
0b375b68	64	=head1 DESCRIPTION
	65
	66	This module figures out the type of DateTime::Format::* class to
	67	inflate/deflate with based on the type of DBIx::Class::Storage::DBI::*
	68	that you are using. If you switch from one database to a different
5d0a2955	69	one your code should continue to work without modification (though note
	70	that this feature is new as of 0.07, so it may not be perfect yet - bug
	71	reports to the list very much welcome).
0b375b68	72
9c71b5e2	73	If the data_type of a field is C<date>, C<datetime> or C<timestamp> (or
f59e543b	74	a derivative of these datatypes, e.g. C<timestamp with timezone>), this
9c71b5e2	75	module will automatically call the appropriate parse/format method for
	76	deflation/inflation as defined in the storage class. For instance, for
	77	a C<datetime> field the methods C<parse_datetime> and C<format_datetime>
	78	would be called on deflation/inflation. If the storage class does not
	79	provide a specialized inflator/deflator, C<[parse\|format]_datetime> will
	80	be used as a fallback. See L<DateTime::Format> for more information on
	81	date formatting.
	82
943f93f2	83	For more help with using components, see L<DBIx::Class::Manual::Component/USING>.
de78905b	84
0b375b68	85	=cut
0b375b68	86
445e5e31	87	__PACKAGE__->load_components(qw/InflateColumn/);
445e5e31	88
9b83fccd	89	=head2 register_column
	90
	91	Chains with the L<DBIx::Class::Row/register_column> method, and sets
	92	up datetime columns appropriately. This would not normally be
	93	directly called by end users.
	94
33a126ef	95	In the case of an invalid date, L<DateTime> will throw an exception. To
	96	bypass these exceptions and just have the inflation return undef, use
	97	the C<datetime_undef_if_invalid> option in the column info:
d4daee7b	98
33a126ef	99	"broken_date",
	100	{
	101	data_type => "datetime",
	102	default_value => '0000-00-00',
	103	is_nullable => 1,
	104	datetime_undef_if_invalid => 1
	105	}
	106
9b83fccd	107	=cut
9b83fccd	108
445e5e31	109	sub register_column {
	110	my ($self, $column, $info, @rest) = @_;
	111	$self->next::method($column, $info, @rest);
c209c4fd	112	return unless defined($info->{data_type});
bb90689c	113
	114	my $type;
	115
abc914bd	116	for (qw/date datetime timestamp/) {
bb90689c	117	my $key = "inflate_${_}";
	118
	119	next unless exists $info->{$key};
	120	return unless $info->{$key};
	121
	122	$type = $_;
	123	last;
	124	}
	125
	126	unless ($type) {
	127	$type = lc($info->{data_type});
6c99a3ee	128	if ($type eq "timestamp with time zone" \|\| $type eq "timestamptz") {
	129	$type = "timestamp";
	130	$info->{_ic_dt_method} \|\|= "timestamp_with_timezone";
65b386df	131	} elsif ($type eq "timestamp without time zone") {
	132	$type = "timestamp";
	133	$info->{_ic_dt_method} \|\|= "timestamp_without_timezone";
4a80eede	134	} elsif ($type eq "smalldatetime") {
4a80eede	135	$type = "datetime";
fb95dc4d	136	$info->{_ic_dt_method} \|\|= "smalldatetime";
6c99a3ee	137	}
bb90689c	138	}
bb90689c	139
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.";
c3ed0bde	143	$info->{timezone} = $info->{extra}{timezone} unless defined $info->{timezone};
dda9af55	144	}
dda9af55	145
8d689133	146	if ( defined $info->{extra}{locale} ) {
341d5ede	147	carp "Putting locale into extra => { locale => '...' } has been deprecated, ".
6c9d0c63	148	"please put it directly into the '$column' column definition.";
c3ed0bde	149	$info->{locale} = $info->{extra}{locale} unless defined $info->{locale};
8d689133	150	}
d4daee7b	151
dceeddc7	152	my $undef_if_invalid = $info->{datetime_undef_if_invalid};
dceeddc7	153
abc914bd	154	if ($type eq 'datetime' \|\| $type eq 'date' \|\| $type eq 'timestamp') {
ab969dd4	155	# This shallow copy of %info avoids t/52_cycle.t treating
	156	# the resulting deflator as a circular reference.
	157	my %info = ( '_ic_dt_method' => $type , %{ $info } );
	158
92ed0695	159	if (defined $info->{extra}{floating_tz_ok}) {
341d5ede	160	carp "Putting floating_tz_ok into extra => { floating_tz_ok => 1 } has been deprecated, ".
6c9d0c63	161	"please put it directly into the '$column' column definition.";
b1e4a1df	162	$info{floating_tz_ok} = $info->{extra}{floating_tz_ok};
92ed0695	163	}
45147005	164
445e5e31	165	$self->inflate_column(
	166	$column =>
	167	{
	168	inflate => sub {
	169	my ($value, $obj) = @_;
40f75181	170
ed7ab0f4	171	my ($dt, $err);
ed7ab0f4	172	try { $dt = $obj->_inflate_to_datetime( $value, \%info ) }
cf0d15ad	173	catch {
	174	$err = 1;
	175	if (! $undef_if_invalid) {
0bae8f79	176	$self->throw_exception ("Error while inflating ${value} for ${column} on ${self}: $_");
cf0d15ad	177	}
ed7ab0f4	178	};
cf0d15ad	179	return undef if $err;
40f75181	180
f856fe01	181	return $obj->_post_inflate_datetime( $dt, \%info );
445e5e31	182	},
	183	deflate => sub {
	184	my ($value, $obj) = @_;
f856fe01	185
f856fe01	186	$value = $obj->_pre_deflate_datetime( $value, \%info );
ab969dd4	187	$obj->_deflate_from_datetime( $value, \%info );
445e5e31	188	},
	189	}
	190	);
	191	}
	192	}
	193
ab969dd4	194	sub _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
	204	sub _inflate_to_datetime {
	205	my( $self, $value, $info ) = @_;
	206	return $self->_flate_or_fallback( $value, $info, 'parse_%s' );
	207	}
	208
	209	sub _deflate_from_datetime {
	210	my( $self, $value, $info ) = @_;
	211	return $self->_flate_or_fallback( $value, $info, 'format_%s' );
	212	}
abc914bd	213
445e5e31	214	sub _datetime_parser {
f568d83b	215	shift->result_source->storage->datetime_parser (@_);
445e5e31	216	}
445e5e31	217
f856fe01	218	sub _post_inflate_datetime {
	219	my( $self, $dt, $info ) = @_;
	220
c3ed0bde	221	$dt->set_time_zone($info->{timezone}) if defined $info->{timezone};
c3ed0bde	222	$dt->set_locale($info->{locale}) if defined $info->{locale};
f856fe01	223
	224	return $dt;
	225	}
	226
	227	sub _pre_deflate_datetime {
	228	my( $self, $dt, $info ) = @_;
	229
c3ed0bde	230	if (defined $info->{timezone}) {
f856fe01	231	carp "You're using a floating timezone, please see the documentation of"
	232	. " DBIx::Class::InflateColumn::DateTime for an explanation"
	233	if ref( $dt->time_zone ) eq 'DateTime::TimeZone::Floating'
	234	and not $info->{floating_tz_ok}
	235	and not $ENV{DBIC_FLOATING_TZ_OK};
	236
c3ed0bde	237	$dt->set_time_zone($info->{timezone});
f856fe01	238	}
f856fe01	239
c3ed0bde	240	$dt->set_locale($info->{locale}) if defined $info->{locale};
f856fe01	241
	242	return $dt;
	243	}
	244
445e5e31	245	1;
0b375b68	246	__END__
0b375b68	247
45147005	248	=head1 USAGE NOTES
45147005	249
97983826	250	If you have a datetime column with an associated C<timezone>, and subsequently
45147005	251	create/update this column with a DateTime object in the L<DateTime::TimeZone::Floating>
	252	timezone, you will get a warning (as there is a very good chance this will not have the
	253	result you expect). For example:
	254
	255	__PACKAGE__->add_columns(
92ed0695	256	starts_when => { data_type => 'datetime', timezone => "America/Chicago" }
45147005	257	);
	258
	259	my $event = $schema->resultset('EventTZ')->create({
	260	starts_at => DateTime->new(year=>2007, month=>12, day=>31, ),
	261	});
	262
	263	The warning can be avoided in several ways:
	264
	265	=over
	266
	267	=item Fix your broken code
	268
	269	When calling C<set_time_zone> on a Floating DateTime object, the timezone is simply
	270	set to the requested value, and B<no time conversion takes place>. It is always a good idea
	271	to be supply explicit times to the database:
	272
	273	my $event = $schema->resultset('EventTZ')->create({
	274	starts_at => DateTime->new(year=>2007, month=>12, day=>31, time_zone => "America/Chicago" ),
	275	});
	276
	277	=item Suppress the check on per-column basis
	278
	279	__PACKAGE__->add_columns(
92ed0695	280	starts_when => { data_type => 'datetime', timezone => "America/Chicago", floating_tz_ok => 1 }
45147005	281	);
	282
	283	=item Suppress the check globally
	284
	285	Set the environment variable DBIC_FLOATING_TZ_OK to some true value.
	286
	287	=back
	288
92ed0695	289	Putting extra attributes like timezone, locale or floating_tz_ok into extra => {} has been
	290	B<DEPRECATED> because this gets you into trouble using L<DBIx::Class::Schema::Versioned>.
	291	Instead put it directly into the columns definition like in the examples above. If you still
	292	use the old way you'll see a warning - please fix your code then!
45147005	293
0b375b68	294	=head1 SEE ALSO
	295
	296	=over 4
	297
	298	=item More information about the add_columns method, and column metadata,
	299	can be found in the documentation for L<DBIx::Class::ResultSource>.
	300
45147005	301	=item Further discussion of problems inherent to the Floating timezone:
	302	L<Floating DateTimes\|DateTime/Floating_DateTimes>
	303	and L<< $dt->set_time_zone\|DateTime/"Set" Methods >>
	304
0b375b68	305	=back
	306
	307	=head1 AUTHOR
	308
	309	Matt S. Trout <mst@shadowcatsystems.co.uk>
	310
	311	=head1 CONTRIBUTORS
	312
	313	Aran Deltac <bluefeet@cpan.org>
	314
	315	=head1 LICENSE
	316
	317	You may distribute this code under the same terms as Perl itself.
	318