[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/;

=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;
  __PACKAGE__->load_components(qw/InflateColumn::DateTime Core/);
  __PACKAGE__->add_columns(
    starts_when => { data_type => 'datetime' }
    create_date => { data_type => 'date' }
  );

NOTE: You B<must> load C<InflateColumn::DateTime> B<before> C<Core>. See
L<DBIx::Class::Manual::Component> for details.

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/);

__PACKAGE__->mk_group_accessors('simple' => '__datetime_parser');

=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} ||= "datetime";
    }
  }

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

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

  $locale   = $info->{locale}   if defined $info->{locale};
  $timezone = $info->{timezone} if defined $info->{timezone};

  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 = eval { $obj->_inflate_to_datetime( $value, \%info ) };
            if (my $err = $@ ) {
              return undef if ($undef_if_invalid);
              $self->throw_exception ("Error while inflating ${value} for ${column} on ${self}: $err");
            }

            $dt->set_time_zone($timezone) if $timezone;
            $dt->set_locale($locale) if $locale;
            return $dt;
          },
          deflate => sub {
            my ($value, $obj) = @_;
            if ($timezone) {
                carp "You're using a floating timezone, please see the documentation of"
                  . " DBIx::Class::InflateColumn::DateTime for an explanation"
                  if ref( $value->time_zone ) eq 'DateTime::TimeZone::Floating'
                      and not $info{floating_tz_ok}
                      and not $ENV{DBIC_FLOATING_TZ_OK};
                $value->set_time_zone($timezone);
                $value->set_locale($locale) if $locale;
            }
            $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 {
  my $self = shift;
  if (my $parser = $self->__datetime_parser) {
    return $parser;
  }
  my $parser = $self->result_source->storage->datetime_parser(@_);
  return $self->__datetime_parser($parser);
}

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/;
445e5e31	7
0b375b68	8	=head1 NAME
0b375b68	9
5d0a2955	10	DBIx::Class::InflateColumn::DateTime - Auto-create DateTime objects from date and datetime columns.
0b375b68	11
	12	=head1 SYNOPSIS
	13
	14	Load this component and then declare one or more
679a304a	15	columns to be of the datetime, timestamp or date datatype.
0b375b68	16
0b375b68	17	package Event;
517d5d64	18	__PACKAGE__->load_components(qw/InflateColumn::DateTime Core/);
0b375b68	19	__PACKAGE__->add_columns(
0b375b68	20	starts_when => { data_type => 'datetime' }
9c71b5e2	21	create_date => { data_type => 'date' }
0b375b68	22	);
0b375b68	23
2c96eeed	24	NOTE: You B<must> load C<InflateColumn::DateTime> B<before> C<Core>. See
	25	L<DBIx::Class::Manual::Component> for details.
	26
0b375b68	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/);
	88
	89	__PACKAGE__->mk_group_accessors('simple' => '__datetime_parser');
	90
9b83fccd	91	=head2 register_column
	92
	93	Chains with the L<DBIx::Class::Row/register_column> method, and sets
	94	up datetime columns appropriately. This would not normally be
	95	directly called by end users.
	96
33a126ef	97	In the case of an invalid date, L<DateTime> will throw an exception. To
	98	bypass these exceptions and just have the inflation return undef, use
	99	the C<datetime_undef_if_invalid> option in the column info:
d4daee7b	100
33a126ef	101	"broken_date",
	102	{
	103	data_type => "datetime",
	104	default_value => '0000-00-00',
	105	is_nullable => 1,
	106	datetime_undef_if_invalid => 1
	107	}
	108
