DOCSP-42957: DateTimeInterface in queries (#3140)

Adds information & a code example about automatic conversion from DateTimeInterface to UTCDateTime in queries.

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);
     }

docs/query-builder.txt

@@ -353,23 +353,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 <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.
+
+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:
 

docs/upgrade.txt

@@ -101,6 +101,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.