Función PHP date_time_set()

En PHP, el método DateTime::setTime() se utiliza para establecer una nueva hora en un objeto DateTime dado. Este método forma parte de la clase DateTime de PHP y puede emplearse para actualizar la parte horaria de un objeto de fecha/hora con un nuevo valor.

Sintaxis

La sintaxis del método DateTime::setTime() es la siguiente:

Sintaxis del método DateTime::setTime()

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

Donde:

• $datetime es el objeto DateTime que se desea modificar.
• $hour es el nuevo valor de la hora (0–23).
• $minute es el nuevo valor de los minutos (0–59).
• $second es el nuevo valor de los segundos (0–59, opcional, el valor predeterminado es 0).
• $microsecond es el nuevo valor de los microsegundos (0–999999, opcional, el valor predeterminado es 0).

Nota: La zona horaria del objeto DateTime se conserva durante esta operación. El método modifica el objeto en su lugar. Si los valores proporcionados superan sus rangos válidos, PHP los normaliza automáticamente (por ejemplo, la hora 25 pasa al día siguiente) en lugar de lanzar una excepción.

Ejemplo de uso

Veamos un ejemplo de cómo utilizar el método DateTime::setTime():

Ejemplo del método PHP DateTime::setTime()

En este ejemplo, primero creamos un nuevo objeto DateTime con la fecha y hora establecidas en '2000-01-01 12:00:00'. A continuación, usamos el método setTime() para fijar la hora en 14 y los minutos en 30. Finalmente, usamos el método format() para mostrar la fecha y hora modificadas en el formato 'Y-m-d H:i:s'. La salida es:

2000-01-01 14:30:00

Como no hemos pasado $second ni $microsecond, ambos toman el valor predeterminado 0, por lo que los segundos se reinician aunque la hora original ya tenía :00 segundos.

Establecer segundos y microsegundos

Puedes pasar los cuatro argumentos para controlar la hora hasta el microsegundo. El componente de microsegundos solo aparece en la salida si la cadena de formato incluye 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');

Esto imprime 2000-01-01 14:30:15.500000.

Los valores fuera de rango se normalizan

setTime() no lanza una excepción cuando los valores están fuera del rango válido; los normaliza y traslada el desbordamiento a la fecha. Establecer la hora en 25 adelanta la fecha un día:

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

Esto imprime 2000-01-02 01:00:00: la hora 25 se convierte en 01:00 del día siguiente. Esto es útil para operaciones aritméticas (por ejemplo, "sumar 5 horas" pasando $hour + 5), pero puede ser fuente de errores silenciosos si se esperaba una validación. Para cambiar la fecha directamente, usa setDate(), o modify() para desplazamientos relativos.

Comparación de DateTime::setTime() con otras funciones

El método DateTime::setTime() es el enfoque orientado a objetos estándar en PHP para modificar la hora. A diferencia de las funciones de fecha procedimentales, que devuelven cadenas nuevas o requieren un análisis complejo, setTime() modifica directamente el objeto DateTime en su lugar, garantizando la seguridad de tipos y un comportamiento coherente.

Esto contrasta con DateTimeImmutable::setTime(), que devuelve una nueva instancia y deja la original sin cambios:

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

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

Esto imprime 12:00 | 08:00: $original no cambia y $changed contiene la nueva hora. Con el DateTime mutable, la llamada devuelve el mismo objeto modificado, por lo que $original y $changed apuntarían al mismo objeto con la hora 08:00. Prefiere DateTimeImmutable cuando un valor se comparte o se pasa entre funciones, para evitar mutaciones accidentales.

Métodos relacionados que pueden complementar a setTime(): setDate() para cambiar el año/mes/día, setTimezone() para convertir a otra zona horaria, y date_default_timezone_set() para establecer el huso horario predeterminado del script. Para crear el objeto desde cero, consulta new DateTime.

Conclusión

El método DateTime::setTime() es una herramienta útil para manipular fechas y horas en PHP. Al ofrecer una manera sencilla de actualizar la parte horaria de un objeto DateTime, proporciona un enfoque cómodo y fiable para la manipulación de fechas y horas. Para el manejo inmutable de fechas, usa DateTimeImmutable::setTime(), que devuelve una nueva instancia en lugar de modificar la original.

Práctica