Função PHP date_time_set()

Em PHP, o método DateTime::setTime() é usado para definir um novo horário para um objeto DateTime. Esse método faz parte da classe DateTime do PHP e pode ser utilizado para definir a parte de horário de um objeto de data/hora com um novo valor.

Sintaxe

A sintaxe do método DateTime::setTime() é a seguinte:

Sintaxe do método DateTime::setTime()

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

Onde:

• $datetime é o objeto DateTime a ser modificado.
• $hour é o novo valor de hora (0–23).
• $minute é o novo valor de minuto (0–59).
• $second é o novo valor de segundo (0–59, opcional, padrão é 0).
• $microsecond é o novo valor de microssegundo (0–999999, opcional, padrão é 0).

Nota: O fuso horário do objeto DateTime é preservado durante essa operação. O método modifica o objeto diretamente. Se os valores fornecidos excederem seus intervalos válidos, o PHP os normaliza automaticamente (por exemplo, a hora 25 avança para o dia seguinte) em vez de lançar uma exceção.

Exemplo de Uso

Vejamos um exemplo de como usar o método DateTime::setTime():

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

Neste exemplo, primeiro criamos um novo objeto DateTime com a data e hora definidas como '2000-01-01 12:00:00'. Em seguida, usamos o método setTime() para definir a hora como 14 e o minuto como 30. Por fim, usamos o método format() para exibir a data e hora modificadas no formato 'Y-m-d H:i:s'. A saída é:

2000-01-01 14:30:00

Como não passamos $second nem $microsecond, ambos assumem o padrão 0, portanto os segundos são redefinidos mesmo que o horário original já tivesse :00 segundos.

Definindo Segundos e Microssegundos

Você pode passar todos os quatro argumentos para controlar o horário até o microssegundo. O componente de microssegundo só aparece na saída se a string de formato incluir 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');

Isso exibe 2000-01-01 14:30:15.500000.

Valores Fora do Intervalo São Normalizados

setTime() não lança exceção para valores fora do intervalo válido — ele os normaliza e transfere o excesso para a data. Definir a hora como 25 avança a data um dia:

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

Isso exibe 2000-01-02 01:00:00 — a hora 25 vira 01:00 no dia seguinte. Isso é útil para aritmética (por exemplo, "adicionar 5 horas" passando $hour + 5), mas pode ser uma fonte de erros silenciosos se você esperava validação. Para alterar a data diretamente, use setDate() ou modify() para deslocamentos relativos.

Como DateTime::setTime() se Compara a Outras Funções

O método DateTime::setTime() é a abordagem orientada a objetos padrão em PHP para modificar horários. Ao contrário das funções de data procedurais, que retornam novas strings ou exigem análise complexa, setTime() modifica o objeto DateTime diretamente, garantindo segurança de tipos e comportamento consistente.

Isso contrasta com DateTimeImmutable::setTime(), que retorna uma nova instância e deixa o original intacto:

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

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

Isso exibe 12:00 | 08:00: $original permanece inalterado e $changed contém o novo horário. Com o DateTime mutável, a chamada retorna o mesmo objeto modificado, então $original e $changed apontariam para um único objeto com horário 08:00. Prefira DateTimeImmutable quando um valor é compartilhado ou passado adiante, para evitar mutações acidentais.

Métodos relacionados que você pode usar junto com setTime(): setDate() para alterar ano/mês/dia, setTimezone() para converter para outro fuso horário, e date_default_timezone_set() para definir o padrão global do script. Para criar o objeto inicialmente, veja new DateTime.

Conclusão

O método DateTime::setTime() é uma ferramenta útil para manipular datas e horários em PHP. Ao oferecer uma maneira direta de atualizar a parte de horário de um objeto DateTime, ele fornece uma abordagem conveniente e confiável para manipulação de data/hora. Para tratamento de datas imutável, use DateTimeImmutable::setTime(), que retorna uma nova instância em vez de modificar a original.

Prática