diff --git a/docs/includes/usage-examples/UpdateManyTest.php b/docs/includes/usage-examples/UpdateManyTest.php new file mode 100644 index 000000000..49a77dd95 --- /dev/null +++ b/docs/includes/usage-examples/UpdateManyTest.php @@ -0,0 +1,48 @@ + '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) + ->update(['acclaimed' => true]); + + echo 'Updated documents: ' . $updates; + // end-update-many + + $this->assertEquals(2, $updates); + $this->expectOutputString('Updated documents: 2'); + } +} diff --git a/docs/usage-examples.txt b/docs/usage-examples.txt index 43994905d..4a33e18cd 100644 --- a/docs/usage-examples.txt +++ b/docs/usage-examples.txt @@ -72,9 +72,10 @@ calls the controller function and returns the result to a web interface. :maxdepth: 1 /usage-examples/findOne + /usage-examples/insertOne /usage-examples/insertMany /usage-examples/updateOne - /usage-examples/insertOne + /usage-examples/updateMany /usage-examples/deleteOne /usage-examples/deleteMany /usage-examples/count 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 new file mode 100644 index 000000000..3a7482336 --- /dev/null +++ b/docs/usage-examples/updateMany.txt @@ -0,0 +1,67 @@ +.. _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 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 +- 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``. +- ``update()``: updates the matching documents by adding an ``acclaimed`` field and setting + its value to ``true``. This method returns the number of documents that were successfully + updated. + +.. 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 + +To learn how to edit your Laravel application to run the usage example, see the +:ref:`Usage Examples landing page `. + +.. tip:: + + 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: