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);