9b83fccd	109	=cut
9b83fccd	110
445e5e31	111	sub register_column {
	112	my ($self, $column, $info, @rest) = @_;
	113	$self->next::method($column, $info, @rest);
c209c4fd	114	return unless defined($info->{data_type});
bb90689c	115
	116	my $type;
	117
abc914bd	118	for (qw/date datetime timestamp/) {
bb90689c	119	my $key = "inflate_${_}";
	120
	121	next unless exists $info->{$key};
	122	return unless $info->{$key};
	123
	124	$type = $_;
	125	last;
	126	}
	127
	128	unless ($type) {
	129	$type = lc($info->{data_type});
6c99a3ee	130	if ($type eq "timestamp with time zone" \|\| $type eq "timestamptz") {
	131	$type = "timestamp";
	132	$info->{_ic_dt_method} \|\|= "timestamp_with_timezone";
65b386df	133	} elsif ($type eq "timestamp without time zone") {
	134	$type = "timestamp";
	135	$info->{_ic_dt_method} \|\|= "timestamp_without_timezone";
4a80eede	136	} elsif ($type eq "smalldatetime") {
	137	$type = "datetime";
	138	$info->{_ic_dt_method} \|\|= "datetime";
6c99a3ee	139	}
bb90689c	140	}
bb90689c	141
dda9af55	142	my $timezone;
8d689133	143	if ( defined $info->{extra}{timezone} ) {
341d5ede	144	carp "Putting timezone into extra => { timezone => '...' } has been deprecated, ".
6c9d0c63	145	"please put it directly into the '$column' column definition.";
dda9af55	146	$timezone = $info->{extra}{timezone};
	147	}
	148
8d689133	149	my $locale;
8d689133	150	if ( defined $info->{extra}{locale} ) {
341d5ede	151	carp "Putting locale into extra => { locale => '...' } has been deprecated, ".
6c9d0c63	152	"please put it directly into the '$column' column definition.";
8d689133	153	$locale = $info->{extra}{locale};
8d689133	154	}
d4daee7b	155
92ed0695	156	$locale = $info->{locale} if defined $info->{locale};
92ed0695	157	$timezone = $info->{timezone} if defined $info->{timezone};
8d689133	158
dceeddc7	159	my $undef_if_invalid = $info->{datetime_undef_if_invalid};
dceeddc7	160
abc914bd	161	if ($type eq 'datetime' \|\| $type eq 'date' \|\| $type eq 'timestamp') {
ab969dd4	162	# This shallow copy of %info avoids t/52_cycle.t treating
	163	# the resulting deflator as a circular reference.
	164	my %info = ( '_ic_dt_method' => $type , %{ $info } );
	165
92ed0695	166	if (defined $info->{extra}{floating_tz_ok}) {
341d5ede	167	carp "Putting floating_tz_ok into extra => { floating_tz_ok => 1 } has been deprecated, ".
6c9d0c63	168	"please put it directly into the '$column' column definition.";
b1e4a1df	169	$info{floating_tz_ok} = $info->{extra}{floating_tz_ok};
92ed0695	170	}
45147005	171
445e5e31	172	$self->inflate_column(
	173	$column =>
	174	{
	175	inflate => sub {
	176	my ($value, $obj) = @_;
40f75181	177
ab969dd4	178	my $dt = eval { $obj->_inflate_to_datetime( $value, \%info ) };
40f75181	179	if (my $err = $@ ) {
	180	return undef if ($undef_if_invalid);
	181	$self->throw_exception ("Error while inflating ${value} for ${column} on ${self}: $err");
	182	}
	183
dda9af55	184	$dt->set_time_zone($timezone) if $timezone;
8d689133	185	$dt->set_locale($locale) if $locale;
dda9af55	186	return $dt;
445e5e31	187	},
	188	deflate => sub {
	189	my ($value, $obj) = @_;
47cd9169	190	if ($timezone) {
341d5ede	191	carp "You're using a floating timezone, please see the documentation of"
47cd9169	192	. " DBIx::Class::InflateColumn::DateTime for an explanation"
47cd9169	193	if ref( $value->time_zone ) eq 'DateTime::TimeZone::Floating'
ab969dd4	194	and not $info{floating_tz_ok}
47cd9169	195	and not $ENV{DBIC_FLOATING_TZ_OK};
47cd9169	196	$value->set_time_zone($timezone);
8d689133	197	$value->set_locale($locale) if $locale;
47cd9169	198	}
ab969dd4	199	$obj->_deflate_from_datetime( $value, \%info );
445e5e31	200	},
	201	}
	202	);
	203	}
	204	}
	205
