DateTime

Overview

The SugarDateTime class, located in, ./include/SugarDateTime.php, extends PHP's built in DateTime class and can be used to perform common operations on date and time values. 

Setting

With existing SugarDateTime objects, it is recommended to clone the object before modifying or performing operations on it.

$new_datetime = clone $datetime;

Another option is to instantiate a new SugarDateTime object.

// defaults to now
$due_date_time = new SugarDateTime();

$due_date_time->setDate($dueYear, $dueMonth, $dueDay);
$due_date_time->setTime($dueHour, $dueMin);
$due_date_time->setTimezone($dueTZ);

Note : When creating a new SugarDateTime object, the date and time will default to the current date and time in the timezone configured in PHP.

SugarDateTime Objects can also be modified by passing in common English textual date/time strings to manipulate the value.

$due_date = clone $date;
$end_of_the_month->modify("last day of this month");
$end_of_next_month->modify("last day of next month");
$thirty_days_later->modify("+30 days");

Formatting

When formatting SugarDateTime objects into a string for display or logging purposes, there are a few options you can utilize through the formatDateTime() method.

Return the date/time formatted for the database:

$db_datetime_string = formatDateTime("datetime", "db");

Return the date/time formatted using a user's preference:

global $current_user;
$user_datetime_string = formatDateTime("datetime", "user", $current_user);

Return the date/time formatted following ISO-8601 standards:

$iso_datetime_string = formatDateTime("datetime", "iso");

There are times when it is needed to return only certain parts of a date or time. The format() method accepts a string parameter to define what parts or information about the date/time should be returned. 

// 28 Dec 2016
echo $due_date_time->format("j M Y");

// 2016-12-28 19:01:09
echo $due_date_time->asDb();

// The date/time 2016-12-28T11:01:09-08:00 is set in the timezone of America/Los_Angeles
echo "The date/time " . $due_date_time->format("c") . " is set in the timezone of " . $due_date_time->format("e");

// The time when this date/time object was created is 11:01:09 AM -0800
echo "The time when this date/time object was created is " . $due_date_time->format("H:i:s A O");

// There are 31 days in the month of December
echo "There are " . $due_date_time->format("t") . " days in the month of " . $due_date_time->format("F");

// There are 366 days in the year of 2016
echo "There are " . $due_date_time->__get("days_in_year") . " days in the year of " . $due_date_time->format("Y");

// Between Wed, 28 Dec 2016 11:01:09 -0800 and the end of the year, there are 4 days.
echo "Between " . $due_date_time . " and the end of the year, there are " . ($due_date_time->__get("days_in_year") - $due_date_time->format("z")) . " days.";

 For more information on the available options, please refer to http://php.net/manual/en/function.date.php 

TimeDate Class

The TimeDate class, located in ./include/TimeDate.php, utilizes the SugarDateTime class to provide an extended toolset of methods for date/time usage.

Setting

With existing TimeDate objects, it is recommended to clone the object before modifying or performing operations on it.

$new_timedate = clone $timedate;

Another option is to instantiate a new TimeDate object.

// current time in UTC
$timedate = new TimeDate();
$now_utcTZ = $timedate->getNow();

// current time in user's timezone
$timedate = new TimeDate($current_user);
$now_userTZ = $timedate->getNow(true);

Note : When creating a new TimeDate object, the date and time will default to the current date and time in the UTC timezone unless a user object is passed in. 

Formatting

TimeDate objects can return the Date/Time in either a string format or in a SugarDateTime object. The TimeDate object has many formatting options; some of the most common ones are :

getNow

returns SugarDateTime object

Parameters

Returns a SugarDateTime object set to the current date/time. If there is a user object associate to the TimeDate object, passing true to the $userTz parameter will return the object in user's timezone. If no user is associated or false is passed, the timezone returned will be in UTC.

Example

$timedate = new TimeDate($current_user);

// returns current date/time in UTC
$now_utcTZ = $timedate->getNow();

// returns current date/time in the user's timezone
$now_userTZ = $timedate->getNow(true);

fromUser

returns SugarDateTime object

Parameters

Returns a SugarDateTime object converted from the passed in string. If there is a user object passed in as a parameter will return the object in user's timezone. If no user is passed in, the timezone returned will be in UTC.

Example

$date = "2016-12-28 13:09";
$timedate = new TimeDate();
$datetime = $timedate->fromUser($date, $current_user);

asUser

returns string

Parameters

Returns a string of the date and time formatted based on the user's profile settings. If there is a user object passed in as a parameter it will return the object in user's timezone. If no user is passed in, the timezone returned will be in UTC.

Example

$datetime = new datetime("2016-12-28 13:09");
$timedate = new TimeDate();
$formattedDate = $timedate->asUser($datetime, $current_user);

fromDb

returns SugarDateTime

Parameters

Returns a SugarDateTime object converted from the passed in database formatted string.

Note : If the string does not match the database format exactly, this function will return boolean false.

Example

// Y-m-d H:i:s
$db_datetime = "2016-12-28 13:09:01";
$timedate = new TimeDate();
$datetime = $timedate->fromDb($db_datetime);

// returns bool(false)
$wrong_datetime = "2016-12-28 13:09";
$timedate = new TimeDate();
$datetime = $timedate->fromDb($timedate);

fromString

returns SugarDateTime

Parameters

Returns a SugarDateTime object converted from the passed in database formatted string. If there is a user object passed in as a parameter it will return the object in user's timezone. If no user is passed in, the timezone returned will be in UTC.

Example

$datetime_str = "December 28th 2016 13:09";
$timedate = new TimeDate();
$datetime = $timedate->fromString($datetime_str);

get_db_date_time_format

returns string

Parameters

N/a

Returns a string of the current database date and time format settings. 

Note : For just the date format use get_db_date_format() and for just the time format use get_db_time_format().

Example

$timedate = new TimeDate();

// Y-m-d H:i:s
$db_format = $timedate->get_db_date_time_format();

to_display_date_time

returns string

Parameters

Returns a string of the date and time formatted based on the user's profile settings. If no user is passed in, the current user's default will be used. If $convert_tz is true the string returned will be in the passed in user's timezone. If no user is passed in, the timezone returned will be in UTC.

Note : If the string does not match the database format exactly, this function will return boolean false.

Example

$datetime_str = "2016-12-28 13:09:01";

// 12-28-2016 07:09
$timedate = new TimeDate();
$datetime = $timedate->to_display_date_time($datetime_str);

// 2016-12-28 13:09
$timedate = new TimeDate();
$datetime = $timedate->to_display_date_time($datetime_str, true, false, $diff_user);

Parsing

In addition to formatting, TimeDate objects can also return Date/Time values based on special parameters. The TimeDate object has many date parsing options; some of the most common ones are :

parseDateRange

returns array

Parameters

Returns an array of SugarDateTime objects containing the start and Date/Time values calculated based on the entered parameter. If no user is passed in, the current user's default will be used. If $adjustForTimezone is true the string returned will be in the passed in user's timezone. If NULL is passed in as the user, the timezone returned will be in UTC. The available values for $range are :

Example

$timedate = new TimeDate($current_user);

// returns today's start and end date/time in UTC
$today_utcTZ = $timedate->parseDateRange("today", NULL, false);

// returns today's start and end date/time in the user's timezone
$today_userTZ = $timedate->parseDateRange("today", $current_user, true);