DOCSP-42957: DateTimeInterface 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

@@ -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 <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

@@ -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.