(PHP 5 >= 5.3.0, PHP 7, PHP 8)
DateTimeInterface::diff -- DateTimeImmutable::diff -- DateTime::diff -- date_diff — Retorna a diferença entre dois objetos DateTime
Estilo orientado a objetos
$targetObject
, bool $absolute
= false
): DateInterval$targetObject
, bool $absolute
= false
): DateIntervalEstilo procedural
$baseObject
, DateTimeInterface $targetObject
, bool $absolute
= false
): DateIntervalRetorna a diferença entre dois objetos que implementam a classe DateTimeInterface.
datetime
A data a ser comparada.
absolute
O intervalo deve ser forçado como positivo?
O objeto DateInterval representa a diferença entre as duas datas.
O parâmetro absolute
afeta somente a
propriedade invert
de um
objeto DateInterval.
O valor de retorno representa mais especificamente o intervalo de tempo a
ser aplicado ao objeto original ($this
ou
$originObject
) para se chegar ao
$targetObject
. Este processo nem sempre é
reversível.
O método leva em conta mudanças de horário de verão, e por isso pode
retornar um intervalo de 24 horas e 30 minutos
, por exemplo.
Se a intenção for fazer cálculos com horários absolutos, será necessário converter
tanto $this
/$baseObject
quanto
$targetObject
para UTC primeiro.
Exemplo #1 Exemplo do método DateTimeImmutable::diff()
Estilo orientado a objetos
<?php
$origin = new DateTime('2009-10-11');
$target = new DateTime('2009-10-13');
$interval = $origin->diff($target);
echo $interval->format('%R%a dias');
?>
Estilo procedural
<?php
$origin = date_create('2009-10-11');
$target = date_create('2009-10-13');
$interval = date_diff($origin, $target);
echo $interval->format('%R%a dias');
?>
Os exemplos acima produzirão:
+2 dias
Exemplo #2 DateTimeInterface::diff() durante mudança de horário de verão
<?php
$originalTime = new DateTimeImmutable("2021-10-30 09:00:00 Europe/London");
$targetTime = new DateTimeImmutable("2021-10-31 08:30:00 Europe/London");
$interval = $originalTime->diff($targetTime);
echo $interval->format("%H:%I:%S (Dias inteiros: %a)"), "\n";
?>
O exemplo acima produzirá:
24:30:00 (Dias inteiros: 0)
Exemplo #3 Intervalo do método DateTimeInterface::diff()
O valor que o método retorna é a quantidade exata de tempo para sair de
$this
e chegar em $targetObject
.
Comparando 1º de janeiro com 31 de dezembro retorna portanto 364, e não 365
dias (para anos não bissextos).
<?php
$originalTime = new DateTimeImmutable("2023-01-01 UTC");
$targetTime = new DateTimeImmutable("2023-12-31 UTC");
$interval = $originalTime->diff($targetTime);
echo "Dias inteiros: ", $interval->format("%a"), "\n";
?>
O exemplo acima produzirá:
Dias inteiros: 364
Exemplo #4 Comparação entre objetos DateTime
Nota:
Objetos das classes DateTimeImmutable e DateTime podem ser comparados utilizando os operadores de comparação.
<?php
$date1 = new DateTime("now");
$date2 = new DateTime("tomorrow");
var_dump($date1 == $date2);
var_dump($date1 < $date2);
var_dump($date1 > $date2);
?>
O exemplo acima produzirá:
bool(false) bool(true) bool(false)