####
Time
####


****
NAME
****


Kernel::System::Time - time functions. DEPRECATED, for new code use Kernel::System::DateTime instead.


***********
DESCRIPTION
***********


This module is managing time functions.


****************
PUBLIC INTERFACE
****************


new()
=====


create a time object. Do not use it directly, instead use:


.. code-block:: perl

     my $TimeObject = $Kernel::OM->Get('Kernel::System::DateTime');



SystemTime()
============


returns the number of non-leap seconds since what ever time the
system considers to be the epoch (that's 00:00:00, January 1, 1904
for Mac OS, and 00:00:00 UTC, January 1, 1970 for most other systems).


.. code-block:: perl

     my $SystemTime = $TimeObject->SystemTime();



SystemTime2TimeStamp()
======================


returns a time stamp for a given system time in \ ``yyyy-mm-dd 23:59:59``\  format.


.. code-block:: perl

     my $TimeStamp = $TimeObject->SystemTime2TimeStamp(
         SystemTime => $SystemTime,
     );


If you need the short format "23:59:59" for dates that are "today",
pass the Type parameter like this:


.. code-block:: perl

     my $TimeStamp = $TimeObject->SystemTime2TimeStamp(
         SystemTime => $SystemTime,
         Type       => 'Short',
     );



CurrentTimestamp()
==================


returns a time stamp of the local system time (see SystemTime())
in \ ``yyyy-mm-dd 23:59:59``\  format.


.. code-block:: perl

     my $TimeStamp = $TimeObject->CurrentTimestamp();



SystemTime2Date()
=================


converts a system time to a structured date array.


.. code-block:: perl

     my ($Sec, $Min, $Hour, $Day, $Month, $Year, $WeekDay) = $TimeObject->SystemTime2Date(
         SystemTime => $TimeObject->SystemTime(),
     );


$WeekDay is the day of the week, with 0 indicating Sunday and 3 indicating Wednesday.


TimeStamp2SystemTime()
======================


converts a given time stamp to local system time.


.. code-block:: perl

     my $SystemTime = $TimeObject->TimeStamp2SystemTime(
         String => '2004-08-14 22:45:00',
     );



Date2SystemTime()
=================


converts a structured date array to system time of OTRS.


.. code-block:: perl

     my $SystemTime = $TimeObject->Date2SystemTime(
         Year   => 2004,
         Month  => 8,
         Day    => 14,
         Hour   => 22,
         Minute => 45,
         Second => 0,
     );



ServerLocalTimeOffsetSeconds()
==============================


All framework code that calls this method only uses it to check if the server runs in UTC
and therefore user time zones are allowed. It's not needed any more in the future and is only
in here to don't break code that has not been ported yet. It returns 0 to tell its callers
that the server runs in UTC and so user time zones are allowed/active.

( originally returned the computed difference in seconds between UTC time and local time. )


.. code-block:: perl

     my $ServerLocalTimeOffsetSeconds = $TimeObject->ServerLocalTimeOffsetSeconds(
         SystemTime => $SystemTime,  # optional, otherwise call time()
     );



MailTimeStamp()
===============


returns the current time stamp in RFC 2822 format to be used in email headers:
"Wed, 22 Sep 2014 16:30:57 +0200".


.. code-block:: perl

     my $MailTimeStamp = $TimeObject->MailTimeStamp();



WorkingTime()
=============


get the working time in seconds between these local system times.


.. code-block:: perl

     my $WorkingTime = $TimeObject->WorkingTime(
         StartTime => $Created,
         StopTime  => $TimeObject->SystemTime(),
     );
 
     my $WorkingTime = $TimeObject->WorkingTime(
         StartTime => $Created,
         StopTime  => $TimeObject->SystemTime(),
         Calendar  => 3, # '' is default
     );



DestinationTime()
=================


get the destination time based on the current calendar working time (fallback: default
system working time) configuration.

Returns a system time (integer time stamp).

The algorithm roughly works as follows:
    - Check if the start time is actually in the configured working time.
        - If not, set it to the next working time second. Example: start time is
            on a weekend, start time would be set to 8:00 on the following Monday.
    - Then the diff time (in seconds) is added to the start time incrementally, only considering
        the configured working times. So adding 24 hours could actually span multiple days because
        they would be spread over the configured working hours. If we have 8-20, 24 hours would be
        spread over 2 days (13/11 hours).

NOTE: Currently, the implementation stops silently after 600 iterations, making it impossible to
    specify longer escalation times, for example.


.. code-block:: perl

     my $DestinationTime = $TimeObject->DestinationTime(
         StartTime => $Created,
         Time      => 60*60*24*2,
     );
 
     my $DestinationTime = $TimeObject->DestinationTime(
         StartTime => $Created,
         Time      => 60*60*24*2,
         Calendar  => 3, # '' is default
     );



VacationCheck()
===============


check if the selected day is a vacation (it does not matter if you
insert 01 or 1 for month or day in the function or in the SysConfig)

returns (true) vacation day if exists, returns false if date is no
vacation day


.. code-block:: perl

     $TimeObject->VacationCheck(
         Year     => 2005,
         Month    => 7 || '07',
         Day      => 13,
     );
 
     $TimeObject->VacationCheck(
         Year     => 2005,
         Month    => 7 || '07',
         Day      => 13,
         Calendar => 3, # '' is default; 0 is handled like ''
     );