DOCSP-42957: DateTimeInterface in queries

docs/includes/query-builder/QueryBuilderTest.php

@@ -150,12 +150,13 @@ public function testWhereIn(): void
 
     public function testWhereDate(): void
     {
-        // begin query whereDate
+        // begin query where date
         $result = DB::connection('mongodb')
             ->table('movies')
-            ->whereDate('released', '2010-1-15')
-            ->get();
-        // end query whereDate
+            ->where('released', new UTCDateTime(
+                Carbon::create(2010, 1, 15, 0, 0, 0, 'UTC'),
+            ))->get();
+        // end query where date
 
         $this->assertInstanceOf(\Illuminate\Support\Collection::class, $result);
     }

docs/query-builder.txt

@@ -348,23 +348,26 @@ 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 ``2010, 1, 15, 0, 0, 0``, 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
 
-   Starting in {+odm-long+} v5.0, ``UTCDateTime`` BSON values in MongoDB
-   are returned as `Carbon <https://carbon.nesbot.com/docs/>`__ date
-   classes in query results. The {+odm-short+} applies the default
-   timezone when performing this conversion.
+   Starting in {+odm-long+} v5.0, `Carbon <https://carbon.nesbot.com/docs/>`__
+   objects passed as query filters, as shown in the preceding code example, 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.
 
 .. _laravel-query-builder-pattern:
 

docs/upgrade.txt

@@ -81,6 +81,14 @@ 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. For 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.