From 4943a55520de1236bc4578f6d8dcc7a071991558 Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 6 Sep 2024 16:22:26 -0400 Subject: [PATCH 1/9] DOCSP-42957: DateTimeInterface in queries --- docs/upgrade.txt | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/upgrade.txt b/docs/upgrade.txt index 4d7dca0d8..cc4dfd30d 100644 --- a/docs/upgrade.txt +++ b/docs/upgrade.txt @@ -89,6 +89,9 @@ This library version introduces the following breaking changes: of this behavior, you cannot have two separate ``id`` and ``_id`` fields in your documents. +- When using a ``DateTimeInterface`` object in a query, the library converts + the ``DateTimeInterface`` to a ``MongoDB\BSON\UTCDateTime`` object. + .. _laravel-breaking-changes-v4.x: Version 4.x Breaking Changes From 6c274ebf2cd032475f67764acd50bd91311cdaed Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 10 Sep 2024 11:04:22 -0400 Subject: [PATCH 2/9] feedback edits --- .../query-builder/QueryBuilderTest.php | 9 ++++---- docs/query-builder.txt | 21 +++++++++++-------- docs/upgrade.txt | 11 +++++++--- 3 files changed, 25 insertions(+), 16 deletions(-) diff --git a/docs/includes/query-builder/QueryBuilderTest.php b/docs/includes/query-builder/QueryBuilderTest.php index 02d15cc48..32ad88101 100644 --- a/docs/includes/query-builder/QueryBuilderTest.php +++ b/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); } diff --git a/docs/query-builder.txt b/docs/query-builder.txt index 9b1fe65f9..f15b0092b 100644 --- a/docs/query-builder.txt +++ b/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 `__ 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 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: diff --git a/docs/upgrade.txt b/docs/upgrade.txt index cc4dfd30d..1f9cf95ae 100644 --- a/docs/upgrade.txt +++ b/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. @@ -89,9 +97,6 @@ This library version introduces the following breaking changes: of this behavior, you cannot have two separate ``id`` and ``_id`` fields in your documents. -- When using a ``DateTimeInterface`` object in a query, the library converts - the ``DateTimeInterface`` to a ``MongoDB\BSON\UTCDateTime`` object. - .. _laravel-breaking-changes-v4.x: Version 4.x Breaking Changes From 080e02951644797a0907ce0f06e85dcec2960916 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 10 Sep 2024 15:06:15 +0000 Subject: [PATCH 3/9] apply phpcbf formatting --- docs/includes/query-builder/QueryBuilderTest.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/includes/query-builder/QueryBuilderTest.php b/docs/includes/query-builder/QueryBuilderTest.php index 32ad88101..c32513368 100644 --- a/docs/includes/query-builder/QueryBuilderTest.php +++ b/docs/includes/query-builder/QueryBuilderTest.php @@ -154,7 +154,7 @@ public function testWhereDate(): void $result = DB::connection('mongodb') ->table('movies') ->where('released', new UTCDateTime( - Carbon::create(2010, 1, 15, 0, 0, 0, 'UTC') + Carbon::create(2010, 1, 15, 0, 0, 0, 'UTC'), ))->get(); // end query where date From 353ffc16acef554127999c553ef7cc7d420e4ed3 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 10 Sep 2024 11:12:40 -0400 Subject: [PATCH 4/9] edits --- docs/includes/query-builder/QueryBuilderTest.php | 5 ++--- docs/query-builder.txt | 4 ++-- docs/upgrade.txt | 4 +++- 3 files changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/includes/query-builder/QueryBuilderTest.php b/docs/includes/query-builder/QueryBuilderTest.php index 32ad88101..c59c33a8d 100644 --- a/docs/includes/query-builder/QueryBuilderTest.php +++ b/docs/includes/query-builder/QueryBuilderTest.php @@ -153,9 +153,8 @@ public function testWhereDate(): void // begin query where date $result = DB::connection('mongodb') ->table('movies') - ->where('released', new UTCDateTime( - Carbon::create(2010, 1, 15, 0, 0, 0, 'UTC') - ))->get(); + ->where('released', Carbon::create(2010, 1, 15, 0, 0, 0, 'UTC')) + ->get(); // end query where date $this->assertInstanceOf(\Illuminate\Support\Collection::class, $result); diff --git a/docs/query-builder.txt b/docs/query-builder.txt index f15b0092b..59c3ff9be 100644 --- a/docs/query-builder.txt +++ b/docs/query-builder.txt @@ -359,10 +359,10 @@ is ``2010, 1, 15, 0, 0, 0``, specified in a ``Carbon`` object: :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, `Carbon `__ - objects passed as query filters, as shown in the preceding code example, are + 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`` diff --git a/docs/upgrade.txt b/docs/upgrade.txt index 1f9cf95ae..11af98eaa 100644 --- a/docs/upgrade.txt +++ b/docs/upgrade.txt @@ -85,7 +85,9 @@ This library version introduces the following breaking changes: 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 + ``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. From eb5f12a168f87f30a6c4d92376f8d45d272bc190 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 10 Sep 2024 11:49:54 -0400 Subject: [PATCH 5/9] feedback --- docs/query-builder.txt | 2 +- docs/upgrade.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/query-builder.txt b/docs/query-builder.txt index 59c3ff9be..f5b2c9fb1 100644 --- a/docs/query-builder.txt +++ b/docs/query-builder.txt @@ -351,7 +351,7 @@ Match Dates Example The following example shows how to use the ``where()`` query builder method to retrieve documents from the ``movies`` collection in which the ``released`` value -is ``2010, 1, 15, 0, 0, 0``, specified in a ``Carbon`` object: +is January 15, 2010, specified in a ``Carbon`` object: .. literalinclude:: /includes/query-builder/QueryBuilderTest.php :language: php diff --git a/docs/upgrade.txt b/docs/upgrade.txt index 11af98eaa..e6f112fd4 100644 --- a/docs/upgrade.txt +++ b/docs/upgrade.txt @@ -87,7 +87,7 @@ This library version introduces the following breaking changes: 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 + 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. From 89fbfaf67814483b9506ad5b9da1a355599b7bc8 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 10 Sep 2024 13:38:24 -0400 Subject: [PATCH 6/9] JT feedback --- docs/includes/query-builder/QueryBuilderTest.php | 16 ++++++++++++++-- docs/query-builder.txt | 12 ++++++++++++ 2 files changed, 26 insertions(+), 2 deletions(-) diff --git a/docs/includes/query-builder/QueryBuilderTest.php b/docs/includes/query-builder/QueryBuilderTest.php index c59c33a8d..04dc7c6f2 100644 --- a/docs/includes/query-builder/QueryBuilderTest.php +++ b/docs/includes/query-builder/QueryBuilderTest.php @@ -148,18 +148,30 @@ public function testWhereIn(): void $this->assertInstanceOf(\Illuminate\Support\Collection::class, $result); } - public function testWhereDate(): void + public function testWhereCarbon(): void { // begin query where date $result = DB::connection('mongodb') ->table('movies') - ->where('released', Carbon::create(2010, 1, 15, 0, 0, 0, 'UTC')) + ->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 string + $result = DB::connection('mongodb') + ->table('movies') + ->whereDate('released', '2010-1-15') + ->get(); + // end query whereDate string + + $this->assertInstanceOf(\Illuminate\Support\Collection::class, $result); + } + public function testLike(): void { // begin query like diff --git a/docs/query-builder.txt b/docs/query-builder.txt index f5b2c9fb1..5be6b05b4 100644 --- a/docs/query-builder.txt +++ b/docs/query-builder.txt @@ -369,6 +369,18 @@ is January 15, 2010, specified in a ``Carbon`` object: 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: Text Pattern Match Example From 7cbf2312807ebad1ddf5c3f0a4b2103344982993 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 10 Sep 2024 16:36:50 -0400 Subject: [PATCH 7/9] carbon use statement --- docs/includes/query-builder/QueryBuilderTest.php | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/includes/query-builder/QueryBuilderTest.php b/docs/includes/query-builder/QueryBuilderTest.php index 04dc7c6f2..39c945fc6 100644 --- a/docs/includes/query-builder/QueryBuilderTest.php +++ b/docs/includes/query-builder/QueryBuilderTest.php @@ -11,6 +11,7 @@ use MongoDB\BSON\Regex; use MongoDB\Collection; use MongoDB\Laravel\Tests\TestCase; +use Carbon\Carbon; use function file_get_contents; use function json_decode; From 2d048dfd8c07862e5b65bab035bd3e1afbd6f67f Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 10 Sep 2024 20:38:57 +0000 Subject: [PATCH 8/9] apply phpcbf formatting --- docs/includes/query-builder/QueryBuilderTest.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/includes/query-builder/QueryBuilderTest.php b/docs/includes/query-builder/QueryBuilderTest.php index 39c945fc6..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; @@ -11,7 +12,6 @@ use MongoDB\BSON\Regex; use MongoDB\Collection; use MongoDB\Laravel\Tests\TestCase; -use Carbon\Carbon; use function file_get_contents; use function json_decode; From 1935a5783ca657c824cf048e501c98a21ceb6069 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 10 Sep 2024 16:46:33 -0400 Subject: [PATCH 9/9] checks