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

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

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