Date and time handling is an important function of the software, and the \IPS\DateTime class provides several utility methods to assist with handling dates and times reliably. It is important to note that the \IPS\DateTime class extends the core PHP DateTime class, so all of the general PHP methods for working with dates and times are immediately available through this interface as well.
Dates and times are represented in the database by unix timestamps. When displaying a date to a user, however, we need to convert the timestamp into a human-readable date and time, localized to the viewer's time zone. You can use the ts() static method for this purpose.
$time = \IPS\DateTime::ts( $timestamp );
You can also use the create() static method to create a new datetime instance (which will default to the current date/time).
$time = \IPS\DateTime::create();
The primary methods you will then use to display the date and/or time are as follows
/* Show the date and time in the user's timezone */
print (string) $time;
The magic __toString() method will automatically take care of time zone conversions and so on.
/* Output a <time> HTML tag with the relative time displayed */ print $time->html( TRUE, FALSE, NULL );
The first parameter determines whether the date/time should be capitalized or not (set this to FALSE if the time will be used in the middle of a sentence for instance), while the second parameter determines if the 'short' version of the date/time should be used even when not on mobile (e.g. 1d instead of 1day). The last parameter allows you to override the member or language to use to format the time.
/* Show just the date */
print $time->localeDate();
/* Show just the time - first parameter indicates whether or not to return seconds, while the second parameter indicates whether or not to return minutes */
print $time->localeTime( TRUE, TRUE );
/* Return just the month and day, without the year (or time)
print $time->dayAndMonth();
/* Return the date with the 4 digit year */
print $time->fullYearLocaleDate();
/* Format the relative date/time */
print $time->relative( \IPS\DateTime::RELATIVE_FORMAT_NORMAL );
For the relative() method, the following constants are recognized:
- RELATIVE_FORMAT_NORMAL: Yesterday at 2pm
- RELATIVE_FORMAT_LOWER: yesterday at 2pm (e.g. "Edited yesterday at 2pm")
- RELATIVE_FORMAT_SHORT: 1dy (for mobile view)
If you need to use a completely custom format, you can use the strFormat() method. While the DateTime class in PHP already has a built in format() method, it is not locale-aware and as such the strFormat() is used instead (which accepts any format accepted by strftime in PHP).
print $time->strFormat( '%B' );
Finally, there are some standardized formats supported out of the box as well, primarily useful when specifications require dates to be formatted in a certain way (e.g. RSS)
print $time->rfc3339(); // 2017-06-06T11:00:00Z
print $time->rfc1123(); // Tuesday, 6 June 2017 11:00:00 GMT
It is important to remember when caching data that dates and times should be localized based on the current viewing user's time zone (which is automatically detected). For this reason, you should not cache formatted dates or times, but rather format on display.
Finally, there is a "datetime" template plugin which can be used to format dates and times in templates automatically.
{datetime="$timestamp"}
This will output the localized date and time from the __toString() call. The extra attributes supported by this plugin are:
- dateonly: Only return the date
- norelative: Do not return a relative date
- lowercase: Return the date in lowercase
- short: Return the short form of the date
Report Document