mktime()

La funzione PHP mktime() costruisce un timestamp Unix dalle singole parti di data e ora — ora, minuto, secondo, mese, giorno e anno. È l'inverso di date(): mentre date() trasforma un timestamp in una stringa formattata, mktime() trasforma le parti di una data in un timestamp che puoi archiviare, confrontare o su cui eseguire operazioni aritmetiche.

Questo capitolo tratta l'ordine degli argomenti (che confonde quasi tutti), come mktime() normalizza automaticamente i valori fuori intervallo, il comportamento del fuso orario e quando è opportuno usare le classi DateTime invece.

Sintassi

mktime(
    int $hour = (current hour),
    ?int $minute = (current minute),
    ?int $second = (current second),
    ?int $month  = (current month),
    ?int $day    = (current day),
    ?int $year   = (current year)
): int|false

Il primo argomento, $hour, è obbligatorio a partire da PHP 8.0 — chiamare mktime() senza argomenti genera un ArgumentCountError. Qualsiasi argomento omesso assume per default la parte corrispondente della data e ora locali correnti. La funzione restituisce il timestamp come intero, oppure false se gli argomenti producono una data fuori dall'intervallo valido.

Un timestamp Unix è il numero di secondi trascorsi dall'epoca Unix — 1 gennaio 1970, 00:00:00 UTC. È la valuta comune per le date in PHP, nei database e nei sistemi operativi.

Attenzione all'ordine degli argomenti. mktime() riceve prima il tempo poi la data: ora, minuto, secondo, mese, giorno, anno. Questo è diverso da come solitamente scriviamo le date (anno-mese-giorno), ed è la fonte più comune di bug.

Costruire un timestamp specifico

Per rappresentare un momento preciso, passa tutte e sei le parti. Qui costruiamo le 14:30 del 15 giugno 2024:

Impostiamo il fuso orario esplicitamente in modo che l'output sia riproducibile. Senza date_default_timezone_set(), mktime() interpreta le parti nel fuso orario configurato del server, il che può spostare il timestamp risultante.

Calcoli con le date usando mktime()

Poiché un timestamp è semplicemente un numero di secondi, puoi aggiungere o sottrarre secondi per spostare una data in avanti o indietro. Per trovare la data 30 giorni dopo un dato giorno, aggiungi 30 × 86400 secondi (ci sono 86.400 secondi in un giorno):

Aggiungere 30 giorni a una data

Questo approccio basato sui secondi grezzi va bene per giorni interi, ma ignora le transizioni dell'ora legale: un "giorno" non è sempre esattamente 86.400 secondi. Per un'aritmetica del calendario corretta attraverso i confini dell'ora legale, usa invece DateTime::modify() o DateInterval.

Normalizzazione automatica

Una funzionalità comoda di mktime() è che normalizza i valori fuori intervallo: li riporta alla data corretta invece di fallire. Passa il mese 13 e otterrai gennaio dell'anno successivo; passa il giorno 0 e otterrai l'ultimo giorno del mese precedente:

Questo rende mktime() comodo per calcoli del tipo "ultimo giorno del mese": mktime(0, 0, 0, $month + 1, 0, $year) restituisce l'ultimo giorno di $month. Nota che questa tolleranza significa anche che mktime() non rifiuterà una data chiaramente non valida come il 30 febbraio — la riporterà silenziosamente al valore corretto. Se devi validare una data del calendario, usa prima checkdate().

Insidie comuni

• Ordine sbagliato degli argomenti. Scrivere mktime(2024, 6, 15) pensando che sia anno-mese-giorno produce una data senza senso. Ricorda: prima il tempo, poi mese, giorno, anno.
• Nessun argomento in PHP 8. mktime() con zero argomenti genera ArgumentCountError. Per ottenere il timestamp corrente, usa invece time().
• Anni a due cifre. Passa un anno completo a quattro cifre. I valori come 0–69 vengono mappati su 2000–2069 e 70–100 su 1970–2000, il che raramente è ciò che si vuole.

mktime() vs. le classi DateTime

mktime() è procedurale e lavora nel fuso orario locale. Per le parti in UTC, usa la funzione gemella gmmktime(). Per il nuovo codice, preferisci le classi orientate agli oggetti DateTime e DateTimeImmutable — portano informazioni sul fuso orario, gestiscono l'aritmetica consapevole dell'ora legale ed evitano la matematica manuale dei secondi:

Conclusione

mktime() costruisce un timestamp Unix dalle parti di data e ora, normalizzando automaticamente i valori fuori intervallo — il che lo rende comodo per calcoli rapidi con le date e trucchi come "ultimo giorno del mese". Tieni a mente le sue particolarità: il tempo viene prima della data nella lista degli argomenti, e una chiamata senza argomenti ora genera un errore (usa time() per "adesso"). Per lavori corretti rispetto all'ora legale e consapevoli del fuso orario in PHP moderno, preferisci DateTimeImmutable e DateInterval. Vedi anche checkdate() per la validazione e strtotime() per il parsing di stringhe di date in formato leggibile.

Esercizio