date_timestamp_get()

Introduction

Les fonctions de date et d'heure constituent une partie essentielle des langages de programmation. En PHP, les développeurs ont souvent besoin de récupérer la date et l'heure actuelles ou d'effectuer des opérations sur des dates et des heures. La fonction date_timestamp_get() est l'une de ces fonctions, utilisée pour extraire le timestamp Unix d'un objet DateTime. Dans cet article, nous allons explorer la fonction date_timestamp_get() en détail et comprendre son fonctionnement.

Comprendre date_timestamp_get()

La fonction date_timestamp_get() est une fonction PHP intégrée qui extrait le timestamp Unix d'un objet DateTime. Un timestamp Unix est un nombre unique représentant un instant dans le temps : le nombre de secondes écoulées depuis le 1er janvier 1970, 00:00:00 UTC (l'"époque Unix").

Un timestamp est toujours un nombre basé sur UTC. Le fuseau horaire de l'objet DateTime en entrée est utilisé pour calculer la valeur, mais le timestamp lui-même ne stocke aucun fuseau horaire — deux objets DateTime décrivant le même instant dans des fuseaux horaires différents retournent le même timestamp.

Syntaxe

date_timestamp_get(DateTimeInterface $object): int

• $object — une instance de DateTime ou DateTimeImmutable (tout ce qui implémente DateTimeInterface). Passer null ou un non-objet déclenche une TypeError en PHP 8+.
• Valeur de retour — un int, le timestamp Unix en secondes. (Les microsecondes inférieures à la seconde sont ignorées ; utilisez $date->format('U.u') si vous en avez besoin.)

L'objet DateTime peut être créé avec la fonction date_create() ou le constructeur de la classe DateTime. date_timestamp_get($date) est l'alias procédural de l'appel de méthode $date->getTimestamp().

Exemple de base

Nous créons un objet DateTime à partir d'une chaîne de date, le passons à date_timestamp_get(), et affichons le timestamp Unix retourné. Pour du code orienté objet moderne, la forme équivalente (et généralement préférée) est $date->getTimestamp().

Le fuseau horaire affecte le résultat

Comme un timestamp est un instant absolu en UTC, la même chaîne d'horloge murale produit un timestamp différent selon le fuseau horaire de l'objet :

<?php
$utc = new DateTime('2023-03-03 10:30:00', new DateTimeZone('UTC'));
$tokyo = new DateTime('2023-03-03 10:30:00', new DateTimeZone('Asia/Tokyo'));

echo date_timestamp_get($utc);   // 1677839400
echo "\n";
echo date_timestamp_get($tokyo); // 1677807000 (32400s = 9h earlier in UTC)

10:30 à Tokyo se produit 9 heures avant 10:30 en UTC, donc son timestamp est inférieur de 32400 secondes. Consultez date_default_timezone_set() pour contrôler le fuseau horaire par défaut.

Utilisation du timestamp dans les calculs

La véritable valeur d'un timestamp réside dans l'arithmétique — une fois qu'une date est un simple entier, vous pouvez le soustraire, le comparer et le convertir librement :

<?php
$start = date_timestamp_get(date_create('2023-03-03 10:30:00'));
$end   = date_timestamp_get(date_create('2023-03-03 12:00:00'));

$diffSeconds = $end - $start;
echo $diffSeconds / 60 . " minutes elapsed"; // 90 minutes elapsed

Pour convertir un timestamp en chaîne formatée, passez-le à date(), ou construisez un nouvel objet avec setTimestamp(). Pour des différences de dates plus riches (années, mois, jours), préférez date_diff().

Cas d'usage courants et pièges

• Stocker des dates dans une base de données sous forme d'entier maintient le tri et les requêtes de plage rapides et sans dépendance au fuseau horaire.
• Comparer deux instants est une simple comparaison d'entiers une fois que les deux sont des timestamps.
• Piège — float vs int : le type de retour est int. Si vous avez besoin d'une précision en microsecondes (définie via le constructeur ou date_create() avec une seconde fractionnaire), getTimestamp() la tronque ; utilisez format('U.u') à la place.
• Piège — dates antérieures à 1970 produisent des timestamps négatifs, ce qui est valide mais surprend le code qui suppose un nombre positif.
• Opération inverse : pour définir l'heure d'un objet à partir d'un timestamp, utilisez date_timestamp_set().

Conclusion

date_timestamp_get() offre aux développeurs PHP un moyen simple et précis de réduire un objet DateTime à un unique timestamp Unix UTC — idéal pour le stockage, la comparaison et l'arithmétique. Pour le code orienté objet courant, utilisez $date->getTimestamp() ; les deux sont interchangeables.

Pratique