diff --git a/docs/includes/usage-examples/InsertOneTest.php b/docs/includes/usage-examples/InsertOneTest.php new file mode 100644 index 000000000..15eadf419 --- /dev/null +++ b/docs/includes/usage-examples/InsertOneTest.php @@ -0,0 +1,35 @@ + 'Marriage Story', + 'year' => 2019, + 'runtime' => 136, + ]); + + echo $movie->toJson(); + // end-insert-one + + $this->assertInstanceOf(Movie::class, $movie); + $this->expectOutputRegex('/^{"title":"Marriage Story","year":2019,"runtime":136,"updated_at":".{27}","created_at":".{27}","_id":"[a-z0-9]{24}"}$/'); + } +} diff --git a/docs/includes/usage-examples/RunCommandTest.php b/docs/includes/usage-examples/RunCommandTest.php new file mode 100644 index 000000000..cd6e34696 --- /dev/null +++ b/docs/includes/usage-examples/RunCommandTest.php @@ -0,0 +1,29 @@ +command(['listCollections' => 1]); + + foreach ($cursor as $coll) { + echo $coll['name'] . "
\n"; + } + + // end-command + + $this->assertNotNull($cursor); + $this->assertInstanceOf(Cursor::class, $cursor); + $this->expectOutputRegex('/
/'); + } +} 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/index.txt b/docs/index.txt index 9f6b76483..e1331f6a2 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -61,6 +61,7 @@ Fundamentals To learn how to perform the following tasks by using {+odm-short+}, see the following content: +- :ref:`Manage Databases and Collections ` - :ref:`laravel-fundamentals-read-ops` - :ref:`laravel-fundamentals-write-ops` - :ref:`laravel-eloquent-models` @@ -75,6 +76,12 @@ Issues & Help Learn how to report bugs, contribute to the library, and find more resources in the :ref:`laravel-issues-and-help` section. +Feature Compatibility +--------------------- + +Learn about Laravel features that {+odm-short+} supports in the +:ref:`laravel-feature-compat` section. + Compatibility ------------- diff --git a/docs/usage-examples.txt b/docs/usage-examples.txt index 899655924..be29ee9ac 100644 --- a/docs/usage-examples.txt +++ b/docs/usage-examples.txt @@ -72,9 +72,12 @@ 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/updateMany /usage-examples/deleteOne /usage-examples/deleteMany /usage-examples/count /usage-examples/distinct + /usage-examples/runCommand 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/insertOne.txt b/docs/usage-examples/insertOne.txt new file mode 100644 index 000000000..785bf2578 --- /dev/null +++ b/docs/usage-examples/insertOne.txt @@ -0,0 +1,73 @@ +.. _laravel-insert-one-usage: + +================= +Insert a Document +================= + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: insert one, add one, code example + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +You can insert a document into a collection by calling the ``create()`` method on +an Eloquent model or query builder. + +To insert a document, pass the data you need to insert as a document containing +the fields and values to the ``create()`` method. + +Example +------- + +This usage example performs the following actions: + +- Uses the ``Movie`` Eloquent model to represent the ``movies`` collection in the + ``sample_mflix`` database +- Inserts a document into the ``movies`` collection + +The example calls the ``create()`` method to insert a document that contains the following +information: + +- ``title`` value of ``"Marriage Story"`` +- ``year`` value of ``2019`` +- ``runtime`` value of ``136`` + +.. io-code-block:: + :copyable: true + + .. input:: ../includes/usage-examples/InsertOneTest.php + :start-after: begin-insert-one + :end-before: end-insert-one + :language: php + :dedent: + + .. output:: + :language: json + :visible: false + + { + "title": "Marriage Story", + "year": 2019, + "runtime": 136, + "updated_at": "...", + "created_at": "...", + "_id": "..." + } + +To learn how to edit your Laravel application to run the usage example, see the +:ref:`Usage Examples landing page `. + +.. tip:: + + You can also use the ``save()`` or ``insert()`` methods to insert a document into a collection. + To learn more about insert operations, see the :ref:`laravel-fundamentals-insert-documents` section + of the Write Operations guide. + + diff --git a/docs/usage-examples/runCommand.txt b/docs/usage-examples/runCommand.txt new file mode 100644 index 000000000..51f0cca83 --- /dev/null +++ b/docs/usage-examples/runCommand.txt @@ -0,0 +1,53 @@ +.. _laravel-run-command-usage: + +============= +Run a Command +============= + +You can run a MongoDB command directly on a database by calling the ``command()`` +method on a database connection instance. + +To run a command, call the ``command()`` method and pass it a document that +contains the command and its parameters. + +Example +------- + +This usage example performs the following actions on the database connection +instance that uses the ``sample_mflix`` database: + +- Creates a database connection instance that references the ``sample_mflix`` + database +- Specifies a command to retrieve a list of collections and views in the + ``sample_mflix`` database +- Prints the value of the ``name`` field of each result returned by the command + +The example calls the ``command()`` method to run the ``listCollections`` command. This method +returns a cursor that contains a result document for each collection in the database. + +.. io-code-block:: + + .. input:: ../includes/usage-examples/RunCommandTest.php + :start-after: begin-command + :end-before: end-command + :language: php + :dedent: + + .. output:: + :language: console + :visible: false + + sessions + movies + theaters + comments + embedded_movies + users + +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 running MongoDB database commands, see + :manual:`Database Commands ` in the {+server-docs-name+}. 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: