How To Use Dates in Joomla

Joomla has a helper class Date, which extends from PHP's DateTime class. It allows developers to handle date formatting more efficiently.

The Date is a class that stores a date and provides logic to manipulate and render that date in a variety of formats.

Create a Date Instance

All of the date helper methods require an instance of the Date class. To begin, you must create one. A Date object may be created in three ways:

use Joomla\CMS\Date\Date;
$date = new Date(); // Creates a new Date object equal to the current time.

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

use Joomla\CMS\Date\Date;
$date = Date::getInstance(); // Alias of new Date();

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

use Joomla\CMS\Factory;
$date = Factory::getDate();

Arguments

The Date constructor accepts two optional parameters:

  1. Date string to format
  2. Time zone

Not passing a date string will create a Date object with the current date and time, while not passing a time zone will allow the Date object to use the default time zone set.

The first argument, if used, should be a string that can be parsed using PHP's native DateTime constructor. For example,

use Joomla\CMS\Date\Date;

$currentTime = new Date('now'); // Current date and time
$tomorrowTime = new Date('now +1 day'); // Current date and time, + 1 day.
$plus1MonthTime = new Date('now +1 month'); // Current date and time, + 1 month.
$plus1YearTime = new Date('now +1 year'); // Current date and time, + 1 year.
$plus1YearAnd1MonthTime = new Date('now +1 year +1 month'); // Current date and time, + 1 year and 1 month.
$plusTimeToTime = new Date('now +1 hour +30 minutes +3 seconds'); // Current date and time, + 1 hour, 30 minutes and 3 seconds
$plusTimeToTime = new Date('now -1 hour +30 minutes +3 seconds'); // Current date and time, + 1 hour, 30 minutes and 3 seconds
$combinedTimeToTime = new Date('now -1 hour -30 minutes 23 seconds'); // Current date and time, - 1 hour, +30 minutes and +23 seconds

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

If a time zone has been specified as the second argument to the constructor, it will be converted to that time zone.

Joomla Date Formats

A number of date formats are predefined in Joomla. You can utilize these formatting strings when outputting dates, so that your dates will be automatically re-formatted according to a user's locale.

DATE_FORMAT_LC="l, d F Y"
DATE_FORMAT_LC1="l, d F Y"
DATE_FORMAT_LC2="l, d F Y H:i"
DATE_FORMAT_LC3="d F Y"
DATE_FORMAT_LC4="Y-m-d"
DATE_FORMAT_LC5="Y-m-d H:i"
DATE_FORMAT_LC6="Y-m-d H:i:s"
DATE_FORMAT_JS1="y-m-d"
DATE_FORMAT_CALENDAR_DATE="%Y-%m-%d"
DATE_FORMAT_CALENDAR_DATETIME="%Y-%m-%d %H:%M:%S"
DATE_FORMAT_FILTER_DATE="Y-m-d"
DATE_FORMAT_FILTER_DATETIME="Y-m-d H:i:s"

Displaying Dates

1. The HtmlHelper's date() method will take any date-time string that the Date constructor would accept, along with a formatting string, and output the date appropriately for the current user's timezone settings. This is the recommended method for outputting dates for the user.

use Joomla\CMS\HTML\HTMLHelper;
use Joomla\CMS\Language\Text;

$myDateString = '2021-12-1 15:20:00';
echo HtmlHelper::date($myDateString, Text::_('DATE_FORMAT_FILTER_DATETIME'));

2. Another option is to format the Date manually. If this method is used, you will have to also manually retrieve and set the user's time zone.

use Joomla\CMS\Language\Text;
use Joomla\CMS\Date\Date;
use Joomla\CMS\Factory;

$myDateString = '2021-12-1 15:20:00';
$timezone = Factory::getUser()->getTimezone();

$date = new Date($myDateString);
$date->setTimezone($timezone);
echo $date->format(Text::_('DATE_FORMAT_FILTER_DATETIME'));

Adding and Subtracting from Dates

Because the Joomla Date object extends the PHP DateTime object, it provides methods for adding and subtracting from dates. The easiest of these methods to use is the modify() method. It accepts any relative modification string that the PHP strtotime() method would accept. For example,

use Joomla\CMS\Date\Date;

$date = new Date('2021-12-1 15:20:00');
$date->modify('+1 year');
echo $date->toSQL(); // 2022-12-01 15:20:00

There are also separate add() and sub() methods, for adding or subtracting time from a date object respectively. These accept PHP-standard DateInterval objects:

use Joomla\CMS\Date\Date;

$interval = new \DateInterval('P1Y1D'); // Interval represents 1 year and 1 day
$date1 = new Date('2012-12-1 15:20:00');
$date1->add($interval);
echo $date1->toSQL(); // 2013-12-02 15:20:00

$date2 = new Date('2012-12-1 15:20:00');
$date2->sub($interval);
echo $date2->toSQL(); // 2011-11-30 15:20:00

Outputting Dates in Other Formats

ISO 8601 Format

$date = new Date('2012-12-1 15:20:00');
$date->toISO8601(); // 20121201T152000Z

RFC 822 Format

$date = new Date('2012-12-1 15:20:00');
$date->toRFC822(); // Sat, 01 Dec 2012 15:20:00 +0000

SQL Date-Time Format

$date = new Date('20121201T152000Z');
$date->toSql(); // 2012-12-01 15:20:00

Unix Timestamps

A Unix timestamp is expressed as the number of seconds that have passed since the Unix Epoch (the first second of Jan 1st 1970).

$date = new Date('20121201T152000Z');
$date->toUnix(); // 1354375200

Other Methods

1. dayToString($day, $abbr = false)

Translates day of week number to a string. For example, if $day is 3, the method will return WEDNESDAY.

2. monthToString($month, $abbr = false)

Translates month number to a string. For example, if $month is 6, the method will return JUNE.