date_default_timezone_set()

Introduzione

La funzione date_default_timezone_set() imposta il fuso orario predefinito utilizzato da ogni funzione data/ora in uno script PHP. Una volta chiamata, funzioni come date(), mktime(), strtotime() e DateTime interpretano e formattano le ore in relazione a quel fuso orario. Questa pagina spiega cosa fa la funzione, quando è necessaria e le insidie da tenere a mente.

Sintassi

date_default_timezone_set(string $timezoneId): bool

$timezoneId è una string identificatore di fuso orario del database IANA, ad esempio Europe/London o Asia/Tokyo — non un'abbreviazione come EST. La funzione restituisce true in caso di successo e false se l'identificatore non è valido. Quando l'identificatore non è valido, PHP emette anche un E_WARNING e ripristina il fuso orario configurato in precedenza.

Perché è importante

Un timestamp è semplicemente un numero di secondi dall'epoca Unix (UTC). Per trasformare quel numero in una data leggibile — "2024-03-15 14:30" — PHP ha bisogno di sapere in quale fuso orario visualizzarla. Se non ne viene impostato uno, PHP utilizza il valore date.timezone da php.ini, che può differire tra il computer locale, lo staging e la produzione. Questa discrepanza è una fonte classica di bug del tipo "l'orario è sbagliato di qualche ora".

Chiamare date_default_timezone_set() all'inizio dello script rende il fuso orario esplicito e coerente ovunque venga eseguito il codice, indipendentemente dalla configurazione del server.

Utilizzo di base

<?php
date_default_timezone_set('America/New_York');

echo date('Y-m-d H:i:s');

Questo imposta il fuso orario dello script sull'ora dell'Est degli Stati Uniti. Ogni successiva chiamata a funzioni data/ora viene ora visualizzata in quel fuso. Impostare il fuso non modifica il timestamp sottostante — cambia solo il modo in cui viene visualizzato.

Cambiare il fuso orario a runtime

È possibile modificare il fuso orario predefinito più di una volta. Lo stesso timestamp Unix mostra un orario diverso in ciascun fuso:

Qui date_default_timezone_get() conferma il fuso attualmente attivo — utile per il debug.

Gestire un identificatore non valido

Poiché la funzione restituisce false (e lancia un avviso) con un identificatore errato, è bene validare il valore di ritorno quando il fuso proviene da input utente o da una configurazione:

<?php
$zone = 'Mars/Olympus_Mons'; // not a real timezone

if (@date_default_timezone_set($zone)) {
    echo "Timezone set to $zone\n";
} else {
    date_default_timezone_set('UTC');
    echo "Invalid timezone, falling back to UTC\n";
}
// Outputs: Invalid timezone, falling back to UTC

Identificatori comunemente usati

PHP supporta centinaia di fusi orari. Alcuni tra i più utilizzati:

Per la lista completa generata automaticamente usa timezone_identifiers_list() e consulta il riferimento sui fusi orari PHP per una panoramica.

Buone pratiche

• Impostalo una volta, subito. Chiamalo vicino all'inizio del file di bootstrap/entry point in modo che l'intera richiesta condivida un unico fuso.
• Preferisci memorizzare in UTC. Salva i timestamp in UTC nel database e converti nel fuso dell'utente solo per la visualizzazione; questo evita ambiguità legate all'ora legale.
• Usa gli identificatori, non le abbreviazioni. Europe/London gestisce l'ora legale automaticamente; GMT/BST non lo fanno.

Conclusione

date_default_timezone_set() offre un controllo esplicito su come PHP visualizza le date e gli orari, mantenendo il comportamento coerente tra i diversi ambienti. Impostalo deliberatamente, valida gli identificatori non attendibili e verifica il fuso attivo con date_default_timezone_get() quando qualcosa sembra sbagliato.

Esercizio