.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "DBIx::Class::InflateColumn::DateTime 3pm"
.TH DBIx::Class::InflateColumn::DateTime 3pm "2022-05-21" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
DBIx::Class::InflateColumn::DateTime \- Auto\-create DateTime objects from date and datetime columns.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Load this component and then declare one or more
columns to be of the datetime, timestamp or date datatype.
.PP
.Vb 2
\&  package Event;
\&  use base \*(AqDBIx::Class::Core\*(Aq;
\&
\&  _\|_PACKAGE_\|_\->load_components(qw/InflateColumn::DateTime/);
\&  _\|_PACKAGE_\|_\->add_columns(
\&    starts_when => { data_type => \*(Aqdatetime\*(Aq }
\&    create_date => { data_type => \*(Aqdate\*(Aq }
\&  );
.Ve
.PP
Then you can treat the specified column as a DateTime object.
.PP
.Vb 2
\&  print "This event starts the month of ".
\&    $event\->starts_when\->month_name();
.Ve
.PP
If you want to set a specific timezone and locale for that field, use:
.PP
.Vb 3
\&  _\|_PACKAGE_\|_\->add_columns(
\&    starts_when => { data_type => \*(Aqdatetime\*(Aq, timezone => "America/Chicago", locale => "de_DE" }
\&  );
.Ve
.PP
If you want to inflate no matter what data_type your column is,
use inflate_datetime or inflate_date:
.PP
.Vb 3
\&  _\|_PACKAGE_\|_\->add_columns(
\&    starts_when => { data_type => \*(Aqvarchar\*(Aq, inflate_datetime => 1 }
\&  );
\&
\&  _\|_PACKAGE_\|_\->add_columns(
\&    starts_when => { data_type => \*(Aqvarchar\*(Aq, inflate_date => 1 }
\&  );
.Ve
.PP
It's also possible to explicitly skip inflation:
.PP
.Vb 3
\&  _\|_PACKAGE_\|_\->add_columns(
\&    starts_when => { data_type => \*(Aqdatetime\*(Aq, inflate_datetime => 0 }
\&  );
.Ve
.PP
\&\s-1NOTE:\s0 Don't rely on \f(CW\*(C`InflateColumn::DateTime\*(C'\fR to parse date strings for you.
The column is set directly for any non-references and \f(CW\*(C`InflateColumn::DateTime\*(C'\fR
is completely bypassed.  Instead, use an input parser to create a DateTime
object. For instance, if your user input comes as a '\s-1YYYY\-MM\-DD\s0' string, you can
use \f(CW\*(C`DateTime::Format::ISO8601\*(C'\fR thusly:
.PP
.Vb 2
\&  use DateTime::Format::ISO8601;
\&  my $dt = DateTime::Format::ISO8601\->parse_datetime(\*(AqYYYY\-MM\-DD\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "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).
.PP
If the data_type of a field is \f(CW\*(C`date\*(C'\fR, \f(CW\*(C`datetime\*(C'\fR or \f(CW\*(C`timestamp\*(C'\fR (or
a derivative of these datatypes, e.g. \f(CW\*(C`timestamp with timezone\*(C'\fR), this
module will automatically call the appropriate parse/format method for
deflation/inflation as defined in the storage class. For instance, for
a \f(CW\*(C`datetime\*(C'\fR field the methods \f(CW\*(C`parse_datetime\*(C'\fR and \f(CW\*(C`format_datetime\*(C'\fR
would be called on deflation/inflation. If the storage class does not
provide a specialized inflator/deflator, \f(CW\*(C`[parse|format]_datetime\*(C'\fR will
be used as a fallback. See \*(L"Formatters And Stringification\*(R" in DateTime
for more information on date formatting.
.PP
For more help with using components, see \*(L"\s-1USING\*(R"\s0 in DBIx::Class::Manual::Component.
.SS "register_column"
.IX Subsection "register_column"
Chains with the \*(L"register_column\*(R" in DBIx::Class::Row method, and sets
up datetime columns appropriately.  This would not normally be
directly called by end users.
.PP
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 \f(CW\*(C`datetime_undef_if_invalid\*(C'\fR option in the column info:
.PP
.Vb 7
\&    "broken_date",
\&    {
\&        data_type => "datetime",
\&        default_value => \*(Aq0000\-00\-00\*(Aq,
\&        is_nullable => 1,
\&        datetime_undef_if_invalid => 1
\&    }
.Ve
.SH "USAGE NOTES"
.IX Header "USAGE NOTES"
If you have a datetime column with an associated \f(CW\*(C`timezone\*(C'\fR, 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:
.PP
.Vb 3
\&  _\|_PACKAGE_\|_\->add_columns(
\&    starts_when => { data_type => \*(Aqdatetime\*(Aq, timezone => "America/Chicago" }
\&  );
\&
\&  my $event = $schema\->resultset(\*(AqEventTZ\*(Aq)\->create({
\&    starts_at => DateTime\->new(year=>2007, month=>12, day=>31, ),
\&  });
.Ve
.PP
The warning can be avoided in several ways:
.IP "Fix your broken code" 4
.IX Item "Fix your broken code"
When calling \f(CW\*(C`set_time_zone\*(C'\fR on a Floating DateTime object, the timezone is simply
set to the requested value, and \fBno time conversion takes place\fR. It is always a good idea
to be supply explicit times to the database:
.Sp
.Vb 3
\&  my $event = $schema\->resultset(\*(AqEventTZ\*(Aq)\->create({
\&    starts_at => DateTime\->new(year=>2007, month=>12, day=>31, time_zone => "America/Chicago" ),
\&  });
.Ve
.IP "Suppress the check on per-column basis" 4
.IX Item "Suppress the check on per-column basis"
.Vb 3
\&  _\|_PACKAGE_\|_\->add_columns(
\&    starts_when => { data_type => \*(Aqdatetime\*(Aq, timezone => "America/Chicago", floating_tz_ok => 1 }
\&  );
.Ve
.IP "Suppress the check globally" 4
.IX Item "Suppress the check globally"
Set the environment variable \s-1DBIC_FLOATING_TZ_OK\s0 to some true value.
.PP
Putting extra attributes like timezone, locale or floating_tz_ok into extra => {} has been
\&\fB\s-1DEPRECATED\s0\fR 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!
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "More information about the add_columns method, and column metadata, can be found in the documentation for DBIx::Class::ResultSource." 4
.IX Item "More information about the add_columns method, and column metadata, can be found in the documentation for DBIx::Class::ResultSource."
.PD 0
.ie n .IP "Further discussion of problems inherent to the Floating timezone: Floating DateTimes and $dt\->set_time_zone" 4
.el .IP "Further discussion of problems inherent to the Floating timezone: Floating DateTimes and \f(CW$dt\fR\->set_time_zone" 4
.IX Item "Further discussion of problems inherent to the Floating timezone: Floating DateTimes and $dt->set_time_zone"
.PD
.SH "FURTHER QUESTIONS?"
.IX Header "FURTHER QUESTIONS?"
Check the list of additional \s-1DBIC\s0 resources.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This module is free software copyright
by the DBIx::Class (\s-1DBIC\s0) authors. You can
redistribute it and/or modify it under the same terms as the
DBIx::Class library.