How to use JDate

Introduction

JDate is a helper class, extended from PHP's DateTime class, which allows developers to handle date formatting more efficiently. The class allows developers to format dates for readable strings, MySQL interaction, UNIX timestamp calculation, and also provides helper methods for working in different timezones.

Using JDate

Creating a JDate Instance

All of the date helper methods require an instance of the JDate class. To begin, you must create one. A JDate object may be created in two ways. One is the typical native method of simply creating a new instance:

$date = new JDate(); // Creates a new JDate object equal to the current time.

You may also create an instance using the static method defined in JDate:

$date = JDate::getInstance(); // Alias of 'new JDate();'

There is no difference between these methods, as JDate::getInstance simply creates a new instance of JDate exactly like the first method shown.

Alternatively, you may also retrieve the current date (as a JDate object) from JApplication, by using:

$date = JFactory::getDate();

Arguments

The JDate constructor (and getInstance static method) accepts two optional parameters: A date string to format, and a timezone. Not passing a date string will create a JDate object with the current date and time, while not passing a timezone will allow the JDate object to use the default timezone set.

The first argument, if used, must be a string that can be parsed using php's native DateTime constructor. E.g:

$currentTime = new JDate('now'); // Current date and time
$tomorrowTime = new JDate('now +1 day'); // Current date and time, + 1 day.
$Plus1MonthTime = new JDate('now +1 month'); // Current date and time, + 1 month.
$Plus1YearTime = new JDate('now +1 year'); // Current date and time, + 1 year.
$Plus1YearAnd1MonthTime = new JDate('now +1 year +1 month'); // Current date and time, + 1 year and 1 month.
$PlusTimeToTime = new JDate('now +1 hour +30 minutes +3 seconds'); // Current date and time, + 1 hour, 30 minutes and 3 seconds
$PlusTimeToTime = new JDate('now -1 hour +30 minutes +3 seconds'); // Current date and time, + 1 hour, 30 minutes and 3 seconds
$CombinedTimeToTime = new JDate('now -1 hour -30 minutes 23 seconds'); // Current date and time, - 1 hour, +30 minutes and +23 seconds

$date = new JDate('2012-12-1 15:20:00'); // 3:20 PM, December 1st, 2012

Temporary example of date formats

JFactory::getDate() gets a JDate object and we then do the JDate toFormat function

JFactory::getDate()->toFormat('%a %d %b %Y - %H:%M')

In Joomla! CMS 3.3 API the function "toFormat" was changed to "format", so the example above should be:

JFactory::getDate()->format('%a %d %b %Y - %H:%M')

Function: toISO8601(boolean $local = false) : string

$date = new JDate('2016-01-01 02:00:00'); // A.M. time, in GMT timezone

We set function param before to "false" and after to "true" (user timezone is set to "America/New_York"), we get:

$timezone = new DateTimeZone( JFactory::getUser()->getParam('timezone') );
$date->setTimezone($timezone);
echo $date->toISO8601(false); // 2016-01-01 T 02:00:00 +00:00
echo $date->toISO8601(true); // 2015-12-31 T 21:00:00-05:00 (local time in New York)