PHPORM-234 Convert dates in DB Query results

Author: GromNaN

Diff for: CHANGELOG.md

@@ -6,6 +6,7 @@ All notable changes to this project will be documented in this file.
 * Remove support for Laravel 10 by @GromNaN in [#3123](https://github.com/mongodb/laravel-mongodb/pull/3123)
 * **BREAKING CHANGE** Use `id` as an alias for `_id` in commands and queries for compatibility with Eloquent packages by @GromNaN in [#3040](https://github.com/mongodb/laravel-mongodb/pull/3040)
 * **BREAKING CHANGE** Make Query\Builder return objects instead of array to match Laravel behavior by @GromNaN in [#3107](https://github.com/mongodb/laravel-mongodb/pull/3107)
+* **BREAKING CHANGE** In DB query results, convert BSON `UTCDateTime` objects into `Carbon` date with the default timezone by @GromNaN in [#3119](https://github.com/mongodb/laravel-mongodb/pull/3119)
 * Remove `MongoFailedJobProvider`, replaced by Laravel `DatabaseFailedJobProvider` by @GromNaN in [#3122](https://github.com/mongodb/laravel-mongodb/pull/3122)
 
 ## [4.8.0] - 2024-08-27

Diff for: src/Eloquent/DocumentModel.php

@@ -5,12 +5,14 @@
 namespace MongoDB\Laravel\Eloquent;
 
 use BackedEnum;
+use Carbon\Carbon;
 use Carbon\CarbonInterface;
 use DateTimeInterface;
 use DateTimeZone;
 use Illuminate\Contracts\Queue\QueueableCollection;
 use Illuminate\Contracts\Queue\QueueableEntity;
 use Illuminate\Contracts\Support\Arrayable;
+use Illuminate\Database\Eloquent\Concerns\HasAttributes;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\Relation;
 use Illuminate\Support\Arr;
@@ -97,8 +99,14 @@ public function getQualifiedKeyName()
         return $this->getKeyName();
     }
 
-    /** @inheritdoc */
-    public function fromDateTime($value)
+    /**
+     * Convert a DateTime to a storable UTCDateTime.
+     *
+     * @see HasAttributes::fromDateTime()
+     *
+     * @param  mixed $value
+     */
+    public function fromDateTime($value): UTCDateTime
     {
         // If the value is already a UTCDateTime instance, we don't need to parse it.
         if ($value instanceof UTCDateTime) {
@@ -113,8 +121,14 @@ public function fromDateTime($value)
         return new UTCDateTime($value);
     }
 
-    /** @inheritdoc */
-    protected function asDateTime($value)
+    /**
+     * Return a timestamp as DateTime object.
+     *
+     * @see HasAttributes::asDateTime()
+     *
+     * @param  mixed $value
+     */
+    protected function asDateTime($value): Carbon
     {
         // Convert UTCDateTime instances to Carbon.
         if ($value instanceof UTCDateTime) {

Diff for: src/Query/Builder.php

@@ -14,6 +14,7 @@
 use Illuminate\Support\Arr;
 use Illuminate\Support\Carbon;
 use Illuminate\Support\Collection;
+use Illuminate\Support\Facades\Date;
 use Illuminate\Support\LazyCollection;
 use InvalidArgumentException;
 use LogicException;
@@ -1660,7 +1661,9 @@ private function aliasIdForResult(array|object $values): array|object
             }
 
             foreach ($values as $key => $value) {
-                if (is_array($value) || is_object($value)) {
+                if ($value instanceof UTCDateTime) {
+                    $values[$key] = Date::instance($value->toDateTime());
+                } elseif (is_array($value) || $value instanceof stdClass) {
                     $values[$key] = $this->aliasIdForResult($value);
                 }
             }
@@ -1673,7 +1676,9 @@ private function aliasIdForResult(array|object $values): array|object
             }
 
             foreach (get_object_vars($values) as $key => $value) {
-                if (is_array($value) || is_object($value)) {
+                if ($value instanceof UTCDateTime) {
+                    $values->{$key} = Date::instance($value->toDateTime());
+                } elseif (is_array($value) || $value instanceof stdClass) {
                     $values->{$key} = $this->aliasIdForResult($value);
                 }
             }

Diff for: tests/QueryBuilderTest.php

@@ -4,6 +4,7 @@
 
 namespace MongoDB\Laravel\Tests;
 
+use Carbon\Carbon;
 use DateTime;
 use DateTimeImmutable;
 use Illuminate\Support\Facades\Date;
@@ -33,7 +34,6 @@
 use function md5;
 use function sort;
 use function strlen;
-use function strtotime;
 
 class QueryBuilderTest extends TestCase
 {
@@ -676,27 +676,32 @@ public function testUpdateSubdocument()
     public function testDates()
     {
         DB::table('users')->insert([
-            ['name' => 'John Doe', 'birthday' => new UTCDateTime(Date::parse('1980-01-01 00:00:00'))],
-            ['name' => 'Robert Roe', 'birthday' => new UTCDateTime(Date::parse('1982-01-01 00:00:00'))],
-            ['name' => 'Mark Moe', 'birthday' => new UTCDateTime(Date::parse('1983-01-01 00:00:00.1'))],
-            ['name' => 'Frank White', 'birthday' => new UTCDateTime(Date::parse('1960-01-01 12:12:12.1'))],
+            ['name' => 'John Doe', 'birthday' => Date::parse('1980-01-01 00:00:00')],
+            ['name' => 'Robert Roe', 'birthday' => Date::parse('1982-01-01 00:00:00')],
+            ['name' => 'Mark Moe', 'birthday' => Date::parse('1983-01-01 00:00:00.1')],
+            ['name' => 'Frank White', 'birthday' => Date::parse('1975-01-01 12:12:12.1')],
         ]);
 
         $user = DB::table('users')
-            ->where('birthday', new UTCDateTime(Date::parse('1980-01-01 00:00:00')))
+            ->where('birthday', Date::parse('1980-01-01 00:00:00'))
             ->first();
         $this->assertEquals('John Doe', $user->name);
 
         $user = DB::table('users')
-            ->where('birthday', new UTCDateTime(Date::parse('1960-01-01 12:12:12.1')))
+            ->where('birthday', Date::parse('1975-01-01 12:12:12.1'))
             ->first();
+
         $this->assertEquals('Frank White', $user->name);
+        $this->assertInstanceOf(Carbon::class, $user->birthday);
+        $this->assertSame('1975-01-01 12:12:12.100000', $user->birthday->format('Y-m-d H:i:s.u'));
 
         $user = DB::table('users')->where('birthday', '=', new DateTime('1980-01-01 00:00:00'))->first();
         $this->assertEquals('John Doe', $user->name);
+        $this->assertInstanceOf(Carbon::class, $user->birthday);
+        $this->assertSame('1980-01-01 00:00:00.000000', $user->birthday->format('Y-m-d H:i:s.u'));
 
-        $start = new UTCDateTime(1000 * strtotime('1950-01-01 00:00:00'));
-        $stop  = new UTCDateTime(1000 * strtotime('1981-01-01 00:00:00'));
+        $start = new UTCDateTime(new DateTime('1950-01-01 00:00:00'));
+        $stop  = new UTCDateTime(new DateTime('1981-01-01 00:00:00'));
 
         $users = DB::table('users')->whereBetween('birthday', [$start, $stop])->get();
         $this->assertCount(2, $users);