timezone_name_get()

Introduzione

Questo articolo tratta la funzione timezone_name_get in PHP. Ne esploreremo la sintassi, i parametri e i valori di ritorno, con esempi pratici. Questa funzione legge l'identificatore da un oggetto DateTimeZone, il che risulta utile quando si memorizza un oggetto fuso orario e in seguito si ha bisogno del suo nome per log, visualizzazione o confronto.

timezone_name_get è l'alias procedurale del metodo DateTimeZone::getName. I due sono intercambiabili, quindi usa quello più adatto al tuo stile di codice.

Disponibilità: timezone_name_get fa parte dell'estensione date/time integrata di PHP. È sempre disponibile — non è necessario installare alcuna estensione aggiuntiva (come intl).

Sintassi

La funzione timezone_name_get accetta un singolo oggetto DateTimeZone e restituisce il nome del fuso orario che rappresenta. Ecco la firma:

Sintassi della funzione PHP timezone_name_get()

timezone_name_get(DateTimeZone $object): string

Analizziamo i parametri:

• $object: Un oggetto DateTimeZone che rappresenta un fuso orario.

Parametri

Come già accennato, la funzione timezone_name_get accetta un solo parametro: un oggetto DateTimeZone. Questo oggetto rappresenta un fuso orario specifico e viene creato usando la classe DateTimeZone. Ecco un esempio di creazione di un oggetto DateTimeZone:

Esempio di creazione di un oggetto DateTimeZone in PHP

<?php

$timezone = new DateTimeZone('America/New_York');

In questo esempio creiamo un oggetto DateTimeZone che rappresenta il fuso orario Eastern degli Stati Uniti.

Nota: In PHP 8+, il controllo dei tipi è rigoroso. Passare un argomento che non è un oggetto DateTimeZone genererà un TypeError.

Valori di ritorno

La funzione timezone_name_get restituisce una string che rappresenta il nome del fuso orario dell'oggetto DateTimeZone passato come parametro. Ecco un esempio di utilizzo:

Esempio di utilizzo della funzione timezone_name_get() in PHP

In questo esempio creiamo un oggetto DateTimeZone che rappresenta il fuso orario Eastern, poi lo passiamo alla funzione timezone_name_get. La funzione restituisce la string "America/New_York", che visualizziamo con l'istruzione echo.

La funzione restituisce sempre l'identificatore canonico con cui è stato costruito l'oggetto. Se si crea l'oggetto da un offset o un'abbreviazione, il nome restituito lo riflette:

Nomi per zone basate su offset e abbreviazione

<?php

echo timezone_name_get(new DateTimeZone('+05:00')), PHP_EOL; // Output: +05:00
echo timezone_name_get(new DateTimeZone('GMT')), PHP_EOL;    // Output: GMT
echo timezone_name_get(new DateTimeZone('UTC')), PHP_EOL;    // Output: UTC

Per le zone denominate, il risultato è la stessa string che puoi passare a funzioni come date_default_timezone_set, il che la rende un identificatore sicuro per il round-trip.

Esempi pratici

Ora che abbiamo coperto le basi della funzione timezone_name_get, esploriamo alcuni esempi pratici del suo utilizzo.

Esempio 1: Visualizzare i fusi orari in un menu a discesa

Supponiamo di voler creare un form che permetta agli utenti di selezionare il proprio fuso orario. Possiamo usare la classe DateTimeZone insieme alla funzione timezone_name_get per popolare un menu a discesa con tutti i fusi orari disponibili. Ecco un esempio:

Visualizzazione dei fusi orari in un menu a discesa in PHP

<select name="timezone">
  <?php foreach(DateTimeZone::listIdentifiers() as $timezone): ?>
    <option value="<?php echo $timezone; ?>">
      <?php echo $timezone; ?>
    </option>
  <?php endforeach; ?>
</select>

In questo esempio usiamo il metodo listIdentifiers della classe DateTimeZone per ottenere l'elenco di tutti i fusi orari disponibili. Poiché listIdentifiers restituisce già i nomi canonici dei fusi orari, possiamo usare direttamente $timezone sia per il valore che per l'etichetta, rendendo il codice più efficiente.

Esempio 2: Convertire una data in un altro fuso orario

Supponiamo di avere una data nel fuso orario Pacific e di volerla convertire nel fuso orario Eastern. Possiamo usare la classe DateTime insieme a DateTimeZone e alla funzione timezone_name_get per farlo. Ecco un esempio:

Conversione di una data in un altro fuso orario in PHP

In questo esempio creiamo un oggetto DateTime che rappresenta una data e un orario nel fuso orario Pacific, usando l'identificatore America/Los_Angeles. Creiamo poi un clone di questo oggetto e usiamo il metodo setTimezone per convertirlo nel fuso orario Eastern, con l'identificatore America/New_York. Infine, visualizziamo le date in entrambi i fusi orari usando il metodo format e verifichiamo i nomi dei fusi orari attivi con timezone_name_get.

Notare che l'ora Eastern mostra 12:00:00 rispetto alle 09:00:00 Pacific — tre ore avanti, esattamente come atteso.

Alternativa orientata agli oggetti

Poiché timezone_name_get è solo un wrapper attorno a DateTimeZone::getName, puoi chiamare direttamente il metodo:

Stile procedurale vs. orientato agli oggetti

<?php

$timezone = new DateTimeZone('Europe/Berlin');

echo timezone_name_get($timezone), PHP_EOL; // Procedural
echo $timezone->getName(), PHP_EOL;          // Object-oriented
// Both output: Europe/Berlin

Entrambe le forme restituiscono la stessa string. Il metodo orientato agli oggetti si concatena facilmente quando si ha già un'istanza di DateTimeZone.

Funzioni correlate

• timezone_open — crea un oggetto DateTimeZone di cui puoi leggere il nome in seguito.
• date_timezone_get — ottieni il DateTimeZone associato a un oggetto DateTime.
• timezone_offset_get — ottieni l'offset di un fuso orario (in secondi) rispetto all'UTC per un dato momento.
• timezone_identifiers_list — elenca tutti gli identificatori di fuso orario validi.

Per una panoramica più ampia, consulta il capitolo PHP Timezones.

Conclusione

Questo articolo ha trattato la funzione timezone_name_get in PHP, incluse sintassi, parametri, valori di ritorno e casi d'uso pratici. Restituisce l'identificatore canonico memorizzato in un oggetto DateTimeZone, è disponibile senza estensioni aggiuntive e rispecchia il metodo DateTimeZone::getName. Speriamo che queste informazioni ti aiutino a gestire le conversioni di fuso orario in modo più affidabile nei tuoi progetti.

Pratica