PHP Date

Introduzione

Quasi ogni applicazione deve leggere, formattare o eseguire calcoli su date: voci di log, etichette "pubblicato 3 giorni fa", pianificazione, controlli di scadenza. PHP mette a disposizione due set di strumenti paralleli:

• Funzioni procedurali basate sul Unix timestamp — un intero che conta i secondi dal 1° gennaio 1970, 00:00:00 UTC. time(), date(), strtotime() e mktime() appartengono a questa categoria.
• L'API orientata agli oggetti DateTime — DateTime, DateTimeImmutable, DateTimeZone e DateInterval — più sicura per l'aritmetica e la gestione dei fusi orari.

Questa pagina tratta le funzioni e le classi più utilizzate, quando scegliere ciascuna e la trappola dei fusi orari che coglie quasi tutti di sorpresa.

Nota sui fusi orari

Per impostazione predefinita, PHP usa il fuso orario configurato in php.ini (impostazione date.timezone). Se non è impostato, si possono ottenere risultati inconsistenti tra server diversi. Impostalo esplicitamente all'inizio dello script oppure passa un DateTimeZone a ciascun oggetto:

date_default_timezone_set('UTC');

Consulta PHP Timezones per l'elenco completo degli identificatori validi e per scoprire come convertire tra fusi orari.

La funzione date()

date(string $format, ?int $timestamp = null) formatta un timestamp in una stringa leggibile. Se si omette il timestamp, viene usato il momento attuale. È lo strumento principale per visualizzare le date.

echo date('Y-m-d H:i:s'); // e.g. 2023-10-25 14:30:00
echo date('l, F j, Y');   // e.g. Wednesday, October 25, 2023

La stringa format è composta da segnaposto a singolo carattere. I più comuni:

Per stampare una lettera letterale che è anche un carattere di formato, eseguine l'escape con una barra rovesciata: date('\T\o\d\a\y: Y-m-d').

La funzione time()

time() restituisce il timestamp Unix corrente come intero. Usala ogni volta che hai bisogno di un "adesso" numerico da memorizzare, confrontare o su cui fare aritmetica.

$now = time();
echo $now; // an integer such as 1698241800

// One hour from now:
echo date('Y-m-d H:i:s', $now + 3600);

Poiché un timestamp è semplicemente un intero di secondi, puoi aggiungere o sottrarre durate direttamente (+ 3600 per un'ora, + 86400 per un giorno). Per qualcosa di più complesso di pochi offset fissi, preferisci l'aritmetica con DateTime descritta di seguito.

La funzione strtotime()

strtotime(string $datetime, ?int $baseTimestamp = null) analizza una data/ora testuale in inglese e la converte in un timestamp, restituendo false in caso di errore. Comprende sia stringhe assolute che frasi relative.

echo strtotime('2023-10-25 14:30:00'); // 1698244200 (UTC)
echo "\n";
var_dump(strtotime('next monday'));    // a future timestamp, or false if unparseable

$tomorrow = strtotime('+1 day');
echo date('Y-m-d', $tomorrow);

Controlla sempre se il risultato è false prima di usarlo, poiché un errore di battitura fallisce silenziosamente invece di lanciare un'eccezione.

La funzione mktime()

mktime(int $hour, int $minute, int $second, int $month, int $day, int $year) costruisce un timestamp a partire da componenti individuali. L'ordine degli argomenti è prima il tempo, poi la data.

$timestamp = mktime(0, 0, 0, 12, 31, 2023);
echo date('Y-m-d', $timestamp); // 2023-12-31

mktime() normalizza i valori fuori intervallo, il che è comodo: mktime(0, 0, 0, 13, 1, 2023) trasforma "mese 13" in gennaio 2024.

La classe DateTime

new DateTime(string $datetime = 'now', ?DateTimeZone $timezone = null) racchiude una data in un oggetto che puoi formattare, confrontare e modificare con chiamate ai metodi. (La funzione date_create() è un alias procedurale dello stesso costruttore.)

$date = new DateTime('2023-10-25', new DateTimeZone('UTC'));
echo $date->format('Y-m-d'); // 2023-10-25

DateTime è mutabile — metodi come modify() modificano l'oggetto sul posto. Questa è la fonte di bug sottili quando un oggetto è condiviso, motivo per cui la versione immutabile descritta di seguito è generalmente preferita.

La classe DateTimeImmutable

DateTimeImmutable ha la stessa API di DateTime, ma ogni metodo modificante restituisce un nuovo oggetto e lascia l'originale invariato. Per il codice moderno questa è la scelta più sicura.

$date = new DateTimeImmutable('2023-10-25');
$newDate = $date->modify('+1 day');
echo $date->format('Y-m-d');    // 2023-10-25 (unchanged)
echo "\n";
echo $newDate->format('Y-m-d'); // 2023-10-26

Il metodo DateTime::format()

format(string $format) trasforma un oggetto DateTime o DateTimeImmutable in una stringa. Accetta gli stessi caratteri di formato della funzione date().

$date = new DateTimeImmutable('2023-10-25 14:30:00');
echo $date->format('l, F j, Y'); // Wednesday, October 25, 2023

Aritmetica e differenze tra date

L'API a oggetti eccelle nell'aritmetica. Usa DateInterval (stringhe di durata ISO-8601) per aggiungere o sottrarre, e diff() per confrontare due date:

$start = new DateTimeImmutable('2023-10-25');
$later = $start->add(new DateInterval('P10D')); // P10D = 10 days
echo $later->format('Y-m-d'); // 2023-11-04

$diff = $start->diff(new DateTimeImmutable('2023-12-31'));
echo "\n" . $diff->days . ' days apart'; // 67 days apart

Scegliere lo strumento giusto

• Hai bisogno di un "adesso" formattato rapidamente? Usa date().
• Stai memorizzando o confrontando un momento numericamente? Usa time() / Unix timestamp.
• Stai analizzando input dell'utente o di log? Usa strtotime() (e controlla se restituisce false).
• Stai facendo aritmetica, diff o conversioni di fuso orario? Usa DateTimeImmutable con DateInterval.

Errori comuni

• Fuso orario non impostato. Senza date_default_timezone_set() o un valore in php.ini, i risultati variano da server a server. Impostalo una volta, all'inizio.
• strtotime() restituisce false per stringhe non riconosciute — non lancia mai un'eccezione, quindi valida sempre il risultato.
• DateTime è mutabile. modify() modifica l'originale; usa DateTimeImmutable per evitare sorprese legate allo stato condiviso.
• I timestamp sono secondi UTC. Formattarli con date() applica il fuso orario corrente, quindi lo stesso intero viene visualizzato in modo diverso a seconda delle impostazioni.

Conclusione

PHP mette a disposizione un toolkit procedurale per i timestamp (date(), time(), strtotime(), mktime()) e uno orientato agli oggetti (DateTime, DateTimeImmutable). Affidati ai timestamp semplici per la visualizzazione e la memorizzazione, e a DateTimeImmutable per l'aritmetica e la logica consapevole dei fusi orari. Per approfondimenti, consulta PHP Date and Time, il riferimento date(), strtotime() e mktime().

Esercitazione