date_isodate_set()

La funzione date_isodate_set() imposta la data di un object DateTime utilizzando il calendario a settimane ISO 8601 — ovvero, tramite anno, numero di settimana e giorno della settimana anziché tramite mese e giorno. È l'alias procedurale del metodo DateTime::setISODate(), quindi entrambi fanno esattamente la stessa cosa.

Questa pagina tratta la sintassi della funzione, le differenze tra il calendario a settimane ISO e il calendario ordinario, esempi eseguibili e gli errori più comuni.

Sintassi

La funzione date_isodate_set() ha la seguente sintassi:

Sintassi della funzione PHP date_isodate_set()

date_isodate_set(DateTime $object, int $year, int $week, int $dayOfWeek = 1): DateTime

dove:

• $object — l'object DateTime da modificare (viene modificato in-place).
• $year — l'anno ISO.
• $week — il numero di settimana ISO, da 1 a 53.
• $dayOfWeek — il giorno della settimana, 1 per lunedì fino a 7 per domenica (opzionale, il valore predefinito è 1).

La funzione restituisce lo stesso object DateTime, quindi le chiamate possono essere concatenate. La chiamata equivalente in stile orientato agli object è:

$date->setISODate($year, $week, $dayOfWeek);

Perché usare le date a settimane ISO

A differenza del calendario ordinario, ISO 8601 numera ogni settimana dell'anno e identifica una data tramite (anno, settimana, giorno della settimana). Questo è comodo per i report aziendali, la pianificazione e qualsiasi sistema che ragiona in settimane anziché in mesi.

Vale la pena ricordare due regole:

• La settimana 1 è la settimana che contiene il primo giovedì dell'anno — equivalentemente, la settimana che contiene il 4 gennaio. Per questo motivo, i primi giorni di gennaio possono appartenere all'anno ISO precedente, e gli ultimi giorni di dicembre possono appartenere a quello successivo.
• I valori fuori intervallo traboccano invece di generare un errore. Richiedere la settimana 53 o il giorno 7 di una settimana che non esiste fa semplicemente avanzare la data alla settimana o all'anno successivo. Ad esempio, date_isodate_set($d, 2022, 52, 7) restituisce 2023-01-01, perché la 52ª settimana del 2022 termina domenica 1º gennaio 2023.

Nota: date_isodate_set() modifica solo la parte relativa alla data. L'ora rimane quella già presente nel DateTime (l'ora corrente per un object appena creato).

Esempi

Utilizzo di base

Imposta una data al 3º giorno (mercoledì) della 10ª settimana ISO del 2023:

La funzione modifica $date in-place. Si parte da un momento fisso in modo che l'output sia sempre lo stesso; viene sostituita solo la parte della data.

I numeri di settimana possono attraversare il confine dell'anno

Richiedere l'ultimo giorno dell'ultima settimana del 2022 porta a gennaio 2023 — è il calendario ISO in azione, non un bug:

La 52ª settimana del 2022 termina domenica 1º gennaio 2023, quindi quella è la data restituita.

Equivalente orientato agli object

DateTime::setISODate() svolge lo stesso compito e restituisce l'object, il che consente di concatenare direttamente una chiamata a format():

Questo imposta la data al 1º giorno (lunedì) della 24ª settimana del 2023.

Funzioni correlate

• date_create() — crea un object DateTime da passare alla funzione.
• date_format() — formatta la data risultante per la visualizzazione.

Conclusione

date_isodate_set() imposta un DateTime su un (anno, settimana, giorno della settimana) specifico utilizzando il calendario a settimane ISO 8601. Ricorda che la settimana ISO 1 contiene il primo giovedì dell'anno, che i valori di settimana e giorno fuori intervallo traboccano nella settimana o nell'anno successivo invece di generare errori, e che viene modificata solo la data — non l'ora.

Esercitazione