`AbstractActiveRecord::newValues()` incorrectly marks DateTimeInterface attribute as changed

[darealfive]

Description

The newValues() method fails to correctly detect changes for DateTimeType related types, e.g. DateTimeInterface respectively DateTimeImmutable.

Specifically:

• DateTimeImmutable / DateTimeInterface values are compared using strict comparison (!==), causing two instances representing the same moment to be always treated as changed (incorrectly), because two objects are never object-equal.

This affects Active Record dirty-checking and can cause unnecessary record updates and therefore subsequent problems.

---

Steps to Reproduce

1. Load an Active Record model from the database with at least one DateTime column and make sure it gets mapped to DateTimeImmutable.
2. ...either assign a new DateTimeImmutable instance with the same date/time value.
   ... or leave the value as is.
3. Call newValues() or attempt to save the model.Expected:
   The attribute should not be marked as dirty.

Actual:
The attribute is considered as changed (dirty) incorrectly.

---

Expected Behavior

• DateTimeInterface values should be compared using loose comparison (==) to compare actual date/time values rather than object identity.

---

Proposed Fix

/**
 * Returns the property values that have been modified since they're loaded or saved most recently.
 *
 * The comparison of new DateTimeInterface objects with old values uses `==`.
 * The comparison of all other values uses `===`.
 *
 * @param array|null $propertyNames The names of the properties whose values may be returned if they're changed
 *                                  recently. If `null`, {@see propertyNames()} will be used.
 *
 * @return array The changed property values (name-value pairs).
 *
 * @psalm-return array<string, mixed>
 */
#[Override]
public function newValues(array|null $propertyNames = null): array
{
    $values    = $this->propertyValues($propertyNames);
    $oldValues = $this->oldValues();
    if ($oldValues === []) {
        return $values;
    }

    $result = array_diff_key($values, $oldValues);
    foreach (array_diff_key($values, $result) as $name => $value) {
        if ($value instanceof DateTimeInterface) {
            if ($value != $oldValues[$name]) {
                $result[$name] = $value;
            }
        } else {
            if ($value !== $oldValues[$name]) {
                $result[$name] = $value;
            }
        }
    }

    return $result;
}

---

Notes

I think this behavior avoids false positives when using immutable date/time objects.
You may update \Yiisoft\ActiveRecord\ActiveRecordInterface::newValues documentation with the provided one and leave the actual implementation documentation empty (as it is currently).

Package version

1.0.0

PHP version

PHP 8.4.15 (cli)

[darealfive]

Regarding performance: If you do not want to use "instanceof" as the first check, you may alternatively check all primitive values explicitly to be compared with !== and only after that use the !=.
E.g.:

if (is_scalar($value) || $value === null || is_array($value)) {
  if ($value !== $oldValues[$name]) {
    $result[$name] = $value;
  }
}
else {
  if ($value != $oldValues[$name]) {
    $result[$name] = $value;
  }
}

[vjik]

Currently, we can apply the fix suggested in this topic.

But the ability to set a custom comparator should be added in the future, because AR may use custom objects as values.

[samdark]

@darealfive do you have some time for a pull request?

[Tigrov]

I think this is not correct.

What if the date time object has a different time zone?

new DateTimeImmutable('2025-12-12 09:00:00+10') == new DateTimeImmutable('2025-12-12 08:00:00+9')

[vjik]

I think this is not correct.

What if the date time object has a different time zone?

new DateTimeImmutable('2025-12-12 09:00:00+10') == new DateTimeImmutable('2025-12-12 08:00:00+9')

Although these objects represent the same timestamp, some DB columns store the timezone, and in this case these objects are different.

[darealfive]

I think this is not correct.

What if the date time object has a different time zone?

new DateTimeImmutable('2025-12-12 09:00:00+10') == new DateTimeImmutable('2025-12-12 08:00:00+9')

Hmm.. These two objects represent the same moment in time, that would be a problem indeed if we would simply compare with != respectively ==.

A possible fix might be to format those objects via ->format('c'):

(new DateTimeImmutable('2025-12-12 09:00:00+10'))->format('c') == (new DateTimeImmutable('2025-12-12 08:00:00+9'))->format('c');
// Compares the original datetime strings incl. timezone: 2025-12-12T09:00:00+10:00 == 2025-12-12 08:00:00+9 is FALSE

@samdark I have time for a pull request—I might wait a little longer until the discussion about the time zone has been clarified :)

[samdark]

Sounds like the check should depend on the database type, i.e., if the timezone isn't stored in any way, then compare if that's the same moment in time. If the timezone is stored, then compare the timezone as well.

[vjik]

Sounds like the check should depend on the database type

Database column type

[darealfive]

Sounds like the check should depend on the database type, i.e., if the timezone isn't stored in any way, then compare if that's the same moment in time. If the timezone is stored, then compare the timezone as well.

TLDR

Always use ->format('c') because application will either implicitly knows or explicitly writes the timezone.

Long story

I think the user should handle these cases explicitly. You already give us the option to assign a timezone if a column does not store one.
\Yiisoft\Db\Schema\Column\DateTimeColumn::$dbTimezone
\Yiisoft\Db\Schema\Column\DateTimeColumn::$phpTimezone

The user should either explicitly set a timezone for the DB column, or "Use empty string to disable time zone conversion" as specified in \Yiisoft\Db\Schema\Column\DateTimeColumn::$dbTimezone

A programmer should always be aware that a datetime column is either UTC or must be combined with a timezone to obtain the exact moment in time.
This means that there is always a timezone and we should compare it via ->format('c')

But maybe I'm wrong here.
Do you think there are cases where the time zone should be ignored when comparing DateTime objects?

[Tigrov]

A possible fix might be to format those objects via ->format('c'):

It also does not work:
(new DateTimeImmutable('2025-12-12 09:00:00.123456+10'))->format('c') == (new DateTimeImmutable('2025-12-12 09:00:00+10'))->format('c')

I think the correct approach is when the user can override this method for his own needs.

public function newValues(array|null $propertyNames = null): array
{
    ...
}

[darealfive]

A possible fix might be to format those objects via ->format('c'):

It also does not work: (new DateTimeImmutable('2025-12-12 09:00:00.123456+10'))->format('c') == (new DateTimeImmutable('2025-12-12 09:00:00+10'))->format('c')

I think the correct approach is when the user can override this method for his own needs.

public function newValues(array|null $propertyNames = null): array
{
...
}

You are right - Y-m-d\TH:i:s.uP should be used instead.

echo new DateTimeImmutable('2025-12-12 09:00:00.123456+10')->format('c');
// ... outputs => "2025-12-12T09:00:00+10:00"

echo new DateTimeImmutable('2025-12-12 09:00:00.123456+10')->format('Y-m-d\TH:i:s.uP');
// ... outputs => "2025-12-12T09:00:00.123456+10:00"

... which would enable us to also compare microseconds.

But nevertheless,

I think the correct approach is when the user can override this method for his own needs.

YES. But for know we may focus on a more solid default implementation, right?
I will create a pull request during this weekend.