DateTimeInterface::diff

DateTimeImmutable::diff

DateTime::diff

date_diff

Returns the difference between two DateTime objects

&reftitle.description;

&style.oop;

public `DateInterval` `DateTimeInterface::diff` `DateTimeInterface` `targetObject` `bool` `absolute`&false; public `DateInterval` `DateTimeImmutable::diff` `DateTimeInterface` `targetObject` `bool` `absolute`&false; public `DateInterval` `DateTime::diff` `DateTimeInterface` `targetObject` `bool` `absolute`&false;

&style.procedural;

`DateInterval` `date_diff` `DateTimeInterface` `baseObject` `DateTimeInterface` `targetObject` `bool` `absolute`&false;

Returns the difference between two `DateTimeInterface` objects.

&reftitle.parameters;

`datetime`

- The date to compare to.

`absolute`

- Should the interval be forced to be positive?

&reftitle.returnvalues;

The `DateInterval` object represents the difference between the two dates.

The `absolute` parameter only affects the `invert` property of a `DateInterval` object.

The return value more specifically represents the clock-time interval to apply to the original object (`$this` or `$originObject`) to arrive at the `$targetObject`. This process is not always reversible.

The method is aware of DST changeovers, and hence can return an interval of `24 hours and 30 minutes`, as per one of the examples. If you want to calculate with absolute time, you need to convert both the `$this`/`$baseObject`, and `$targetObject` to UTC first.

&reftitle.examples;

### `DateTimeImmutable::diff` example

&style.oop;

    <?php
    $origin = new DateTimeImmutable('2009-10-11');
    $target = new DateTimeImmutable('2009-10-13');
    $interval = $origin->diff($target);
    echo $interval->format('%R%a days');
    ?>

&style.procedural;

    <?php
    $origin = date_create('2009-10-11');
    $target = date_create('2009-10-13');
    $interval = date_diff($origin, $target);
    echo $interval->format('%R%a days');
    ?>

&examples.outputs;

    +2 days

### `DateTimeInterface::diff` during DST changeover

    <?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 (Full days: %a)"), "\n";
    ?>

&example.outputs;

    24:30:00 (Full days: 0)

### `DateTimeInterface::diff` range

The value that the method returns is the exact amount of time to get from `$this` to `$targetObject`. Comparing January 1st to December 31st returns therefore 364, and not 365, days (for non-leap years).

    <?php
    $originalTime = new DateTimeImmutable("2023-01-01 UTC");
    $targetTime = new DateTimeImmutable("2023-12-31 UTC");
    $interval = $originalTime->diff($targetTime);
    echo "Full days: ", $interval->format("%a"), "\n";
    ?>

&example.outputs;

    Full days: 364

### `DateTime` object comparison

`DateTimeImmutable` and `DateTime` objects can be compared using comparison operators.

    <?php
    $date1 = new DateTime("now");
    $date2 = new DateTime("tomorrow");

    var_dump($date1 == $date2);
    var_dump($date1 < $date2);
    var_dump($date1 > $date2);
    ?>

&example.outputs;

    bool(false)
    bool(true)
    bool(false)

&reftitle.seealso;

- `DateInterval::format`
- `DateTime::add`
- `DateTime::sub`