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 DateTime::Format 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
AUTHOR¶
Matt S. Trout <mst@shadowcatsystems.co.uk>
CONTRIBUTORS¶
Aran Deltac <bluefeet@cpan.org>
LICENSE¶
You may distribute this code under the same terms as Perl itself.