Função PHP date_date_set()

Em PHP, date_date_set() e seu equivalente orientado a objetos DateTime::setDate() definem uma nova data (ano, mês e dia) em um objeto DateTime existente. A parte de hora do objeto permanece intacta — apenas a data do calendário muda. Este é o contraparte do lado da data para DateTime::setTime(), que altera apenas o horário.

Use-o quando você já tem um objeto DateTime e deseja movê-lo para um dia específico sem reconstruir o objeto a partir de uma string.

Sintaxe

setDate() está disponível tanto como método quanto como função procedural. As duas formas fazem exatamente a mesma coisa:

A sintaxe de DateTime::setDate() e date_date_set()

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

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

Onde:

• $datetime é o objeto DateTime a ser modificado.
• $year é o novo ano (ex.: 2024).
• $month é o novo mês (1–12).
• $day é o novo dia do mês (1–31).

O método retorna o mesmo objeto DateTime, permitindo encadeamento de chamadas. O horário, os microssegundos e o fuso horário existentes do objeto são todos preservados.

Exemplo de Uso

Vamos definir uma nova data em um objeto DateTime mantendo seu horário original:

Exemplo do método PHP DateTime::setDate()

Criamos um DateTime para 2000-01-01 12:30:00 e, em seguida, chamamos setDate() para alterar a data para 15 de julho de 2024. Como setDate() afeta apenas a data do calendário, o horário 12:30:00 é preservado. Em seguida, usamos o método format() para imprimir o resultado:

2024-07-15 12:30:00

Estilo Procedural

Se preferir (ou estiver lendo código mais antigo), a mesma alteração pode ser escrita com date_date_set(). Ele recebe o objeto como primeiro argumento:

<?php

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

Isso imprime 2024-07-15. Aqui, date_create() constrói o objeto — é o equivalente procedural de new DateTime.

Dias Fora do Intervalo São Normalizados

Assim como o restante da API DateTime, setDate() não valida o dia em relação ao comprimento do mês. Em vez disso, normaliza o valor e transfere qualquer excedente para o mês seguinte. Pedir "31 de fevereiro" resulta em uma data em março:

<?php

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

Isso imprime 2024-03-02: fevereiro de 2024 tem 29 dias, então o 31º fica 2 dias além do fim do mês e cai em 2 de março. Esse comportamento de transbordo é conveniente para aritmética de datas, mas é uma fonte comum de bugs silenciosos se você esperava uma exceção. Para deslocar uma data por um valor relativo, use modify(), add() ou sub().

Mutável vs. Imutável

DateTime é mutável: setDate() altera o objeto no lugar e retorna esse mesmo objeto. Se o valor for compartilhado em outro lugar do seu código, todas as referências verão a mudança. Para evitar mutações acidentais, use DateTimeImmutable, cujo setDate() retorna uma nova instância e deixa o 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');

Isso imprime 2000-01-01 | 2024-07-15: $original permanece inalterado e $changed contém a nova data. Com o DateTime mutável, ambas as variáveis apontariam para o mesmo objeto modificado.

Métodos Relacionados

setDate() raramente é usado sozinho. Frequentemente é combinado com:

• setTime() — alterar a hora/minuto/segundo do mesmo objeto.
• setTimezone() — converter o objeto para outro fuso horário.
• date_default_timezone_set() — definir o fuso horário padrão do script.
• new DateTime / date_create() — criar o objeto em primeiro lugar.

Conclusão

DateTime::setDate() (e o equivalente date_date_set()) é a maneira limpa e orientada a objetos de alterar o ano, mês e dia de um objeto DateTime enquanto preserva seu horário e fuso horário. Lembre-se de dois pontos: dias fora do intervalo são normalizados para o mês seguinte em vez de lançar uma exceção, e o DateTime mutável é alterado no lugar — use DateTimeImmutable quando precisar que o original permaneça intacto.

Prática