Funzione PHP date_timezone_get()

La funzione date_timezone_get() restituisce il fuso orario associato a un oggetto DateTime come oggetto DateTimeZone. Sapere quale fuso orario porta una data fa la differenza tra un timestamp che significa "le 15:00 a New York" e uno che significa "le 15:00 in un posto indefinito" — sbagliarlo è una delle cause più comuni di bug di disallineamento orario nelle applicazioni PHP.

Questa pagina tratta la firma della funzione, cosa restituisce (anche in caso di errore), l'equivalente orientato agli oggetti che si vede più spesso nel codice reale, e esempi pratici come la lettura e la conversione di un fuso orario.

Comprendere i fusi orari in PHP

Un fuso orario è una regione geografica che condivide lo stesso orario standard. Ciascuno è identificato da un nome IANA univoco come America/New_York o Europe/London. PHP include il database IANA completo; puoi elencare tutti i nomi supportati con timezone_identifiers_list().

Ogni oggetto DateTime porta internamente un fuso orario. Se non ne viene specificato uno, si utilizza il fuso orario predefinito dello script — il valore impostato da date_default_timezone_set() (o, in mancanza di questo, la direttiva date.timezone in php.ini). Per modificare il fuso orario di un oggetto esistente invece di leggerlo, usa date_timezone_set().

Un punto chiave: date_timezone_get() non converte l'orario. Riporta soltanto l'etichetta del fuso orario attualmente associata all'oggetto. Per spostare effettivamente il valore dell'orologio in un altro fuso, è necessario cambiare il fuso orario con setTimezone() / date_timezone_set().

La funzione date_timezone_get()

date_timezone_get() è l'alias procedurale del metodo DateTime::getTimezone(). Entrambi fanno la stessa cosa — restituiscono l'istanza DateTimeZone contenuta in un oggetto DateTime (o DateTimeImmutable).

Sintassi

date_timezone_get(DateTimeInterface $object): DateTimeZone|false

L'equivalente orientato agli oggetti:

$object->getTimezone();

Parametri

• $object: Un oggetto DateTime o DateTimeImmutable da cui leggere il fuso orario.

Valore restituito

In caso di successo restituisce un oggetto DateTimeZone. Restituisce false in caso di errore (ad esempio, se l'oggetto non ha informazioni sul fuso orario associate). Chiama getName() sul risultato per ottenere la stringa IANA come "Europe/London".

Esempi

Ecco alcuni esempi di come si può utilizzare la funzione date_timezone_get():

Esempio 1: Recuperare il fuso orario della data e ora correnti

Un oggetto DateTime creato senza un fuso orario esplicito eredita quello predefinito dello script, quindi l'output qui è ciò che è stato passato a date_default_timezone_set() — UTC in questo esempio.

Esempio 2: Recuperare il fuso orario dopo averlo modificato

Dopo che setTimezone() riassegna il fuso, date_timezone_get() riporta il nuovo valore, America/New_York.

Esempio 3: Leggere l'offset e convertire tra fusi orari

Poiché date_timezone_get() restituisce un oggetto DateTimeZone completo, puoi passarlo ad altre chiamate che gestiscono i fusi orari — ad esempio, per leggere l'offset UTC o per convertire un momento da un fuso all'altro:

<?php
// 9:00 AM in London on a summer date (BST, UTC+1)
$london = new DateTime('2023-07-01 09:00:00', new DateTimeZone('Europe/London'));

$tz = date_timezone_get($london);
echo $tz->getName(), "\n";                  // Europe/London
echo $tz->getOffset($london) / 3600, "\n";  // 1  (hours east of UTC)

// Convert the same instant to Tokyo time
$london->setTimezone(new DateTimeZone('Asia/Tokyo'));
echo $london->format('Y-m-d H:i'), "\n";    // 2023-07-01 17:00

L'istante è identico; cambia solo la rappresentazione dell'orologio — le 09:00 BST di Londra corrispondono alle 17:00 JST di Tokyo. Vedi date_format() per i caratteri di formattazione usati sopra.

Errori comuni

• Legge, non converte. date_timezone_get() restituisce solo il fuso associato. Riassegnare il risultato a un'altra variabile non cambia la data — usa setTimezone() per questo.
• Fuso predefinito vs. esplicito. Un oggetto creato senza un fuso orario eredita quello predefinito dello script. Se quel valore predefinito è errato, ogni lettura sembra corretta ma l'orario sottostante è sbagliato. Impostalo una volta con date_default_timezone_set().
• Preferisci la forma OOP nel codice moderno. $object->getTimezone() esegue la stessa chiamata e si legge più naturalmente all'interno di catene di metodi.

Conclusione

date_timezone_get() restituisce il DateTimeZone associato a un oggetto DateTime, fornendo il nome IANA e gli strumenti per leggere gli offset o convertire tra fusi orari. Combinata con date_default_timezone_set() e date_timezone_set(), ti permette di mantenere i timestamp non ambigui tra utenti e server in diverse parti del mondo.

Esercizio