diff --git a/docs/includes/query-builder/QueryBuilderTest.php b/docs/includes/query-builder/QueryBuilderTest.php index 02d15cc48..38f001a33 100644 --- a/docs/includes/query-builder/QueryBuilderTest.php +++ b/docs/includes/query-builder/QueryBuilderTest.php @@ -4,6 +4,7 @@ namespace App\Http\Controllers; +use Carbon\Carbon; use Illuminate\Database\Query\Builder; use Illuminate\Pagination\AbstractPaginator; use Illuminate\Support\Facades\DB; @@ -148,14 +149,26 @@ public function testWhereIn(): void $this->assertInstanceOf(\Illuminate\Support\Collection::class, $result); } + public function testWhereCarbon(): void + { + // begin query where date + $result = DB::connection('mongodb') + ->table('movies') + ->where('released', Carbon::create(2010, 1, 15)) + ->get(); + // end query where date + + $this->assertInstanceOf(\Illuminate\Support\Collection::class, $result); + } + public function testWhereDate(): void { - // begin query whereDate + // begin query whereDate string $result = DB::connection('mongodb') ->table('movies') ->whereDate('released', '2010-1-15') ->get(); - // end query whereDate + // end query whereDate string $this->assertInstanceOf(\Illuminate\Support\Collection::class, $result); } diff --git a/docs/query-builder.txt b/docs/query-builder.txt index 9b1fe65f9..5be6b05b4 100644 --- a/docs/query-builder.txt +++ b/docs/query-builder.txt @@ -348,23 +348,38 @@ query builder method to retrieve documents from the Match Dates Example ^^^^^^^^^^^^^^^^^^^ -The following example shows how to use the ``whereDate()`` +The following example shows how to use the ``where()`` query builder method to retrieve documents from the -``movies`` collection that match the specified date of -``2010-1-15`` in the ``released`` field: +``movies`` collection in which the ``released`` value +is January 15, 2010, specified in a ``Carbon`` object: .. literalinclude:: /includes/query-builder/QueryBuilderTest.php :language: php :dedent: - :start-after: begin query whereDate - :end-before: end query whereDate + :start-after: begin query where date + :end-before: end query where date -.. note:: Date Query Result Type +.. note:: Date Query Filter and Result Type - Starting in {+odm-long+} v5.0, ``UTCDateTime`` BSON values in MongoDB - are returned as `Carbon `__ date - classes in query results. The {+odm-short+} applies the default - timezone when performing this conversion. + Starting in {+odm-long+} v5.0, `Carbon `__ + objects passed as query filters, as shown in the preceding code, are + converted to ``UTCDateTime`` BSON values. + + In query results, ``UTCDateTime`` BSON values in MongoDB are returned as ``Carbon`` + objects. The {+odm-short+} applies the default timezone when performing + this conversion. + +If you want to represent a date as a string in your query filter +rather than as a ``Carbon`` object, use the ``whereDate()`` query +builder method. The following example retrieves documents from +the ``movies`` collection in which the ``released`` value +is January 15, 2010 and specifies the date as a string: + +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin query whereDate string + :end-before: end query whereDate string .. _laravel-query-builder-pattern: diff --git a/docs/upgrade.txt b/docs/upgrade.txt index 4d7dca0d8..e6f112fd4 100644 --- a/docs/upgrade.txt +++ b/docs/upgrade.txt @@ -81,6 +81,16 @@ This library version introduces the following breaking changes: use the default ``Illuminate\Queue\Failed\DatabaseFailedJobProvider`` class and specify a connection to MongoDB. +- When using a ``DateTimeInterface`` object, including ``Carbon``, in a query, + the library converts the ``DateTimeInterface`` to a ``MongoDB\BSON\UTCDateTime`` + object. This conversion applies to ``DateTimeInterface`` objects passed as query + filters to the ``where()`` method or as data passed to the ``insert()`` and + ``update()`` methods. + + To view an example that passes a ``Carbon`` object to the + ``DB::where()`` method, see the :ref:`laravel-query-builder-wheredate` + section of the Query Builder guide. + - In query results, the library converts BSON ``UTCDateTime`` objects to ``Carbon`` date classes, applying the default timezone.