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.