timezone_offset_get()

La funzione timezone_offset_get() in PHP restituisce l'offset del fuso orario in secondi rispetto al Tempo Coordinato Universale (UTC) per un dato oggetto DateTimeInterface. Questa guida ne illustra la sintassi, i parametri e l'utilizzo pratico.

Comprensione di timezone_offset_get()

La funzione timezone_offset_get() restituisce l'offset del fuso orario in secondi rispetto al Tempo Coordinato Universale (UTC) per una data e un'ora specificate. È una funzione integrata di PHP che consente agli sviluppatori di manipolare date e orari in base a fusi orari specifici.

Sintassi

La sintassi della funzione timezone_offset_get() in PHP è la seguente:

Sintassi della funzione timezone_offset_get() in PHP

<?php
timezone_offset_get(DateTimeZone $object, DateTimeInterface $datetime): int

In forma procedurale, la funzione accetta un oggetto DateTimeZone e l'oggetto DateTimeInterface per cui si vuole l'offset, e restituisce l'offset in secondi. La maggior parte degli sviluppatori utilizza l'equivalente orientato agli oggetti, DateTimeZone::getOffset(), che risulta più leggibile:

<?php
$tz   = new DateTimeZone('America/Los_Angeles');
$date = new DateTime('2019-01-01 12:00:00', $tz);

// These two calls are equivalent:
$offset = timezone_offset_get($tz, $date);
$offset = $tz->getOffset($date);

Parametri

La funzione timezone_offset_get() accetta due parametri:

1. $object - Un oggetto DateTimeZone di cui si vuole leggere l'offset.
2. $datetime - Un oggetto DateTimeInterface (un DateTime o DateTimeImmutable) che rappresenta il momento nel tempo per cui viene calcolato l'offset.

Il momento è importante: a causa dell'ora legale, lo stesso fuso orario può avere un offset diverso in estate rispetto all'inverno, quindi è necessario indicare alla funzione quale istante si intende.

Valore di ritorno e note

• Valore di ritorno: Restituisce un offset intero in secondi. È negativo per i fusi orari a ovest di UTC (le Americhe) e positivo per quelli a est.
• Versione PHP: Disponibile dal PHP 5.2.0.
• Gestione DST: L'offset tiene automaticamente conto dell'ora legale. Per America/Los_Angeles, una data invernale restituisce -28800 (UTC-8) mentre una data estiva restituisce -25200 (UTC-7).
• Ore, non secondi: Per convertire il risultato in ore, dividi per 3600 (es. -28800 / 3600 = -8).

Applicazioni pratiche

La funzione timezone_offset_get() in PHP è uno strumento potente per lavorare con date e orari in fusi orari specifici. Alcune applicazioni pratiche di questa funzione includono:

1. Visualizzare informazioni su data e ora in base alle preferenze di fuso orario dell'utente.
2. Convertire informazioni su data e ora da un fuso orario a un altro.
3. Eseguire calcoli su date e orari con offset di fuso orario accurati.

Esempio di utilizzo

Ecco un esempio di utilizzo della funzione timezone_offset_get() in PHP:

Esempio della funzione PHP timezone_offset_get()

La data di gennaio cade fuori dall'ora legale, quindi l'offset è -28800 secondi (UTC-8):

-28800

L'ora legale in azione

Chiamando lo stesso fuso orario con una data estiva si ottiene un offset diverso, perché l'ora legale del Pacifico corrisponde a UTC-7. Formattare l'offset in ore rende il risultato più leggibile:

<?php
$tz = new DateTimeZone('America/Los_Angeles');

foreach (['2019-01-01 12:00:00', '2019-07-01 12:00:00'] as $when) {
    $date    = new DateTime($when, $tz);
    $seconds = $tz->getOffset($date);
    $hours   = $seconds / 3600;
    echo "$when => $seconds seconds (UTC$hours)\n";
}

2019-01-01 12:00:00 => -28800 seconds (UTC-8)
2019-07-01 12:00:00 => -25200 seconds (UTC-7)

Conclusione

timezone_offset_get() (e il suo equivalente orientato agli oggetti DateTimeZone::getOffset()) restituisce la distanza esatta di un fuso orario da UTC in secondi per un momento specifico, con l'ora legale già considerata. Dividi per 3600 quando hai bisogno delle ore, e ricorda di passare la data corretta affinché l'ora legale venga risolta correttamente.

Per approfondire, consulta date_default_timezone_set() per impostare il fuso orario predefinito dello script, timezone_name_get() per leggere il nome di un fuso orario, e l'elenco completo dei fusi orari PHP.

Esercitazione