Función PHP date_date_set()

En PHP, date_date_set() y su equivalente orientado a objetos DateTime::setDate() establecen una nueva fecha (año, mes y día) en un objeto DateTime existente. La parte de tiempo del objeto no se modifica — solo cambia la fecha del calendario. Es el complemento del lado de la fecha para DateTime::setTime(), que solo cambia la hora.

Úsala cuando ya tengas un objeto DateTime y quieras moverlo a un día específico sin reconstruir el objeto desde una cadena de texto.

Sintaxis

setDate() está disponible tanto como método como función procedimental. Las dos formas hacen exactamente lo mismo:

La sintaxis para DateTime::setDate() y date_date_set()

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

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

Donde:

• $datetime es el objeto DateTime a modificar.
• $year es el nuevo año (p. ej. 2024).
• $month es el nuevo mes (1–12).
• $day es el nuevo día del mes (1–31).

El método devuelve el mismo objeto DateTime para que las llamadas puedan encadenarse. La hora, los microsegundos y la zona horaria existentes del objeto se conservan todos.

Ejemplo de uso

Establezcamos una nueva fecha en un objeto DateTime manteniendo su hora original:

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

Creamos un DateTime para 2000-01-01 12:30:00 y luego llamamos a setDate() para cambiar la fecha al 15 de julio de 2024. Como setDate() solo toca la fecha del calendario, la hora 12:30:00 se conserva. Luego usamos el método format() para imprimir el resultado:

2024-07-15 12:30:00

Estilo procedimental

Si lo prefieres (o estás leyendo código antiguo), el mismo cambio se puede escribir con date_date_set(). Toma el objeto como primer argumento:

<?php

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

Esto imprime 2024-07-15. Aquí date_create() construye el objeto — es el equivalente procedimental de new DateTime.

Los días fuera de rango se desplazan

Al igual que el resto de la API de DateTime, setDate() no valida el día contra la longitud del mes. En cambio, normaliza el valor y traslada cualquier desbordamiento al mes siguiente. Pedir el "31 de febrero" te da una fecha en marzo:

<?php

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

Esto imprime 2024-03-02: febrero de 2024 tiene 29 días, por lo que el día 31 es 2 días más allá del final del mes y cae el 2 de marzo. Este desplazamiento es conveniente para la aritmética de fechas, pero es una fuente común de errores silenciosos si esperabas una excepción. Para desplazar una fecha en una cantidad relativa, usa modify(), add() o sub().

Mutable vs. Inmutable

DateTime es mutable: setDate() cambia el objeto en su lugar y devuelve ese mismo objeto. Si el valor se comparte en otro lugar de tu código, todas las referencias verán el cambio. Para evitar mutaciones accidentales, usa DateTimeImmutable, cuyo setDate() devuelve una nueva instancia y deja el original intacto:

<?php

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

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

Esto imprime 2000-01-01 | 2024-07-15: $original no se toca, y $changed contiene la nueva fecha. Con el DateTime mutable, ambas variables apuntarían al mismo objeto modificado.

Métodos relacionados

setDate() rara vez viaja solo. A menudo lo combinarás con:

• setTime() — cambia la hora/minuto/segundo del mismo objeto.
• setTimezone() — convierte el objeto a otra zona horaria.
• date_default_timezone_set() — establece la zona horaria predeterminada para todo el script.
• new DateTime / date_create() — crea el objeto en primer lugar.

Conclusión

DateTime::setDate() (y el equivalente date_date_set()) es la forma limpia y orientada a objetos de cambiar el año, mes y día de un objeto DateTime conservando su hora y zona horaria. Recuerda dos cosas: los días fuera de rango se desplazan al mes siguiente en lugar de lanzar una excepción, y el DateTime mutable se cambia en su lugar — utiliza DateTimeImmutable cuando necesites que el original permanezca intacto.

Práctica