Funzione PHP date_time_set()

In PHP, il metodo DateTime::setTime() viene utilizzato per impostare un nuovo orario per un dato oggetto DateTime. Questo metodo fa parte della classe PHP DateTime e può essere usato per modificare la parte temporale di un oggetto data/ora con un nuovo valore.

Sintassi

La sintassi del metodo DateTime::setTime() è la seguente:

Sintassi del metodo DateTime::setTime()

$datetime->setTime($hour, $minute, $second, $microsecond);

Dove:

• $datetime è l'oggetto DateTime da modificare.
• $hour è il nuovo valore per l'ora (0–23).
• $minute è il nuovo valore per i minuti (0–59).
• $second è il nuovo valore per i secondi (0–59, opzionale, il valore predefinito è 0).
• $microsecond è il nuovo valore per i microsecondi (0–999999, opzionale, il valore predefinito è 0).

Nota: Il fuso orario dell'oggetto DateTime viene preservato durante questa operazione. Il metodo modifica l'oggetto sul posto. Se i valori forniti superano gli intervalli validi, PHP li normalizza automaticamente (ad esempio, l'ora 25 viene spostata al giorno successivo) invece di lanciare un'eccezione.

Esempio di utilizzo

Vediamo un esempio di come usare il metodo DateTime::setTime():

Esempio del metodo PHP DateTime::setTime()

In questo esempio, creiamo prima un nuovo oggetto DateTime con data e ora impostate su '2000-01-01 12:00:00'. Utilizziamo poi il metodo setTime() per impostare l'ora a 14 e i minuti a 30. Infine, usiamo il metodo format() per visualizzare la data e l'ora modificate nel formato 'Y-m-d H:i:s'. L'output è:

2000-01-01 14:30:00

Poiché non abbiamo passato $second né $microsecond, entrambi hanno come valore predefinito 0, quindi i secondi vengono azzerati anche se l'orario originale aveva :00 secondi.

Impostare secondi e microsecondi

È possibile passare tutti e quattro gli argomenti per controllare l'orario fino al microsecondo. Il componente microsecondi appare nell'output solo se la stringa di formato include u:

<?php
$date = new DateTime('2000-01-01 12:00:00');
$date->setTime(14, 30, 15, 500000);
echo $date->format('Y-m-d H:i:s.u');

Questo stampa 2000-01-01 14:30:15.500000.

I valori fuori intervallo vengono normalizzati

setTime() non lancia eccezioni per valori al di fuori dell'intervallo valido — li normalizza e riporta l'overflow sulla data. Impostare l'ora a 25 fa avanzare la data di un giorno:

<?php
$date = new DateTime('2000-01-01 23:30:00');
$date->setTime(25, 0);
echo $date->format('Y-m-d H:i:s');

Questo stampa 2000-01-02 01:00:00 — l'ora 25 diventa 01:00 del giorno successivo. Ciò è utile per l'aritmetica (ad esempio "aggiungi 5 ore" passando $hour + 5), ma può essere fonte di bug silenziosi se ci si aspettava una validazione. Per modificare direttamente la data, usa setDate(), oppure modify() per spostamenti relativi.

Confronto tra DateTime::setTime() e altre funzioni

Il metodo DateTime::setTime() è l'approccio orientato agli oggetti standard in PHP per modificare l'orario. A differenza delle funzioni di data procedurali che restituiscono nuove stringhe o richiedono un'analisi complessa, setTime() modifica direttamente l'oggetto DateTime sul posto, garantendo la sicurezza dei tipi e un comportamento coerente.

Questo contrasta con DateTimeImmutable::setTime(), che restituisce una nuova istanza lasciando inalterato l'originale:

<?php
$original = new DateTimeImmutable('2000-01-01 12:00:00');
$changed  = $original->setTime(8, 0);

echo $original->format('H:i'), ' | ', $changed->format('H:i');

Questo stampa 12:00 | 08:00: $original rimane invariato e $changed contiene il nuovo orario. Con il DateTime mutabile, la chiamata restituisce lo stesso oggetto modificato, quindi $original e $changed punterebbero entrambi a un unico oggetto con 08:00. Preferire DateTimeImmutable quando un valore è condiviso o passato tra funzioni, per evitare mutazioni accidentali.

Metodi correlati che potresti usare insieme a setTime(): setDate() per cambiare anno/mese/giorno, setTimezone() per convertire in un altro fuso orario, e date_default_timezone_set() per impostare il fuso orario predefinito dello script. Per creare l'oggetto, vedi new DateTime.

Conclusione

Il metodo DateTime::setTime() è uno strumento utile per la manipolazione di date e orari in PHP. Fornendo un modo diretto per aggiornare la parte temporale di un oggetto DateTime, offre un approccio conveniente e affidabile per la gestione di data/ora. Per la gestione immutabile delle date, usa DateTimeImmutable::setTime(), che restituisce una nuova istanza invece di modificare l'originale.

Pratica