gmmktime()

Cos'è la funzione gmmktime() di PHP?

La funzione gmmktime() di PHP costruisce un timestamp Unix dalle singole parti di una data e ora (ora, minuto, secondo, mese, giorno, anno), interpretando tali parti come GMT/UTC anziché il fuso orario locale del server. Un timestamp Unix è semplicemente il numero di secondi trascorsi dal 1° gennaio 1970, 00:00:00 UTC — il valore utilizzato internamente dalla maggior parte delle funzioni di data di PHP.

Questa pagina illustra la sintassi e i parametri della funzione, le differenze rispetto a mktime(), il comportamento di rollover per valori fuori intervallo e l'errore che colpisce la maggior parte degli sviluppatori: nelle versioni moderne di PHP i parametri non sono tutti opzionali.

Il nome si legge come greenwich mean time + make time.

Sintassi

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

Restituisce il timestamp come intero, oppure false se gli argomenti descrivono un'ora non valida.

Parametri

Attenzione: In PHP 8.0 e versioni successive, chiamare gmmktime() senza argomenti genera un ArgumentCountError — hour è obbligatorio. Qualsiasi argomento omesso assume come valore predefinito il corrispondente valore dell'ora GMT corrente. Per ottenere il timestamp attuale, usa invece time().

Esempio di base

Questo genera il timestamp Unix per il 3 marzo 2023 alle 12:30:00 GMT. Per visualizzarlo in un formato leggibile, abbinalo a gmdate():

<?php

$timestamp = gmmktime(12, 30, 0, 3, 3, 2023);
echo gmdate('Y-m-d H:i:s', $timestamp);
// 2023-03-03 12:30:00

gmmktime() vs. mktime()

gmmktime() e mktime() accettano gli stessi argomenti e restituiscono un timestamp Unix — l'unica differenza è il fuso orario in cui le parti vengono interpretate. gmmktime() le tratta come GMT/UTC; mktime() le tratta come fuso orario locale del server. Con gli stessi input producono timestamp diversi quando l'ora locale è sfasata rispetto a UTC:

<?php

date_default_timezone_set('America/New_York'); // UTC-4 in June

echo gmmktime(12, 0, 0, 6, 15, 2023), "\n"; // 1686830400  (12:00 UTC)
echo mktime(12, 0, 0, 6, 15, 2023), "\n";    // 1686844800  (12:00 New York = 16:00 UTC)

Usa gmmktime() quando i tuoi input sono già in UTC (timestamp da un'API, un database memorizzato in UTC, ecc.) in modo che il risultato non vari con l'impostazione del fuso orario del server.

Rollover dei valori fuori intervallo

Non è necessario mantenere le parti nei loro intervalli normali. gmmktime() le normalizza, il che è utile per l'aritmetica delle date senza riporti manuali:

<?php

// Month 13 rolls into the next year
echo gmdate('Y-m-d', gmmktime(0, 0, 0, 13, 1, 2023)), "\n"; // 2024-01-01

// Day 32 of January becomes February 1st
echo gmdate('Y-m-d', gmmktime(0, 0, 0, 1, 32, 2023)), "\n"; // 2023-02-01

// Hour 25 rolls into the next day at 01:00
echo gmdate('Y-m-d H:i', gmmktime(25, 0, 0, 1, 1, 2023)), "\n"; // 2023-01-02 01:00

Questo rende espressioni come gmmktime(0, 0, 0, $month, $day + 7, $year) ("sette giorni dopo") funzionanti correttamente attraverso i confini di mese e anno.

Quando usare gmmktime()

• Coerenza del fuso orario. Poiché usa sempre UTC, gli stessi argomenti producono lo stesso timestamp su qualsiasi server, indipendentemente da date.timezone.
• Costruzione di timestamp da componenti. Quando si hanno valori separati di ora/giorno/mese (ad es. da un modulo o una stringa analizzata) anziché una singola stringa di data. Per una stringa di data completa come "2023-03-03 12:30", usa invece strtotime().
• Aritmetica delle date tramite rollover. Aggiungi o sottrai da un componente e lascia che la funzione normalizzi il risultato.

Se hai solo bisogno di verificare che una combinazione mese/giorno/anno sia una data di calendario valida, consulta checkdate().

Conclusione

gmmktime() converte componenti separati di data e ora in un timestamp Unix basato su UTC. I suoi punti di forza principali sono l'indipendenza dal fuso orario e la normalizzazione automatica dei valori fuori intervallo. Ricorda che, a differenza delle versioni precedenti di PHP, PHP 8+ richiede almeno l'argomento hour, usa mktime() quando i tuoi input sono in ora locale e gmdate() per formattare il risultato.

Esercitazione