DOCSP-42957: DateTimeInterface in queries

docs/includes/query-builder/QueryBuilderTest.php

@@ -150,12 +150,12 @@ 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')
+ ->where('released', Carbon::create(2010, 1, 15, 0, 0, 0, 'UTC'))
  ->get();
- // end query whereDate
+ // 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
+.. note:: Date Query Filter and 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, 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,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. 
+
+ 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.