From 91e0f6a6306856b02ec77752c1eda8f0cfac9d20 Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 12 Jul 2024 15:41:26 -0400 Subject: [PATCH 01/13] DOCSP-41335: Id alias --- docs/fundamentals/read-operations.txt | 7 ++++++- docs/includes/query-builder/QueryBuilderTest.php | 3 ++- docs/query-builder.txt | 12 ++++++++++-- 3 files changed, 18 insertions(+), 4 deletions(-) diff --git a/docs/fundamentals/read-operations.txt b/docs/fundamentals/read-operations.txt index 023494613..1e4f43687 100644 --- a/docs/fundamentals/read-operations.txt +++ b/docs/fundamentals/read-operations.txt @@ -552,6 +552,11 @@ This example queries for documents in which the value of the ``runtime`` field i ``30`` and returns the first matching document according to the value of the ``_id`` field. +.. note:: + + This example uses the ``id`` alias to represent the ``_id`` field, since {+odm-short+} + converts from ``id`` to ``_id`` automatically. + .. tabs:: .. tab:: Query Syntax @@ -582,7 +587,7 @@ field. public function show() { $movie = Movie::where('runtime', 30) - ->orderBy('_id') + ->orderBy('id') ->first(); return view('browse_movies', [ diff --git a/docs/includes/query-builder/QueryBuilderTest.php b/docs/includes/query-builder/QueryBuilderTest.php index a7d7a591e..0f707b292 100644 --- a/docs/includes/query-builder/QueryBuilderTest.php +++ b/docs/includes/query-builder/QueryBuilderTest.php @@ -10,6 +10,7 @@ use MongoDB\BSON\Regex; use MongoDB\Laravel\Collection; use MongoDB\Laravel\Tests\TestCase; +use MongoDB\BSON\ObjectId; use function file_get_contents; use function json_decode; @@ -63,7 +64,7 @@ public function testOrWhere(): void // begin query orWhere $result = DB::connection('mongodb') ->collection('movies') - ->where('year', 1955) + ->where('id', new ObjectId('573a1398f29313caabce9682')) ->orWhere('title', 'Back to the Future') ->get(); // end query orWhere diff --git a/docs/query-builder.txt b/docs/query-builder.txt index 8b4be3245..b98e5dcc8 100644 --- a/docs/query-builder.txt +++ b/docs/query-builder.txt @@ -176,8 +176,9 @@ Logical OR Example The following example shows how to chain the ``orWhere()`` query builder method to retrieve documents from the -``movies`` collection that either match the ``year`` -value of ``1955`` or match the ``title`` value ``"Back to the Future"``: +``movies`` collection that either match the ``_id`` +value of ``ObjectId('573a1398f29313caabce9682')`` or match +the ``title`` value ``"Back to the Future"``: .. literalinclude:: /includes/query-builder/QueryBuilderTest.php :language: php @@ -185,6 +186,13 @@ value of ``1955`` or match the ``title`` value ``"Back to the Future"``: :start-after: begin query orWhere :end-before: end query orWhere +.. note:: + + Beginning in {+odm-short+} v4.6, you can use the ``id`` alias to + represent the ``_id`` field, as shown in the preceding code. When you + run a find operation using the query builder, {+odm-short+} + automatically converts between ``id`` and ``_id``. + .. _laravel-query-builder-logical-and: Logical AND Example From 0da84e50400af19bc08e4241d4bf26df7555e8fa Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 12 Jul 2024 15:42:11 -0400 Subject: [PATCH 02/13] edits --- docs/fundamentals/read-operations.txt | 5 ----- 1 file changed, 5 deletions(-) diff --git a/docs/fundamentals/read-operations.txt b/docs/fundamentals/read-operations.txt index 1e4f43687..384cb5ae5 100644 --- a/docs/fundamentals/read-operations.txt +++ b/docs/fundamentals/read-operations.txt @@ -552,11 +552,6 @@ This example queries for documents in which the value of the ``runtime`` field i ``30`` and returns the first matching document according to the value of the ``_id`` field. -.. note:: - - This example uses the ``id`` alias to represent the ``_id`` field, since {+odm-short+} - converts from ``id`` to ``_id`` automatically. - .. tabs:: .. tab:: Query Syntax From 30f65648a7be7cad73e070ec3560bed2e2b7ff9f Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 12 Jul 2024 19:43:30 +0000 Subject: [PATCH 03/13] 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 0f707b292..e8e07db3a 100644 --- a/docs/includes/query-builder/QueryBuilderTest.php +++ b/docs/includes/query-builder/QueryBuilderTest.php @@ -7,10 +7,10 @@ use Illuminate\Database\Query\Builder; use Illuminate\Pagination\AbstractPaginator; use Illuminate\Support\Facades\DB; +use MongoDB\BSON\ObjectId; use MongoDB\BSON\Regex; use MongoDB\Laravel\Collection; use MongoDB\Laravel\Tests\TestCase; -use MongoDB\BSON\ObjectId; use function file_get_contents; use function json_decode; From 27b0a21092ae2d0533708faca2ff7be5a8677afb Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 12 Jul 2024 15:55:16 -0400 Subject: [PATCH 04/13] change back --- docs/fundamentals/read-operations.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fundamentals/read-operations.txt b/docs/fundamentals/read-operations.txt index 384cb5ae5..023494613 100644 --- a/docs/fundamentals/read-operations.txt +++ b/docs/fundamentals/read-operations.txt @@ -582,7 +582,7 @@ field. public function show() { $movie = Movie::where('runtime', 30) - ->orderBy('id') + ->orderBy('_id') ->first(); return view('browse_movies', [ From 93972b122613f4cbeba85481b90a3845020b127a Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 12 Jul 2024 16:35:15 -0400 Subject: [PATCH 05/13] add info to note --- docs/query-builder.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/query-builder.txt b/docs/query-builder.txt index b98e5dcc8..588baba22 100644 --- a/docs/query-builder.txt +++ b/docs/query-builder.txt @@ -191,7 +191,8 @@ the ``title`` value ``"Back to the Future"``: Beginning in {+odm-short+} v4.6, you can use the ``id`` alias to represent the ``_id`` field, as shown in the preceding code. When you run a find operation using the query builder, {+odm-short+} - automatically converts between ``id`` and ``_id``. + automatically converts between ``id`` and ``_id``. You cannot have + two separate ``id`` and ``_id`` fields in your documents. .. _laravel-query-builder-logical-and: From 6a0a260a2dfb4b22b6c80d0bfe2653ac9b11e51d Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 15 Jul 2024 10:23:35 -0400 Subject: [PATCH 06/13] v4.6 -> v5 --- docs/query-builder.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/query-builder.txt b/docs/query-builder.txt index 588baba22..6e4761136 100644 --- a/docs/query-builder.txt +++ b/docs/query-builder.txt @@ -188,7 +188,7 @@ the ``title`` value ``"Back to the Future"``: .. note:: - Beginning in {+odm-short+} v4.6, you can use the ``id`` alias to + Beginning in {+odm-short+} v5.0, you can use the ``id`` alias to represent the ``_id`` field, as shown in the preceding code. When you run a find operation using the query builder, {+odm-short+} automatically converts between ``id`` and ``_id``. You cannot have From 06e4c46e5793149bc13b8a5153c07677c773803d Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 16 Jul 2024 11:48:25 -0400 Subject: [PATCH 07/13] RR feedback --- docs/query-builder.txt | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/query-builder.txt b/docs/query-builder.txt index 6e4761136..3387a2777 100644 --- a/docs/query-builder.txt +++ b/docs/query-builder.txt @@ -176,9 +176,9 @@ Logical OR Example The following example shows how to chain the ``orWhere()`` query builder method to retrieve documents from the -``movies`` collection that either match the ``_id`` -value of ``ObjectId('573a1398f29313caabce9682')`` or match -the ``title`` value ``"Back to the Future"``: +``movies`` collection in which the value of the ``_id`` +field is ``ObjectId('573a1398f29313caabce9682')`` or +the value of the ``title`` field is ``"Back to the Future"``: .. literalinclude:: /includes/query-builder/QueryBuilderTest.php :language: php @@ -188,11 +188,11 @@ the ``title`` value ``"Back to the Future"``: .. note:: - Beginning in {+odm-short+} v5.0, you can use the ``id`` alias to - represent the ``_id`` field, as shown in the preceding code. When you - run a find operation using the query builder, {+odm-short+} - automatically converts between ``id`` and ``_id``. You cannot have - two separate ``id`` and ``_id`` fields in your documents. + You can use the ``id`` alias in your queries to represent + the ``_id`` field in MongoDB documents, as shown in the preceding + code. When you run a find operation using the query builder, {+odm-short+} + automatically converts between ``id`` and ``_id``. Because of this behavior, + you cannot have two separate ``id`` and ``_id`` fields in your documents. .. _laravel-query-builder-logical-and: From 00e882d18c789196d1d5f3ef70f392ce07b39576 Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 23 Jul 2024 11:56:58 -0400 Subject: [PATCH 08/13] rebase to v4.6, add content back --- docs/includes/query-builder/QueryBuilderTest.php | 2 +- docs/query-builder.txt | 13 +++++++++++-- 2 files changed, 12 insertions(+), 3 deletions(-) diff --git a/docs/includes/query-builder/QueryBuilderTest.php b/docs/includes/query-builder/QueryBuilderTest.php index a7d7a591e..fc58c269c 100644 --- a/docs/includes/query-builder/QueryBuilderTest.php +++ b/docs/includes/query-builder/QueryBuilderTest.php @@ -63,7 +63,7 @@ public function testOrWhere(): void // begin query orWhere $result = DB::connection('mongodb') ->collection('movies') - ->where('year', 1955) + ->where('id', new ObjectId('573a1398f29313caabce9682')) ->orWhere('title', 'Back to the Future') ->get(); // end query orWhere diff --git a/docs/query-builder.txt b/docs/query-builder.txt index 8b4be3245..f675dff83 100644 --- a/docs/query-builder.txt +++ b/docs/query-builder.txt @@ -176,8 +176,9 @@ Logical OR Example The following example shows how to chain the ``orWhere()`` query builder method to retrieve documents from the -``movies`` collection that either match the ``year`` -value of ``1955`` or match the ``title`` value ``"Back to the Future"``: +``movies`` collection in which the value of the ``_id`` +field is ``ObjectId('573a1398f29313caabce9682')`` or +the value of the ``title`` field is ``"Back to the Future"``: .. literalinclude:: /includes/query-builder/QueryBuilderTest.php :language: php @@ -185,6 +186,14 @@ value of ``1955`` or match the ``title`` value ``"Back to the Future"``: :start-after: begin query orWhere :end-before: end query orWhere +.. note:: id Alias + + Starting in v4.6, you can use the ``id`` alias in your queries to represent + the ``_id`` field in MongoDB documents, as shown in the preceding + code. When you run a find operation by using the query builder, {+odm-short+} + automatically converts between ``id`` and ``_id``. Because of this behavior, + you cannot have two separate ``id`` and ``_id`` fields in your documents. + .. _laravel-query-builder-logical-and: Logical AND Example From 5a36a49ffd74191c395035fb2b093e433b2a08f4 Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 30 Aug 2024 11:37:02 -0400 Subject: [PATCH 09/13] JT feedback --- docs/eloquent-models/model-class.txt | 8 ++------ docs/query-builder.txt | 4 ++-- 2 files changed, 4 insertions(+), 8 deletions(-) diff --git a/docs/eloquent-models/model-class.txt b/docs/eloquent-models/model-class.txt index 8cedb4ece..ef9f07bbb 100644 --- a/docs/eloquent-models/model-class.txt +++ b/docs/eloquent-models/model-class.txt @@ -295,12 +295,8 @@ including this trait, you can make the third-party class compatible with MongoDB. When you apply the ``DocumentModel`` trait to a model class, you must -declare the following properties in your class: - -- ``$primaryKey = '_id'``, because the ``_id`` field uniquely - identifies MongoDB documents -- ``$keyType = 'string'``, because the {+odm-short+} casts MongoDB - ``ObjectId`` values to type ``string`` +set the ``$keyType`` property to ``'string'`` as the {+odm-short+} +casts MongoDB ``ObjectId`` values to type ``string``. Extended Class Example ~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/query-builder.txt b/docs/query-builder.txt index 66214fc14..e34e385d3 100644 --- a/docs/query-builder.txt +++ b/docs/query-builder.txt @@ -188,8 +188,8 @@ the value of the ``title`` field is ``"Back to the Future"``: .. note:: - Starting in v5.0, you can use the ``id`` alias in your queries to represent - the ``_id`` field in MongoDB documents, as shown in the preceding + You can use the ``id`` alias in your queries to represent the + ``_id`` field in MongoDB documents, as shown in the preceding code. When you run a find operation using the query builder, {+odm-short+} automatically converts between ``id`` and ``_id``. Because of this behavior, you cannot have two separate ``id`` and ``_id`` fields in your documents. From 52928b50697451dae16089362b0cb572bca0fd00 Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 30 Aug 2024 11:42:41 -0400 Subject: [PATCH 10/13] fix --- docs/query-builder.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/query-builder.txt b/docs/query-builder.txt index e34e385d3..be5f9bb80 100644 --- a/docs/query-builder.txt +++ b/docs/query-builder.txt @@ -188,11 +188,11 @@ the value of the ``title`` field is ``"Back to the Future"``: .. note:: - You can use the ``id`` alias in your queries to represent the - ``_id`` field in MongoDB documents, as shown in the preceding + You can use the ``id`` alias in your queries to represent the + ``_id`` field in MongoDB documents, as shown in the preceding code. When you run a find operation using the query builder, {+odm-short+} - automatically converts between ``id`` and ``_id``. Because of this behavior, - you cannot have two separate ``id`` and ``_id`` fields in your documents. + automatically converts between ``id`` and ``_id``. Because of this behavior, + you cannot have two separate ``id`` and ``_id`` fields in your documents. .. _laravel-query-builder-logical-and: From 99b4f4e2d740f029e19e718e3509c71c4c034204 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 5 Sep 2024 13:11:18 -0400 Subject: [PATCH 11/13] add to upgrade guide --- docs/upgrade.txt | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/upgrade.txt b/docs/upgrade.txt index 301a2100e..926344084 100644 --- a/docs/upgrade.txt +++ b/docs/upgrade.txt @@ -74,6 +74,11 @@ This library version introduces the following breaking changes: - In query results, the library converts BSON ``UTCDateTime`` objects to ``Carbon`` date classes, applying the default timezone. +- ``id`` is an alias for the ``_id`` field in MongoDB documents, and the library + automatically converts between ``id`` and ``_id`` when querying data. Because + of this behavior, you cannot have two separate ``id`` and ``_id`` fields in your + documents. + .. _laravel-breaking-changes-v4.x: Version 4.x Breaking Changes From 1664cfea5ed3c009fb16f88edef0ef9d0429a1aa Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 5 Sep 2024 13:13:06 -0400 Subject: [PATCH 12/13] fix --- docs/upgrade.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/upgrade.txt b/docs/upgrade.txt index 926344084..fed27d862 100644 --- a/docs/upgrade.txt +++ b/docs/upgrade.txt @@ -75,9 +75,9 @@ This library version introduces the following breaking changes: date classes, applying the default timezone. - ``id`` is an alias for the ``_id`` field in MongoDB documents, and the library - automatically converts between ``id`` and ``_id`` when querying data. Because - of this behavior, you cannot have two separate ``id`` and ``_id`` fields in your - documents. + automatically converts between ``id`` and ``_id`` when querying data. Because + of this behavior, you cannot have two separate ``id`` and ``_id`` fields in your + documents. .. _laravel-breaking-changes-v4.x: From 33d71c22e2c5e0ebe9d8569cbebfac850f215367 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 5 Sep 2024 15:07:15 -0400 Subject: [PATCH 13/13] JT feedback 2 --- docs/includes/query-builder/QueryBuilderTest.php | 2 +- docs/query-builder.txt | 8 ++++++-- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/includes/query-builder/QueryBuilderTest.php b/docs/includes/query-builder/QueryBuilderTest.php index 0ad12ef94..5105e59b5 100644 --- a/docs/includes/query-builder/QueryBuilderTest.php +++ b/docs/includes/query-builder/QueryBuilderTest.php @@ -63,7 +63,7 @@ public function testOrWhere(): void { // begin query orWhere $result = DB::connection('mongodb') - ->collection('movies') + ->table('movies') ->where('id', new ObjectId('573a1398f29313caabce9682')) ->orWhere('title', 'Back to the Future') ->get(); diff --git a/docs/query-builder.txt b/docs/query-builder.txt index c6cbcb10d..9b1fe65f9 100644 --- a/docs/query-builder.txt +++ b/docs/query-builder.txt @@ -191,8 +191,12 @@ the value of the ``title`` field is ``"Back to the Future"``: You can use the ``id`` alias in your queries to represent the ``_id`` field in MongoDB documents, as shown in the preceding code. When you run a find operation using the query builder, {+odm-short+} - automatically converts between ``id`` and ``_id``. Because of this behavior, - you cannot have two separate ``id`` and ``_id`` fields in your documents. + automatically converts between ``id`` and ``_id``. This provides better + compatibility with Laravel, as the framework assumes that each record has a + primary key named ``id`` by default. + + Because of this behavior, you cannot have two separate ``id`` and ``_id`` + fields in your documents. .. _laravel-query-builder-logical-and: