fix: convert DateTimeInterface objects to strings in Entity::toRawArray

[gr8man]

Description
Supersedes #10207. Fixes #8302.

Entity::toRawArray() was returning Time objects instead of primitive strings for date fields. This PR fixes it by converting all DateTimeInterface objects to strings in non-recursive mode.

Unlike the original PR (#10207), this version safely handles native PHP DateTime objects to prevent Fatal Errors (Object of class DateTime could not be converted to string), by falling back to $value->format('Y-m-d H:i:s') if __toString() is not implemented.

The conversion only applies to non-recursive calls ($recursive = false). The recursive mode preserves Time objects, which are then handled by BaseModel::timeToString() in the non-cast path and by DataConverter::toDataSource() in the cast path — so model saving/casting is unaffected.

Changes:

• Safely stringify DateTimeInterface objects in Entity::toRawArray() (non-recursive only)
• Updated DatetimeCast::set() to accept strings and any DateTimeInterface for round-trip compatibility
• Added test cases: basic conversion, non-recursive vs recursive, nested entities, mixed attributes

Checklist:

• Securely signed commits
• Component(s) with PHPDoc blocks, only if necessary or adds value (without duplication)
• Unit testing, with >80% coverage
• User guide updated
• [] Conforms to style guide

[michalsn]

This change affects all date-time attributes, not only Entity date fields, and will likely break model casting.

[neznaika0]

I agree, I do not know how to describe it.
What kind of result should we get? After all, DataConveter/DataCaster does not prohibit having a Time object in its raw form. Hard conversion to a string is incorrect.

[gr8man]

Thank you for the review @michalsn. I've traced through all code paths where toRawArray() is consumed:

• Non-cast save path (BaseModel::objectToArray): calls toRawArray() with $recursive = true, which skips the DateTime conversion — timeToString() handles it afterward. No change in behavior ✅
• Cast save path (DataConverter::extract): toRawArray() output goes through toDataSource(), which applies the proper 'set' cast on every field. The updated DatetimeCast::set() already accepts strings, so the round-trip is safe ✅
• Direct user call ($entity->toRawArray()): this is the actual fix for Bug: Entity::toRawArray() may return Time object #8302 — now returns strings instead of Time objects ✅

Model casting is not affected because the conversion layer (toDataSource / timeToString) sits between toRawArray() and the database in both paths. The change only affects user-facing non-recursive calls, which is exactly what the issue reports.

[michalsn]

As I said, it breaks model casting.

public function testExtractEntityWithTimestampCast(): void
{
    $converter = $this->createDataConverter([
        'updated_at' => 'timestamp',
    ]);

    $entity = new class extends Entity {
        protected $dates = [];
    };
    $entity->injectRawData([
        'updated_at' => Time::createFromTimestamp(1_784_092_299),
    ]);

    $data = $converter->extract($entity);

    $this->assertSame(1_784_092_299, $data['updated_at']);
}

public function testExtractEntityPreservesMicrosecondsWithDatetimeCast(): void
{
    $converter = $this->createDataConverter(
        ['updated_at' => 'datetime[us]'],
        [],
        db_connect(),
    );

    $entity = new class extends Entity {
        protected $dates = [];
    };
    $entity->injectRawData([
        'updated_at' => Time::createFromFormat('Y-m-d H:i:s.u', '2026-07-15 00:00:01.123456'),
    ]);

    $data = $converter->extract($entity);

    $this->assertSame('2026-07-15 00:00:01.123456', $data['updated_at']);
}

I don't believe it can be fixed safely in v4 without introducing BC breaks. It may need to be addressed as part of the Entity redesign in v5.

[michalsn]

Now relative values such as "tomorrow" are accepted, which broadens the caster's behavior beyond this fix.

[michalsn]

I still don't think this approach is safe to merge. Timestamps can lose timezone information and therefore represent a different instant, while changes to the built-in casters do not protect custom Model casters expecting DateTimeInterface. Accepting strings through Time::parse() also permits relative values such as tomorrow. More fundamentally, converting typed values to strings and then parsing them again during persistence is lossy and fragile. These are consequences of the approach rather than isolated bugs, so I'm not convinced this can be made BC-safe in v4 by adding more special cases.

[gr8man]

Thank you for the review and the detailed explanation. I completely agree with your assessment — attempting to fix this BC break by adding more special cases and relying on lossy string conversions during persistence is indeed fragile and too risky.

Since there is no clean way to make this BC-safe in v4 without compromising the integrity of the data layer, I am closing this PR. We can accept the current behavior as the standard going forward and look forward to a more robust, non-lossy persistence architecture in v5.

Thanks again for the feedback!