date_timestamp_set()

La funzione PHP date_timestamp_set()

date_timestamp_set() imposta la data e l'ora di un object DateTime a partire da un timestamp Unix — il numero di secondi trascorsi dal 1° gennaio 1970, 00:00:00 UTC (l'"epoca Unix"). Sovrascrive qualsiasi data che l'object conteneva in precedenza, fissandola all'istante esatto rappresentato dal timestamp.

Questa pagina illustra la sintassi della funzione, un esempio funzionante, come interagisce con i fusi orari (la parte su cui molti sbagliano), l'equivalente orientato agli oggetti DateTime::setTimestamp(), i casi d'uso comuni e il suo rapporto con le altre funzioni di data di PHP.

Sintassi

date_timestamp_set(DateTime $object, int $timestamp): DateTime

• $object — un'istanza DateTime da modificare.
• $timestamp — un timestamp Unix (secondi dall'epoca). Passare un numero negativo per le date precedenti al 1970.
• Restituisce — lo stesso object DateTime (in modo da poter concatenare le chiamate), ora aggiornato.

Poiché muta e restituisce l'object passato, date_timestamp_set() è il corrispettivo procedurale del metodo DateTime::setTimestamp() — entrambi fanno la stessa cosa.

Un esempio di base

Questo imposta un object DateTime al 1° gennaio 2022, 00:00:00 UTC, il cui timestamp Unix è 1640995200:

Creiamo un object DateTime, lo passiamo a date_timestamp_set() insieme al timestamp, quindi formattiamo il risultato con format(). La data originale prodotta dal costruttore (il momento corrente) viene scartata.

Un timestamp Unix punta sempre a un momento in UTC — non ha un proprio fuso orario. Se hai bisogno del timestamp per una determinata data di calendario, usa mktime(), strtotime() o (new DateTime('2022-01-01'))->getTimestamp().

I timestamp sono assoluti — il fuso orario influisce solo sulla visualizzazione

Un malinteso comune è che date_timestamp_set() "converta" una data tra fusi orari. Non cambia quale istante punta l'object; si limita a impostare quell'istante. Ciò che cambia tra i fusi orari è il modo in cui format() visualizza quell'istante.

Lo stesso timestamp visualizzato in due fusi orari diversi:

<?php
$timestamp = 1640995200; // 2022-01-01 00:00:00 UTC

$nyc = new DateTime('now', new DateTimeZone('America/New_York'));
date_timestamp_set($nyc, $timestamp);

echo $nyc->format('Y-m-d H:i:s P'); // 2021-12-31 19:00:00 -05:00

L'istante è identico, ma New York è cinque ore indietro rispetto all'UTC a gennaio, quindi l'orario locale è la sera del 31 dicembre. Chiamando $nyc->getTimestamp() si ottiene ancora 1640995200. Per cambiare effettivamente il fuso orario visualizzato, impostarlo esplicitamente con date_timezone_set().

Equivalente orientato agli oggetti

Se si preferisce il concatenamento di metodi, DateTime::setTimestamp() è identico nell'effetto:

<?php
date_default_timezone_set('UTC');

$date = (new DateTime())->setTimestamp(1640995200);

echo $date->format('Y-m-d H:i:s'); // 2022-01-01 00:00:00

Entrambi gli stili mutano l'object sul posto e lo restituiscono, quindi è possibile scegliere quello che si legge meglio nel proprio codice.

Casi d'uso comuni

• Ripristinare un orario memorizzato. Database e API spesso memorizzano gli orari come timestamp Unix interi. date_timestamp_set() ricostruisce un DateTime da quell'intero in modo da poterlo formattare o elaborare aritmeticamente tramite date_add() e date_diff().
• Normalizzare l'input dell'utente. Convertire le date inserite dall'utente in un timestamp con strtotime(), quindi inizializzare un DateTime da quel singolo valore canonico.
• Reimpostare un object esistente. Quando si dispone già di un DateTime configurato (con un fuso orario scelto o un flusso di formattazione) e si vuole semplicemente puntarlo a un nuovo istante senza ricostruirlo.

Funzioni correlate

• date_timestamp_get() — l'inverso: legge il timestamp Unix di un DateTime.
• date_date_set() e date_time_set() — impostano la data o l'ora per componenti invece che tramite un timestamp.
• date_default_timezone_set() — controlla il fuso orario utilizzato quando non viene fornito alcun DateTimeZone.

Conclusione

date_timestamp_set() imposta un object DateTime all'istante esatto descritto da un timestamp Unix, sovrascrivendo il valore precedente e restituendo lo stesso object. Ricorda che il timestamp è sempre basato su UTC e che il fuso orario cambia solo il modo in cui il risultato viene visualizzato — non l'istante che rappresenta. Per l'operazione inversa, usa date_timestamp_get().

Esercizio