Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
DBIx::Class::InflateCoUser:Contributed)DBIx::Class::InflateColumn::DateTime(3)

NAME
       DBIx::Class::InflateColumn::DateTime - Auto-create DateTime objects
       from date and datetime columns.

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 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 "InflateColumn::DateTime" to	parse date strings for
       you.  The column	is set directly	for any	non-references and
       "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
       "DateTime::Format::ISO8601" thusly:

	 use DateTime::Format::ISO8601;
	 my $dt	= DateTime::Format::ISO8601->parse_datetime('YYYY-MM-DD');

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 "date", "datetime" or "timestamp"	(or a
       derivative of these datatypes, e.g. "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 "datetime" field the methods "parse_datetime" and "format_datetime"
       would be	called on deflation/inflation. If the storage class does not
       provide a specialized inflator/deflator,	"[parse|format]_datetime" will
       be used as a fallback. See "Formatters And Stringification" in DateTime
       for more	information on date formatting.

       For more	help with using	components, see	"USING"	in
       DBIx::Class::Manual::Component.

   register_column
       Chains with the "register_column" in DBIx::Class::Row method, and sets
       up datetime columns appropriately.  This	would not normally be directly
       called by end users.

       In the case of an invalid date, DateTime	will throw an exception.  To
       bypass these exceptions and just	have the inflation return undef, use
       the "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
	   }

USAGE NOTES
       If you have a datetime column with an associated	"timezone", and
       subsequently create/update this column with a DateTime object in	the
       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:

       Fix your	broken code
	   When	calling	"set_time_zone"	on a Floating DateTime object, the
	   timezone is simply set to the requested value, and 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" ),
	     });

       Suppress	the check on per-column	basis
	     __PACKAGE__->add_columns(
	       starts_when => {	data_type => 'datetime', timezone => "America/Chicago",	floating_tz_ok => 1 }
	     );

       Suppress	the check globally
	   Set the environment variable	DBIC_FLOATING_TZ_OK to some true
	   value.

       Putting extra attributes	like timezone, locale or floating_tz_ok	into
       extra =>	{} has been DEPRECATED because this gets you into trouble
       using 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!

SEE ALSO
       More information	about the add_columns method, and column metadata, can
       be found	in the documentation for DBIx::Class::ResultSource.
       Further discussion of problems inherent to the Floating timezone:
       Floating	DateTimes and $dt->set_time_zone

FURTHER	QUESTIONS?
       Check the list of additional DBIC resources.

COPYRIGHT AND LICENSE
       This module is free software copyright by the DBIx::Class (DBIC)
       authors.	You can	redistribute it	and/or modify it under the same	terms
       as the DBIx::Class library.

perl v5.24.1			  2016-DBIx::Class::InflateColumn::DateTime(3)

NAME | SYNOPSIS | DESCRIPTION | USAGE NOTES | SEE ALSO | FURTHER QUESTIONS? | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=DBIx::Class::InflateColumn::DateTime&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help