Funzione PHP date_date_set()

In PHP, date_date_set() e il suo corrispettivo orientato agli oggetti DateTime::setDate() impostano una nuova data (anno, mese e giorno) su un oggetto DateTime esistente. La parte relativa all'orario dell'oggetto rimane invariata — cambia solo la data del calendario. Questo è il corrispettivo lato data di DateTime::setTime(), che modifica soltanto l'orario.

Usalo quando hai già un oggetto DateTime e vuoi spostarlo a un giorno specifico senza ricostruire l'oggetto da una stringa.

Sintassi

setDate() è disponibile sia come metodo che come funzione procedurale. Le due forme fanno esattamente la stessa cosa:

La sintassi per DateTime::setDate() e date_date_set()

// Object-oriented style
$datetime->setDate($year, $month, $day);

// Procedural style
date_date_set($datetime, $year, $month, $day);

Dove:

• $datetime è l'oggetto DateTime da modificare.
• $year è il nuovo anno (es. 2024).
• $month è il nuovo mese (1–12).
• $day è il nuovo giorno del mese (1–31).

Il metodo restituisce lo stesso oggetto DateTime, quindi le chiamate possono essere concatenate. L'orario, i microsecondi e il fuso orario esistenti dell'oggetto vengono tutti preservati.

Esempio di utilizzo

Impostiamo una nuova data su un oggetto DateTime mantenendo il suo orario originale:

Esempio del metodo PHP DateTime::setDate()

Creiamo un DateTime per 2000-01-01 12:30:00, poi chiamiamo setDate() per cambiare la data al 15 luglio 2024. Poiché setDate() tocca solo la data del calendario, l'orario 12:30:00 viene preservato. Utilizziamo quindi il metodo format() per stampare il risultato:

2024-07-15 12:30:00

Stile procedurale

Se preferisci (o stai leggendo codice più vecchio), la stessa modifica può essere scritta con date_date_set(). Accetta l'oggetto come primo argomento:

<?php

$date = date_create('2000-01-01');
date_date_set($date, 2024, 7, 15);
echo $date->format('Y-m-d');

Questo stampa 2024-07-15. Qui date_create() costruisce l'oggetto — è l'equivalente procedurale di new DateTime.

I giorni fuori range scorrono al mese successivo

Come il resto delle API di DateTime, setDate() non valida il giorno rispetto alla lunghezza del mese. Al contrario, normalizza il valore e trasferisce qualsiasi eccedenza al mese successivo. Chiedere "il 31 febbraio" restituisce una data a marzo:

<?php

$date = new DateTime('2024-01-31');
$date->setDate(2024, 2, 31);
echo $date->format('Y-m-d');

Questo stampa 2024-03-02: febbraio 2024 ha 29 giorni, quindi il 31° giorno è 2 giorni oltre la fine del mese e cade il 2 marzo. Questo scorrimento è comodo per l'aritmetica delle date, ma è una fonte comune di bug silenziosi se ti aspettavi un'eccezione. Per spostare una data di un importo relativo, usa invece modify(), add() o sub().

Mutabile vs. Immutabile

DateTime è mutabile: setDate() modifica l'oggetto sul posto e restituisce lo stesso oggetto. Se il valore è condiviso altrove nel codice, ogni riferimento vedrà la modifica. Per evitare mutazioni accidentali, usa DateTimeImmutable, il cui setDate() restituisce una nuova istanza e lascia intatto l'originale:

<?php

$original = new DateTimeImmutable('2000-01-01');
$changed  = $original->setDate(2024, 7, 15);

echo $original->format('Y-m-d'), ' | ', $changed->format('Y-m-d');

Questo stampa 2000-01-01 | 2024-07-15: $original è intatto e $changed contiene la nuova data. Con il DateTime mutabile, entrambe le variabili punterebbero allo stesso oggetto modificato.

Metodi correlati

setDate() raramente opera da solo. Spesso lo combinerai con:

• setTime() — modifica ora/minuti/secondi dello stesso oggetto.
• setTimezone() — converte l'oggetto in un altro fuso orario.
• date_default_timezone_set() — imposta il fuso orario predefinito per lo script.
• new DateTime / date_create() — crea l'oggetto in primo luogo.

Conclusione

DateTime::setDate() (e l'equivalente date_date_set()) è il modo pulito e orientato agli oggetti per modificare l'anno, il mese e il giorno di un oggetto DateTime preservandone l'orario e il fuso orario. Ricorda due cose: i giorni fuori range scorrono al mese successivo anziché generare un'eccezione, e il DateTime mutabile viene modificato sul posto — usa DateTimeImmutable quando hai bisogno che l'originale rimanga invariato.

Pratica