ab969dd4	206	sub _flate_or_fallback
	207	{
	208	my( $self, $value, $info, $method_fmt ) = @_;
	209
	210	my $parser = $self->_datetime_parser;
	211	my $preferred_method = sprintf($method_fmt, $info->{ _ic_dt_method });
	212	my $method = $parser->can($preferred_method) ? $preferred_method : sprintf($method_fmt, 'datetime');
	213	return $parser->$method($value);
	214	}
	215
	216	sub _inflate_to_datetime {
	217	my( $self, $value, $info ) = @_;
	218	return $self->_flate_or_fallback( $value, $info, 'parse_%s' );
	219	}
	220
	221	sub _deflate_from_datetime {
	222	my( $self, $value, $info ) = @_;
	223	return $self->_flate_or_fallback( $value, $info, 'format_%s' );
	224	}
abc914bd	225
445e5e31	226	sub _datetime_parser {
	227	my $self = shift;
	228	if (my $parser = $self->__datetime_parser) {
	229	return $parser;
	230	}
	231	my $parser = $self->result_source->storage->datetime_parser(@_);
	232	return $self->__datetime_parser($parser);
	233	}
	234
	235	1;
0b375b68	236	__END__
0b375b68	237
45147005	238	=head1 USAGE NOTES
45147005	239
97983826	240	If you have a datetime column with an associated C<timezone>, and subsequently
45147005	241	create/update this column with a DateTime object in the L<DateTime::TimeZone::Floating>
	242	timezone, you will get a warning (as there is a very good chance this will not have the
	243	result you expect). For example:
	244
	245	__PACKAGE__->add_columns(
92ed0695	246	starts_when => { data_type => 'datetime', timezone => "America/Chicago" }
45147005	247	);
	248
	249	my $event = $schema->resultset('EventTZ')->create({
	250	starts_at => DateTime->new(year=>2007, month=>12, day=>31, ),
	251	});
	252
	253	The warning can be avoided in several ways:
	254
	255	=over
	256
	257	=item Fix your broken code
	258
	259	When calling C<set_time_zone> on a Floating DateTime object, the timezone is simply
	260	set to the requested value, and B<no time conversion takes place>. It is always a good idea
	261	to be supply explicit times to the database:
	262
	263	my $event = $schema->resultset('EventTZ')->create({
	264	starts_at => DateTime->new(year=>2007, month=>12, day=>31, time_zone => "America/Chicago" ),
	265	});
	266
	267	=item Suppress the check on per-column basis
	268
	269	__PACKAGE__->add_columns(
92ed0695	270	starts_when => { data_type => 'datetime', timezone => "America/Chicago", floating_tz_ok => 1 }
45147005	271	);
	272
	273	=item Suppress the check globally
	274
	275	Set the environment variable DBIC_FLOATING_TZ_OK to some true value.
	276
	277	=back
	278
92ed0695	279	Putting extra attributes like timezone, locale or floating_tz_ok into extra => {} has been
	280	B<DEPRECATED> because this gets you into trouble using L<DBIx::Class::Schema::Versioned>.
	281	Instead put it directly into the columns definition like in the examples above. If you still
	282	use the old way you'll see a warning - please fix your code then!
45147005	283
0b375b68	284	=head1 SEE ALSO
	285
	286	=over 4
	287
	288	=item More information about the add_columns method, and column metadata,
	289	can be found in the documentation for L<DBIx::Class::ResultSource>.
	290
45147005	291	=item Further discussion of problems inherent to the Floating timezone:
	292	L<Floating DateTimes\|DateTime/Floating_DateTimes>
	293	and L<< $dt->set_time_zone\|DateTime/"Set" Methods >>
	294
0b375b68	295	=back
	296
	297	=head1 AUTHOR
	298
	299	Matt S. Trout <mst@shadowcatsystems.co.uk>
	300
	301	=head1 CONTRIBUTORS
	302
	303	Aran Deltac <bluefeet@cpan.org>
	304
	305	=head1 LICENSE
	306
	307	You may distribute this code under the same terms as Perl itself.
	308