date_modify()

Questa guida illustra il metodo PHP DateTime::modify() (la controparte orientata agli oggetti della funzione procedurale date_modify()). Spiega come modify() analizza le stringhe di data relative, cosa restituisce, il problema del trabocchetto dei mesi che mette in difficoltà la maggior parte degli sviluppatori e come evitare di mutare una data per errore.

Cos'è DateTime::modify()?

modify() è un metodo integrato della classe DateTime che modifica la data/ora che contiene utilizzando una stringa in formato relativo come +10 days, -3 months o next monday. Usalo ogni volta che hai bisogno di fare aritmetica sulle date — spostare una scadenza in avanti, far retrocedere un timestamp o saltare al prossimo giorno della settimana — senza calcolare manualmente i secondi.

Due caratteristiche rendono modify() distintivo e vale la pena fissarle nella mente prima di leggere gli esempi:

• Muta l'oggetto sul posto — modifica lo stesso DateTime su cui viene chiamato invece di restituire una copia nuova.
• Accetta la stessa grammatica in formato relativo che PHP usa quando costruisce date da stringhe, quindi tutto ciò che new DateTime('+1 week') comprende, lo comprende anche modify().

Sintassi

public DateTime::modify(string $modifier): DateTime|false

• $modifier — una stringa in formato relativo (es. +1 day, -2 weeks, first day of next month, 14:00).
• Restituisce lo stesso oggetto DateTime in caso di successo (in modo che le chiamate possano essere concatenate), oppure false in caso di errore (ad esempio, una stringa non analizzabile).

Poiché restituisce l'oggetto stesso, queste due righe sono equivalenti — il $date originale viene modificato in entrambi i casi:

$date->modify('+1 day');          // mutates $date, return value ignored
$date = $date->modify('+1 day');  // mutates $date AND reassigns the same object

Suggerimento: Quando $modifier proviene dall'input dell'utente, verifica sempre il valore false prima di usare il risultato, poiché una stringa malformata restituisce false invece di generare un'eccezione.

Esempi

Esempio 1: Aggiungere giorni a una data

Per aggiungere 10 giorni a una data fissa con gestione di base degli errori:

Aggiungere giorni a una data in PHP

Output:

2023-03-11

Esempio 2: Sottrarre mesi da una data

Per sottrarre 3 mesi da una data fissa:

Sottrarre mesi da una data in PHP

Output:

2022-12-01

Esempio 3: Impostare l'ora a un valore specifico

Per impostare l'ora alle 14:00 su una data fissa:

Impostare l'ora a un valore specifico in PHP

Output:

2023-03-01 14:00:00

Nota che modify('14:00') imposta la parte relativa all'ora alle 14:00 ma lascia la data invariata — i formati relativi che menzionano solo un'ora agiscono sull'ora, non sul giorno.

Esempio 4: Combinare più unità in una sola chiamata

È possibile combinare più unità relative in una singola stringa modificatore, separate da spazi. Vengono applicate da sinistra a destra:

<?php

$date = new DateTime('2023-03-01');
$date->modify('+1 week +2 days');
echo $date->format('Y-m-d');

Output:

2023-03-10

Il trabocchetto del trabocco dei mesi

L'aggiunta o la sottrazione di mesi non si blocca alla fine di un mese più corto — trabocca nel mese successivo. Guarda cosa succede quando si aggiunge un mese al 31 gennaio:

<?php

$date = new DateTime('2023-01-31');
$date->modify('+1 month');
echo $date->format('Y-m-d');

Output:

2023-03-03

Poiché febbraio 2023 ha solo 28 giorni, "31 gennaio + 1 mese" arriva al "31 febbraio" inesistente, che PHP fa avanzare al 3 marzo. Se invece hai bisogno dell'ultimo giorno del mese successivo, usa un formato relativo assoluto:

<?php

$date = new DateTime('2023-01-31');
$date->modify('last day of next month');
echo $date->format('Y-m-d');

Output:

2023-02-28

Evitare la mutazione accidentale con DateTimeImmutable

Poiché modify() modifica l'oggetto sul posto, condividere un singolo DateTime nel codice può causare bug difficili da trovare — modificarlo in un punto influisce su ogni riferimento ad esso. Se vuoi che ogni operazione restituisca un valore nuovo e lasci intatto l'originale, usa DateTimeImmutable, il cui modify() restituisce un oggetto nuovo:

<?php

$original = new DateTimeImmutable('2023-03-01');
$nextWeek = $original->modify('+7 days');

echo $original->format('Y-m-d') . "\n"; // unchanged
echo $nextWeek->format('Y-m-d');

Output:

2023-03-01
2023-03-08

Formati relativi utili

modify() accetta una ricca grammatica di frasi relative. Alcune delle più comuni:

Funzioni correlate

• date_add() — aggiunge un DateInterval a una data.
• date_sub() — sottrae un DateInterval da una data.
• date_diff() — ottiene la differenza tra due date.
• date_format() — formatta un oggetto DateTime come stringa.

Riepilogo

DateTime::modify() applica una stringa in formato relativo a una data, mutando l'oggetto sul posto e restituendolo (oppure false in caso di errore). È ideale per l'aritmetica delle date e per saltare a giorni con nome, ma ricorda due cose: i calcoli sui mesi traboccano oltre i mesi più brevi e la mutazione è condivisa — usa DateTimeImmutable quando hai bisogno che l'originale sia preservato.

Pratica