Joomla! Documentation™

Introduction

JDate est une classe d'assistance, étendue de la classe PHP DateTime, qui permet aux développeurs de gérer plus efficacement le format des dates. Cette classe permet aux développeurs de formater les dates pour les rendre lisibles dans les chaînes de caractères, des interactions MySQL, des calculs timestamp UNIX et fournit également des méthodes d'aide pour pouvoir travailler dans différents fuseaux horaires.

Regarding the "JDate" class name: This page has been updated to utilise namespaced class names. `JDate`, `JApplication` and other similarly named classes you will see throughout the Joomla documentation are actually class aliases, maintained for legacy reasons. It is recommended to use namespaced access to Joomla classes, which will improve your development experience by providing better code hints and checks in your editor, leading to fewer errors.

You can view the full list of aliased classes in this file inside the Joomla codebase.

Création d'une instance JDate

Toutes les méthodes d'aide pour les dates nécessitent une instance de la classe JDate. Pour commencer, vous devez en créer une. Un objet JDate peut être créé de deux façons. L'une est la méthode type native pour la simple création d'une nouvelle instance :

use Joomla\CMS\Date\Date;

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

Vous pouvez également créer une instance à l'aide de la méthode statique définie dans JDate :

use Joomla\CMS\Date\Date;

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

Il n'y a pas de différences entre ces deux méthodes puisque JDate::getInstance permet simplement de créer une nouvelle instance de JDate, exactement comme pour la première méthode indiquée.

De façon alternative, vous pouvez également récupérer la date courante (comme objet JDate) à partir de JApplication, en utilisant :

use Joomla\CMS\Factory;

$date = Factory::getDate();

Arguments

Le constructeur JDate (et la méthode statique getInstance) accepte deux paramètres en option : une chaîne de format de date, et un fuseau horaire. Ne pas préciser une chaîne de date aura pour conséquence la création d'un objet JDate avec la date et l'heure courantes. Ne pas préciser de fuseau horaire aura pour conséquence d'indiquer à l'objet JDate d'utiliser le réglage par défaut du fuseau horaire.

Le premier argument, s'il est utilisé, doit être une chaîne de caractères qui sera analysée par le constructeur natif PHP DateTime. Exemple :

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('2012-12-1 15:20:00'); // 3:20 PM, December 1st, 2012

A Unix timestamp (in seconds) can also be passed as the first argument, in which case it will be internally uplifted into a date. If a timezone has been specified as the second argument to the constructor, it will be converted to that timezone.

Exemples

One note of caution when outputting Date objects in a user context: do not simply print them to the screen. The Date object's toString() method simply calls its parent's format() method, without consideration for timezones or localized date formatting. This will not result in a good user experience, and will lead to inconsistencies between the formatting in your extension, and elsewhere in Joomla. Instead, you should always output Dates using the methods shown below.

Common Date Formats

A number of date formats are predefined in Joomla as part of the base language packs. This is beneficial because it means date formats can be easily internationalised. A sample of the available format strings is below, from the en-GB language pack. It is highly recommended to utilise these formatting strings when outputting dates, so that your dates will be automatically re-formatted according to a user's locale. They can be retrieved in the same way as any language string (see below for examples).

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"

The HtmlHelper Method (Recommended)

As with many common output items, the HtmlHelper class is here to...help! 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. As such, this is the recommended method for outputting dates for the user.

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

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

The Date Object's format() Method

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 timezone. This method is more useful for formatting dates outside of the user interface, such as in system logs or API calls.

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

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

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

Other Useful Code Examples

Quickly Outputting the Current Time

JFactory::getDate() récupère un objet JDate et nous créons donc la fonction JDate toFormat :

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

// These two are functionally equivalent
echo HtmlHelper::date('now', Text::_('DATE_FORMAT_FILTER_DATETIME'));

$timezone = Factory::getUser()->getTimezone();
echo Factory::getDate()->setTimezone($timezone)->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, which accepts any relative modification string that the PHP strtotime() method would accept. For example:

use Joomla\CMS\Date\Date;

$date = new Date('2012-12-1 15:20:00');
$date->modify('+1 year');
echo $date->toSQL(); // 2013-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 ISO 8601 Format

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

Outputting Dates in RFC 822 Format

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

Outputting Dates in SQL Date-Time Format

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

Outputting Dates as 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