From cef2635b3550f5fe6c87e17a92c7ad3a5bac8bfb Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 8 Apr 2024 16:08:26 -0400 Subject: [PATCH 1/4] DOCSP-35975: Update many usage example --- .../usage-examples/UpdateManyTest.php | 32 +++++++++ docs/usage-examples.txt | 1 + docs/usage-examples/updateMany.txt | 66 +++++++++++++++++++ 3 files changed, 99 insertions(+) create mode 100644 docs/includes/usage-examples/UpdateManyTest.php create mode 100644 docs/usage-examples/updateMany.txt diff --git a/docs/includes/usage-examples/UpdateManyTest.php b/docs/includes/usage-examples/UpdateManyTest.php new file mode 100644 index 000000000..74134ea0f --- /dev/null +++ b/docs/includes/usage-examples/UpdateManyTest.php @@ -0,0 +1,32 @@ +', 9.0) + ->update(['$set' => ['acclaimed' => true]]); + + echo 'Updated documents: ' . $updates; + // end-update-many + + $this->assertTrue($updates); + $this->expectOutputString('Updated documents: 20'); + } +} diff --git a/docs/usage-examples.txt b/docs/usage-examples.txt index 2bcd9ac58..41458d723 100644 --- a/docs/usage-examples.txt +++ b/docs/usage-examples.txt @@ -73,3 +73,4 @@ calls the controller function and returns the result to a web interface. /usage-examples/findOne /usage-examples/updateOne + /usage-examples/updateMany diff --git a/docs/usage-examples/updateMany.txt b/docs/usage-examples/updateMany.txt new file mode 100644 index 000000000..d56a66fa7 --- /dev/null +++ b/docs/usage-examples/updateMany.txt @@ -0,0 +1,66 @@ +.. _laravel-update-one-usage: + +========================= +Update Multiple Documents +========================= + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: update many, modify, code example + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +You can update multiple documents in a collection by calling the ``update()`` method +on an Eloquent model or a query builder. + +Pass a query filter to the ``where()`` method to retrieve documents that meet a +set of criteria. Then, update the matching documents by passing your intended +document changes to the ``update()`` method. + +Example +------- + +This usage example performs the following actions: + +- Uses the ``Movie`` Eloquent model to represent the ``movies`` collection in the + ``sample_mflix`` database +- Updates documents from the ``movies`` collection that match a query filter + +The example calls the following methods on the ``Movie`` model: + +- ``where()``: matches documents in which the value of the ``imdb.rating`` nested field + is greater than ``9`` +- ``update()``: updates the matching documents by adding an ``acclaimed`` field and setting + its value to ``true`` + +.. io-code-block:: + :copyable: true + + .. input:: ../includes/usage-examples/UpdateManyTest.php + :start-after: begin-update-many + :end-before: end-update-many + :language: php + :dedent: + + .. output:: + :language: console + :visible: false + + Updated documents: 20 + +For instructions on editing your Laravel application to run the usage example, see the +:ref:`Usage Example landing page `. + +.. tip:: + + To learn more about updating data with {+odm-short+}, see the `Updates + `__ section of the + Laravel documentation. + From c7f0055f8fff5eca9ab6ab842ca19e2eb9ef9801 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 9 Apr 2024 12:20:40 -0400 Subject: [PATCH 2/4] editing code, wording --- .../usage-examples/UpdateManyTest.php | 20 +++++++++++++++++-- docs/usage-examples/updateMany.txt | 6 +++--- 2 files changed, 21 insertions(+), 5 deletions(-) diff --git a/docs/includes/usage-examples/UpdateManyTest.php b/docs/includes/usage-examples/UpdateManyTest.php index 74134ea0f..99d7a8bca 100644 --- a/docs/includes/usage-examples/UpdateManyTest.php +++ b/docs/includes/usage-examples/UpdateManyTest.php @@ -18,6 +18,22 @@ public function testUpdateMany(): void require_once __DIR__ . '/Movie.php'; Movie::truncate(); + Movie::insert([ + [ + 'title' => 'Hollywood', + 'imdb' => [ + 'rating' => 9.1, + 'votes' => 511, + ], + ], + [ + 'title' => 'The Shawshank Redemption', + 'imdb' => [ + 'rating' => 9.3, + 'votes' => 1513145, + ], + ], + ]); // begin-update-many $updates = Movie::where('imdb.rating', '>', 9.0) @@ -26,7 +42,7 @@ public function testUpdateMany(): void echo 'Updated documents: ' . $updates; // end-update-many - $this->assertTrue($updates); - $this->expectOutputString('Updated documents: 20'); + $this->assertEquals(2, $updates); + $this->expectOutputString('Updated documents: 2'); } } diff --git a/docs/usage-examples/updateMany.txt b/docs/usage-examples/updateMany.txt index d56a66fa7..4b852b46e 100644 --- a/docs/usage-examples/updateMany.txt +++ b/docs/usage-examples/updateMany.txt @@ -18,7 +18,7 @@ Update Multiple Documents :class: singlecol You can update multiple documents in a collection by calling the ``update()`` method -on an Eloquent model or a query builder. +on an Eloquent model or query builder. Pass a query filter to the ``where()`` method to retrieve documents that meet a set of criteria. Then, update the matching documents by passing your intended @@ -55,8 +55,8 @@ The example calls the following methods on the ``Movie`` model: Updated documents: 20 -For instructions on editing your Laravel application to run the usage example, see the -:ref:`Usage Example landing page `. +To learn how to edit your Laravel application to run the usage example, see the +:ref:`Usage Examples landing page `. .. tip:: From f03ca2d4137c3075801b390032e59b2dedf00d13 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 10 Apr 2024 13:50:16 -0400 Subject: [PATCH 3/4] CC feedback --- docs/usage-examples/deleteOne.txt | 1 + docs/usage-examples/findOne.txt | 5 +++-- docs/usage-examples/updateMany.txt | 13 +++++++------ docs/usage-examples/updateOne.txt | 5 +++-- 4 files changed, 14 insertions(+), 10 deletions(-) diff --git a/docs/usage-examples/deleteOne.txt b/docs/usage-examples/deleteOne.txt index 762cfd405..3f934b273 100644 --- a/docs/usage-examples/deleteOne.txt +++ b/docs/usage-examples/deleteOne.txt @@ -32,6 +32,7 @@ This usage example performs the following actions: - Uses the ``Movie`` Eloquent model to represent the ``movies`` collection in the ``sample_mflix`` database - Deletes a document from the ``movies`` collection that matches a query filter +- Prints the number of deleted documents The example calls the following methods on the ``Movie`` model: diff --git a/docs/usage-examples/findOne.txt b/docs/usage-examples/findOne.txt index 39fde3d56..2a66726d1 100644 --- a/docs/usage-examples/findOne.txt +++ b/docs/usage-examples/findOne.txt @@ -19,8 +19,9 @@ Example This usage example performs the following actions: - Uses the ``Movie`` Eloquent model to represent the ``movies`` collection in the - ``sample_mflix`` database. -- Retrieves a document from the ``movies`` collection that matches a query filter. + ``sample_mflix`` database +- Retrieves a document from the ``movies`` collection that matches a query filter +- Prints the retrieved document The example calls the following methods on the ``Movie`` model: diff --git a/docs/usage-examples/updateMany.txt b/docs/usage-examples/updateMany.txt index 4b852b46e..4295b2a64 100644 --- a/docs/usage-examples/updateMany.txt +++ b/docs/usage-examples/updateMany.txt @@ -18,7 +18,7 @@ Update Multiple Documents :class: singlecol You can update multiple documents in a collection by calling the ``update()`` method -on an Eloquent model or query builder. +on an object collection or query builder. Pass a query filter to the ``where()`` method to retrieve documents that meet a set of criteria. Then, update the matching documents by passing your intended @@ -32,13 +32,15 @@ This usage example performs the following actions: - Uses the ``Movie`` Eloquent model to represent the ``movies`` collection in the ``sample_mflix`` database - Updates documents from the ``movies`` collection that match a query filter +- Prints the number of updated documents The example calls the following methods on the ``Movie`` model: - ``where()``: matches documents in which the value of the ``imdb.rating`` nested field - is greater than ``9`` + is greater than ``9``. - ``update()``: updates the matching documents by adding an ``acclaimed`` field and setting - its value to ``true`` + its value to ``true``. This method returns the number of documents that were successfully + updated. .. io-code-block:: :copyable: true @@ -60,7 +62,6 @@ To learn how to edit your Laravel application to run the usage example, see the .. tip:: - To learn more about updating data with {+odm-short+}, see the `Updates - `__ section of the - Laravel documentation. + To learn more about updating data with {+odm-short+}, see the :ref:`laravel-fundamentals-modify-documents` + section of the Write Operations guide. diff --git a/docs/usage-examples/updateOne.txt b/docs/usage-examples/updateOne.txt index f60bd3bad..12aec17ff 100644 --- a/docs/usage-examples/updateOne.txt +++ b/docs/usage-examples/updateOne.txt @@ -30,8 +30,9 @@ Example This usage example performs the following actions: - Uses the ``Movie`` Eloquent model to represent the ``movies`` collection in the - ``sample_mflix`` database. -- Updates a document from the ``movies`` collection that matches a query filter. + ``sample_mflix`` database +- Updates a document from the ``movies`` collection that matches a query filter +- Prints the number of updated documents The example calls the following methods on the ``Movie`` model: From d6d70d90e5a6bf40182f5ef0982b8da5c4479f71 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 17 Apr 2024 12:07:36 -0700 Subject: [PATCH 4/4] JT feedback --- docs/includes/usage-examples/UpdateManyTest.php | 2 +- docs/usage-examples/updateMany.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/includes/usage-examples/UpdateManyTest.php b/docs/includes/usage-examples/UpdateManyTest.php index 99d7a8bca..49a77dd95 100644 --- a/docs/includes/usage-examples/UpdateManyTest.php +++ b/docs/includes/usage-examples/UpdateManyTest.php @@ -37,7 +37,7 @@ public function testUpdateMany(): void // begin-update-many $updates = Movie::where('imdb.rating', '>', 9.0) - ->update(['$set' => ['acclaimed' => true]]); + ->update(['acclaimed' => true]); echo 'Updated documents: ' . $updates; // end-update-many diff --git a/docs/usage-examples/updateMany.txt b/docs/usage-examples/updateMany.txt index 4295b2a64..3a7482336 100644 --- a/docs/usage-examples/updateMany.txt +++ b/docs/usage-examples/updateMany.txt @@ -18,7 +18,7 @@ Update Multiple Documents :class: singlecol You can update multiple documents in a collection by calling the ``update()`` method -on an object collection or query builder. +on a query builder. Pass a query filter to the ``where()`` method to retrieve documents that meet a set of criteria. Then, update the matching documents by passing your intended