Let the platform do the work

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 Get the current date/time as a SugarDateTime object 
fromUser Get SugarDateTime object from user's date/time string
asUser Format DateTime object as user's date/time string
fromDb Get SugarDateTime object from a DB date/time string
fromString Create a SugarDateTime object from a string
get_db_date_time_format Gets the current database date and time format
to_display_date_time Format a string as user's display date/time

getNow

returns SugarDateTime object

Parameters
Name Data Type Default Description
$userTz bool false Whether to use the user's timezone or not. False will use UTC

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
Name Data Type Default Description
$date string n/a Date/Time string to convert to an object
$user User null User to utilize formatting and timezone info from

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
Name Data Type Default Description
$date string n/a Date/Time string to convert to an object
$user User null User to utilize formatting and timezone info from

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
Name Data Type Default Description
$date string n/a Date/Time string in database format to convert to an object

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
Name Data Type Default Description
$date string n/a Date/Time string to convert to an object
$user User null User to utilize timezone info from

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
Name Data Type Default Description
$date string n/a Date/Time string in database format
$meridiem boolean true Deprecated -- Remains for backwards compatibility only
$convert_tz boolean true Convert to user's timezone
$user User null User to utilize formatting and timezone info from

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 Gets the start and end date/time from a range keyword 

parseDateRange

returns array

Parameters
Name Data Type Default Description
$range string n/a String from a predetermined list of available ranges
$user User null User to utilize formatting and timezone info from
$adjustForTimezone boolean true Convert to user's timezone

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 :

Range String Description
yesterday Yesterday's start and end date/time
today Today's start and end date/time
tomorrow Tomorrows's start and end date/time
last_7_days Start and end date/time of the last seven days
next_7_days Start and end date/time of the next seven days
last_30_days Start and end date/time of the last thirty days
next_30_days Start and end date/time of the next thirty days
next_month Start and end date/time of next month
last_month Start and end date/time of last month
this_month Start and end date/time of the current month
last_year Start and end date/time of last year
this_year Start and end date/time of the current year
next_year Start and end date/time of next year
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);