From 3bc0c4ac2b9ec292d5be06c971ce8b554c40ecfb Mon Sep 17 00:00:00 2001 From: Chris Cho <52428683+ccho-mongodb@users.noreply.github.com> Date: Fri, 26 Apr 2024 13:42:29 -0400 Subject: [PATCH] DOCSP-38344: docs cleanup (#2902) Assorted cleanup tasks --------- Co-authored-by: Chris Cho --- docs/compatibility.txt | 3 ++ docs/eloquent-models.txt | 2 +- docs/eloquent-models/relationships.txt | 10 ++-- docs/eloquent-models/schema-builder.txt | 17 +++--- docs/fundamentals.txt | 4 +- docs/fundamentals/connection.txt | 7 +++ .../connection/connect-to-mongodb.txt | 13 +++-- .../connection/connection-options.txt | 6 ++- docs/fundamentals/database-collection.txt | 8 +-- docs/fundamentals/read-operations.txt | 26 ++++----- docs/fundamentals/write-operations.txt | 8 +-- .../query-builder/QueryBuilderTest.php | 1 - .../usage-examples/fact-edit-laravel-app.rst | 2 + .../usage-examples/operation-description.rst | 2 + docs/index.txt | 7 ++- docs/issues-and-help.txt | 9 +++- docs/quick-start.txt | 4 +- docs/quick-start/configure-mongodb.txt | 48 +++++++++++++---- docs/quick-start/next-steps.txt | 7 +++ docs/quick-start/view-data.txt | 2 +- docs/quick-start/write-data.txt | 4 +- docs/transactions.txt | 2 +- docs/upgrade.txt | 2 +- docs/usage-examples.txt | 29 ++++++++-- docs/usage-examples/count.txt | 18 ++++--- docs/usage-examples/deleteMany.txt | 10 ++-- docs/usage-examples/deleteOne.txt | 8 +-- docs/usage-examples/distinct.txt | 9 ++-- docs/usage-examples/find.txt | 15 ++++-- docs/usage-examples/findOne.txt | 53 +++++++++---------- docs/usage-examples/insertMany.txt | 14 ++--- docs/usage-examples/insertOne.txt | 5 +- docs/usage-examples/runCommand.txt | 16 +++++- docs/usage-examples/updateMany.txt | 7 ++- docs/usage-examples/updateOne.txt | 14 +++-- 35 files changed, 241 insertions(+), 151 deletions(-) create mode 100644 docs/includes/usage-examples/fact-edit-laravel-app.rst create mode 100644 docs/includes/usage-examples/operation-description.rst diff --git a/docs/compatibility.txt b/docs/compatibility.txt index 1ab0f6c91..dc0b33148 100644 --- a/docs/compatibility.txt +++ b/docs/compatibility.txt @@ -14,6 +14,9 @@ Compatibility :depth: 1 :class: singlecol +.. meta:: + :keywords: laravel 9, laravel 10, laravel 11, 4.0, 4.1, 4.2 + Laravel Compatibility --------------------- diff --git a/docs/eloquent-models.txt b/docs/eloquent-models.txt index e7edadcfe..95fe24d15 100644 --- a/docs/eloquent-models.txt +++ b/docs/eloquent-models.txt @@ -26,7 +26,7 @@ This section contains guidance on how to use Eloquent models in between models - :ref:`laravel-schema-builder` shows how to manage indexes on your MongoDB collections by using Laravel migrations - + .. toctree:: /eloquent-models/model-class/ diff --git a/docs/eloquent-models/relationships.txt b/docs/eloquent-models/relationships.txt index 2ae716132..b71b8b8c2 100644 --- a/docs/eloquent-models/relationships.txt +++ b/docs/eloquent-models/relationships.txt @@ -90,7 +90,7 @@ method: :dedent: The following sample code shows how to instantiate a model for each class -and add the relationship between them. Click the :guilabel:`VIEW OUTPUT` +and add the relationship between them. Click the :guilabel:`{+code-output-label+}` button to see the data created by running the code: .. io-code-block:: @@ -175,7 +175,7 @@ model by using the ``belongsTo()`` method: :dedent: The following sample code shows how to instantiate a model for each class -and add the relationship between them. Click the :guilabel:`VIEW OUTPUT` +and add the relationship between them. Click the :guilabel:`{+code-output-label+}` button to see the data created by running the code: .. io-code-block:: @@ -275,7 +275,7 @@ using the ``belongsToMany()`` method: :dedent: The following sample code shows how to instantiate a model for each class -and add the relationship between them. Click the :guilabel:`VIEW OUTPUT` +and add the relationship between them. Click the :guilabel:`{+code-output-label+}` button to see the data created by running the code: .. io-code-block:: @@ -405,7 +405,7 @@ following ``Cargo`` model class: The following sample code shows how to create a ``SpaceShip`` model and embed multiple ``Cargo`` models and the MongoDB document created by running the -code. Click the :guilabel:`VIEW OUTPUT` button to see the data created by +code. Click the :guilabel:`{+code-output-label+}` button to see the data created by running the code: .. io-code-block:: @@ -496,7 +496,7 @@ model by using the ``belongsTo()`` method: The following sample code shows how to create a ``SpaceShip`` model in a MySQL database and related ``Passenger`` models in a MongoDB database as well -as the data created by running the code. Click the :guilabel:`VIEW OUTPUT` button +as the data created by running the code. Click the :guilabel:`{+code-output-label+}` button to see the data created by running the code: .. io-code-block:: diff --git a/docs/eloquent-models/schema-builder.txt b/docs/eloquent-models/schema-builder.txt index c6c7e64cc..551de4696 100644 --- a/docs/eloquent-models/schema-builder.txt +++ b/docs/eloquent-models/schema-builder.txt @@ -75,8 +75,9 @@ following changes to perform the schema changes on your MongoDB database: MongoDB database, update the following setting to make sure the migration specifies the correct database: - - Specify ``mongodb`` in the ``$connection`` field of your migration class - - Set ``DB_CONNECTION=mongodb`` in your ``.env`` configuration file + - Make sure your ``connections`` array item contains a valid ``mongodb`` + entry in your ``config/database.php`` file + - Specify ``"mongodb"`` in the ``$connection`` field of your migration class The following example migration class contains the following methods: @@ -166,9 +167,9 @@ fields: - Single field index on ``mission_type`` - Compound index on ``launch_location`` and ``launch_date``, specifying a descending sort order on ``launch_date`` -- Unique index on the ``mission_id`` field, specifying the index name "unique_mission_id_idx" +- Unique index on the ``mission_id`` field, specifying the index name ``"unique_mission_id_idx"`` -Click the :guilabel:`VIEW OUTPUT` button to see the indexes created by running +Click the :guilabel:`{+code-output-label+}` button to see the indexes created by running the migration, including the default index on the ``_id`` field: .. io-code-block:: @@ -207,7 +208,7 @@ You can specify index options when calling an index creation method, such as ``index()``, on a ``Blueprint`` instance. The following migration code shows how to add a collation to an index as an -index option. Click the :guilabel:`VIEW OUTPUT` button to see the indexes +index option. Click the :guilabel:`{+code-output-label+}` button to see the indexes created by running the migration, including the default index on the ``_id`` field: @@ -266,7 +267,7 @@ appropriate helper method on the ``Blueprint`` instance and pass the index creation details. The following migration code shows how to create a sparse and a TTL index -by using the index helpers. Click the :guilabel:`VIEW OUTPUT` button to see +by using the index helpers. Click the :guilabel:`{+code-output-label+}` button to see the indexes created by running the migration, including the default index on the ``_id`` field: @@ -297,7 +298,7 @@ You can specify sparse, TTL, and unique indexes on either a single field or compound index by specifying them in the index options. The following migration code shows how to create all three types of indexes -on a single field. Click the :guilabel:`VIEW OUTPUT` button to see the indexes +on a single field. Click the :guilabel:`{+code-output-label+}` button to see the indexes created by running the migration, including the default index on the ``_id`` field: @@ -342,7 +343,7 @@ method with a ``MongoDB\Laravel\Schema\Blueprint`` parameter. Specify the geospatial index creation details on the ``Blueprint`` instance. The following example migration creates a ``2d`` and ``2dsphere`` geospatial -index on the ``spaceports`` collection. Click the :guilabel:`VIEW OUTPUT` +index on the ``spaceports`` collection. Click the :guilabel:`{+code-output-label+}` button to see the indexes created by running the migration, including the default index on the ``_id`` field: diff --git a/docs/fundamentals.txt b/docs/fundamentals.txt index 250e82efa..5d88f288a 100644 --- a/docs/fundamentals.txt +++ b/docs/fundamentals.txt @@ -9,7 +9,7 @@ Fundamentals :values: reference .. meta:: - :keywords: php framework, odm + :keywords: php framework, odm, concepts .. toctree:: :titlesonly: @@ -20,7 +20,7 @@ Fundamentals /fundamentals/read-operations /fundamentals/write-operations -Learn how to use the {+odm-long+} to perform the following tasks: +Learn more about the following concepts related to the {+odm-long+}: - :ref:`laravel-fundamentals-connection` - :ref:`laravel-db-coll` diff --git a/docs/fundamentals/connection.txt b/docs/fundamentals/connection.txt index 17b849ae9..b9d371c6b 100644 --- a/docs/fundamentals/connection.txt +++ b/docs/fundamentals/connection.txt @@ -4,6 +4,13 @@ Connections =========== +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: options, deployment, connection behavior + .. toctree:: /fundamentals/connection/connect-to-mongodb diff --git a/docs/fundamentals/connection/connect-to-mongodb.txt b/docs/fundamentals/connection/connect-to-mongodb.txt index 7de96ad76..9f7e07b26 100644 --- a/docs/fundamentals/connection/connect-to-mongodb.txt +++ b/docs/fundamentals/connection/connect-to-mongodb.txt @@ -78,6 +78,9 @@ options. In the example, we set the following connection options and values: - ``maxPoolSize=20`` - ``w=majority`` +To learn more about connection options, see +:ref:`laravel-fundamentals-connection-options`. + .. _laravel-database-config: Laravel Database Connection Configuration @@ -151,11 +154,13 @@ For a MongoDB database connection, you can specify the following details: * - ``options`` - Specifies connection options to pass to MongoDB that determine the - connection behavior. + connection behavior. To learn more about connection options, see + :ref:`laravel-connection-auth-options`. * - ``driverOptions`` - - Specifies options specific to pass to the MongoDB PHP Library driver - that determine the driver behavior for that connection. + - Specifies options specific to pass to the {+php-library+} that + determine the driver behavior for that connection. To learn more about + driver options, see :ref:`laravel-driver-options`. .. note:: @@ -323,6 +328,8 @@ To learn more about setting up a MongoDB replica set, see :manual:`Deploy a Replica Set ` in the {+server-docs-name+}. +.. _laravel-direct-connection: + Direct Connection ````````````````` diff --git a/docs/fundamentals/connection/connection-options.txt b/docs/fundamentals/connection/connection-options.txt index 9d873a406..d73cb33d4 100644 --- a/docs/fundamentals/connection/connection-options.txt +++ b/docs/fundamentals/connection/connection-options.txt @@ -155,7 +155,9 @@ and their default values: - Boolean - ``false`` - Specifies whether to directly connect to a single host instead of - discovering and connecting to all servers in the cluster. + discovering and connecting to all servers in the cluster. To learn more + about this setting, see :ref:`laravel-direct-connection` in the + Connection Guide. * - **heartbeatFrequencyMS** - Integer greater than or equal to ``500`` @@ -295,7 +297,7 @@ and their default values: - | Requests acknowledgment that the operation has propagated to a specific number or variety of servers. | To learn more, see :manual:`Write Concern ` - in the Server manual. + in the {+server-docs-name+}. * - **wTimeoutMS** - Non-negative integer diff --git a/docs/fundamentals/database-collection.txt b/docs/fundamentals/database-collection.txt index db74b045b..6b629d79e 100644 --- a/docs/fundamentals/database-collection.txt +++ b/docs/fundamentals/database-collection.txt @@ -30,7 +30,7 @@ data as **documents** that contain field-and-value pairs. In {+odm-short+}, you can access documents through Eloquent models. To learn more about the document data format, -see :manual:`Documents ` in the Server manual. +see :manual:`Documents ` in the {+server-docs-name+}. .. _laravel-access-db: @@ -39,7 +39,7 @@ Specify the Database in a Connection Configuration You can specify a database name that a connection uses in your application's ``config/database.php`` file. The ``connections`` property -in this file stores all of your database connection information, such as +in this file stores all your database connection information, such as your connection string, database name, and optionally, authentication details. After you specify a database connection, you can perform database-level operations and access collections that the database @@ -98,8 +98,8 @@ The following example shows how to specify multiple database connections The MongoDB PHP driver reuses the same connection when you create two clients with the same connection string. There is no - overhead in using two connections for two distinct databases, so you - do not need to optimize your connections. + overhead in using two connections for two distinct databases, so it is + unnecessary to optimize your connections. If your application contains multiple database connections and you want to store your model in a database other than the default, override the diff --git a/docs/fundamentals/read-operations.txt b/docs/fundamentals/read-operations.txt index 0201cb782..8025f0087 100644 --- a/docs/fundamentals/read-operations.txt +++ b/docs/fundamentals/read-operations.txt @@ -256,14 +256,14 @@ a text index on the ``plot`` field. IMDB Rating: 7.4 IMDB Votes: 9663 Plot: A love story between a man and woman ... - + Title: Paheli Year: 2005 Runtime: 140 IMDB Rating: 6.7 IMDB Votes: 8909 Plot: A folk tale - supernatural love story about a ghost ... - + Title: Por un puèado de besos Year: 2014 Runtime: 98 @@ -296,7 +296,7 @@ results by relevance by using the ``orderBy()`` method to sort on the Modify Behavior --------------- -You can modify the results of a find operation by chaining additional methods +You can modify the results of a find operation by chaining more methods to ``where()``. The following sections demonstrate how to modify the behavior of the ``where()`` @@ -397,15 +397,15 @@ followed by the ``orderBy()`` method. You can set an **ascending** or **descending** sort direction on results. By default, the ``orderBy()`` method sets an ascending sort on the supplied field name, but you can explicitly specify an ascending -sort by passing ``'asc'`` as the second parameter. To -specify a descending sort, pass ``'desc'`` as the second parameter. +sort by passing ``"asc"`` as the second parameter. To +specify a descending sort, pass ``"desc"`` as the second parameter. If your documents contain duplicate values in a specific field, you can -handle the tie by specifying additional fields to sort on. This ensures consistent -results if the additional fields contain unique values. +handle the tie by specifying more fields to sort on. This ensures consistent +results if the other fields contain unique values. This example queries for documents in which the value of the ``countries`` field contains -``'Indonesia'`` and orders results first by an ascending sort on the +``"Indonesia"`` and orders results first by an ascending sort on the ``year`` field, then a descending sort on the ``title`` field. .. tabs:: @@ -458,14 +458,14 @@ This example queries for documents in which the value of the ``countries`` field IMDB Rating: 7.6 IMDB Votes: 702 Plot: A film delivery man promises ... - + Title: Gie Year: 2005 Runtime: 147 IMDB Rating: 7.5 IMDB Votes: 470 Plot: Soe Hok Gie is an activist who lived in the sixties ... - + Title: Requiem from Java Year: 2006 Runtime: 120 @@ -473,7 +473,7 @@ This example queries for documents in which the value of the ``countries`` field IMDB Votes: 316 Plot: Setyo (Martinus Miroto) and Siti (Artika Sari Dewi) are young married couple ... - + ... .. tip:: @@ -481,8 +481,8 @@ This example queries for documents in which the value of the ``countries`` field To learn more about sorting, see the following resources: - :manual:`Natural order ` - in the Server manual glossary - - `Ordering, Grouping, Limit and Offset `__ + in the {+server-docs-name+} glossary + - `Ordering, Grouping, Limit, and Offset `__ in the Laravel documentation .. _laravel-retrieve-one: diff --git a/docs/fundamentals/write-operations.txt b/docs/fundamentals/write-operations.txt index 242d4e941..57bbcd8bc 100644 --- a/docs/fundamentals/write-operations.txt +++ b/docs/fundamentals/write-operations.txt @@ -283,7 +283,7 @@ Upsert Example This example shows how to pass the ``upsert`` option to the ``update()`` method to perform an update or insert in a single operation. Click the -:guilabel:`VIEW OUTPUT` button to see the example document inserted when no +:guilabel:`{+code-output-label+}` button to see the example document inserted when no matching documents exist: .. io-code-block:: @@ -353,7 +353,7 @@ method call: The following example shows how to add the value ``"baroque"`` to the ``genres`` array field of a matching document. Click the -:guilabel:`VIEW OUTPUT` button to see the updated document: +:guilabel:`{+code-output-label+}` button to see the updated document: .. io-code-block:: @@ -400,7 +400,7 @@ from the array. The following code example shows the structure of a The following example shows how to remove array values ``"classical"`` and ``"dance-pop"`` from the ``genres`` array field. Click the -:guilabel:`VIEW OUTPUT` button to see the updated document: +:guilabel:`{+code-output-label+}` button to see the updated document: .. io-code-block:: @@ -451,7 +451,7 @@ structure of a positional operator update call on a single matching document: The following example shows how to replace the array value ``"dance-pop"`` with ``"contemporary"`` in the ``genres`` array field. Click the -:guilabel:`VIEW OUTPUT` button to see the updated document: +:guilabel:`{+code-output-label+}` button to see the updated document: .. io-code-block:: diff --git a/docs/includes/query-builder/QueryBuilderTest.php b/docs/includes/query-builder/QueryBuilderTest.php index 40705102d..a7d7a591e 100644 --- a/docs/includes/query-builder/QueryBuilderTest.php +++ b/docs/includes/query-builder/QueryBuilderTest.php @@ -228,7 +228,6 @@ public function testAggAvg(): void // begin aggregation avg $result = DB::collection('movies') ->avg('imdb.rating'); - //->avg('year'); // end aggregation avg $this->assertIsFloat($result); diff --git a/docs/includes/usage-examples/fact-edit-laravel-app.rst b/docs/includes/usage-examples/fact-edit-laravel-app.rst new file mode 100644 index 000000000..ad6839cfb --- /dev/null +++ b/docs/includes/usage-examples/fact-edit-laravel-app.rst @@ -0,0 +1,2 @@ +To learn how to edit your Laravel application to run the usage example, see the +:ref:`Usage Examples landing page `. diff --git a/docs/includes/usage-examples/operation-description.rst b/docs/includes/usage-examples/operation-description.rst new file mode 100644 index 000000000..68119a249 --- /dev/null +++ b/docs/includes/usage-examples/operation-description.rst @@ -0,0 +1,2 @@ +|operator-description| by creating a query builder, using a method such +as ``Model::where()`` or the ``DB`` facade to match documents in a collection, and then calling |result-operation|. diff --git a/docs/index.txt b/docs/index.txt index 88aee9d65..ecd464d60 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -1,5 +1,5 @@ =============== -Laravel MongoDB +{+odm-short+} =============== .. facet:: @@ -92,7 +92,6 @@ compatible, see the :ref:`laravel-compatibility` section. Upgrade Versions ---------------- -Learn what changes you might need to make to your application to upgrade -versions in the :ref:`laravel-upgrading` section. - +Learn what changes you must make to your application to upgrade versions in +the :ref:`laravel-upgrading` section. diff --git a/docs/issues-and-help.txt b/docs/issues-and-help.txt index ff4a1dbb9..197f0a5b1 100644 --- a/docs/issues-and-help.txt +++ b/docs/issues-and-help.txt @@ -4,8 +4,15 @@ Issues & Help ============= +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: debug, report bug, request, contribute, github, support + We are lucky to have a vibrant PHP community that includes users of varying -experience with MongoDB PHP Library and {+odm-short+}. To get support for +experience with {+php-library+} and {+odm-short+}. To get support for general questions, search or post in the :community-forum:`MongoDB PHP Community Forums `. diff --git a/docs/quick-start.txt b/docs/quick-start.txt index d672f3e31..ca5b6a87f 100644 --- a/docs/quick-start.txt +++ b/docs/quick-start.txt @@ -36,9 +36,9 @@ read and write operations on the data. :mdbu-course:`Getting Started with Laravel and MongoDB ` MongoDB University Learning Byte. - If you prefer to connect to MongoDB by using the PHP Library driver without + If you prefer to connect to MongoDB by using the {+php-library+} without Laravel, see `Connecting to MongoDB `__ - in the PHP Library documentation. + in the {+php-library+} documentation. {+odm-short+} extends the Laravel Eloquent and Query Builder syntax to store and retrieve data from MongoDB. diff --git a/docs/quick-start/configure-mongodb.txt b/docs/quick-start/configure-mongodb.txt index 66cd2380c..3baa3ed5e 100644 --- a/docs/quick-start/configure-mongodb.txt +++ b/docs/quick-start/configure-mongodb.txt @@ -14,20 +14,50 @@ Configure Your MongoDB Connection .. procedure:: :style: connected + .. step:: Configure the application environment variable file + + Copy the ``.env.example`` file to a file named ``.env`` in the project + root directory by running the following shell command: + + .. code-block:: sh + + cp .env.example .env + + Open the ``.env`` file and add or edit the following variables and values. + Replace the ```` placeholder with your connection + string from the :ref:`laravel-quick-start-connection-string` step: + + .. code-block:: bash + + DB_CONNECTION=mongodb + DB_URI="" + + For example, if your connection string is + ``"mongodb+srv://myUser:myPass123@mongo0.example.com/"``, + your ``DB_URI`` variable matches the following line: + + .. code-block:: bash + + DB_URI="mongodb+srv://myUser:myPass123@mongo0.example.com/" + + .. note:: + + Make sure these variables in your ``.env`` file are undefined in the + shell in which you run your application. Environment variables in + the shell take precedence over the ones in the ``.env`` file. + .. step:: Set the connection string in the database configuration - Open the ``database.php`` file in the ``config`` directory and - set the default database connection to ``mongodb`` as shown - in the following line: + Open the ``database.php`` file in the ``config`` directory and set the + default database connection to the ``DB_CONNECTION`` environment + variable as shown in the following line: .. code-block:: php - 'default' => env('DB_CONNECTION', 'mongodb'), + 'default' => env('DB_CONNECTION'), Add the following highlighted ``mongodb`` entry to the ``connections`` array - in the same file. Replace the ```` placeholder with the - connection string that you copied from the :ref:`laravel-quick-start-connection-string` - step in the following code example: + in the same file: .. code-block:: php :emphasize-lines: 2-6 @@ -35,13 +65,13 @@ Configure Your MongoDB Connection 'connections' => [ 'mongodb' => [ 'driver' => 'mongodb', - 'dsn' => env('DB_URI', ''), + 'dsn' => env('DB_URI'), 'database' => 'sample_mflix', ], // ... - .. step:: Add the Laravel MongoDB provider + .. step:: Add the {+odm-short+} provider Open the ``app.php`` file in the ``config`` directory and add the following entry into the ``providers`` array: diff --git a/docs/quick-start/next-steps.txt b/docs/quick-start/next-steps.txt index 0284720a3..1afcc2f7e 100644 --- a/docs/quick-start/next-steps.txt +++ b/docs/quick-start/next-steps.txt @@ -23,8 +23,15 @@ GitHub repository. Learn more about {+odm-short+} features from the following resources: +- :ref:`laravel-fundamentals-connection`: learn how to configure your MongoDB + connection. + +- :ref:`laravel-usage-examples`: see code examples of frequently used MongoDB + operations. + - :ref:`laravel-eloquent-models`: use Eloquent model classes to work with MongoDB data. - :ref:`laravel-query-builder`: use the query builder to specify MongoDB queries and aggregations. + diff --git a/docs/quick-start/view-data.txt b/docs/quick-start/view-data.txt index 1be17bb3f..6ce31369e 100644 --- a/docs/quick-start/view-data.txt +++ b/docs/quick-start/view-data.txt @@ -39,7 +39,7 @@ View MongoDB Data make the following edits: - Replace the ``Illuminate\Database\Eloquent\Model`` import with ``MongoDB\Laravel\Eloquent\Model`` - - Specify ``mongodb`` in the ``$connection`` field + - Specify ``"mongodb"`` in the ``$connection`` field The edited ``Movie.php`` file contains the following code: diff --git a/docs/quick-start/write-data.txt b/docs/quick-start/write-data.txt index 31568286a..af7d51ce0 100644 --- a/docs/quick-start/write-data.txt +++ b/docs/quick-start/write-data.txt @@ -68,14 +68,14 @@ Write Data to MongoDB .. code-block:: json { - "title": "The Laravel MongoDB Quick Start", + "title": "The {+odm-short+} Quick Start", "year": 2024, "runtime": 15, "imdb": { "rating": 9.5, "votes": 1 }, - "plot": "This movie entry was created by running through the Laravel MongoDB Quick Start tutorial." + "plot": "This movie entry was created by running through the {+odm-short+} Quick Start tutorial." } Send the JSON payload to the endpoint as a ``POST`` request by running diff --git a/docs/transactions.txt b/docs/transactions.txt index 3cb3c2c5b..5ef3df19d 100644 --- a/docs/transactions.txt +++ b/docs/transactions.txt @@ -24,7 +24,7 @@ In this guide, you can learn how to perform a **transaction** in MongoDB by using the {+odm-long+}. Transactions let you run a sequence of write operations that update the data only after the transaction is committed. -If the transaction fails, the PHP library that manages MongoDB operations +If the transaction fails, the {+php-library+} that manages MongoDB operations for {+odm-short+} ensures that MongoDB discards all the changes made within the transaction before they become visible. This property of transactions that ensures that all changes within a transaction are either applied or diff --git a/docs/upgrade.txt b/docs/upgrade.txt index 1aeba2be3..46308d6de 100644 --- a/docs/upgrade.txt +++ b/docs/upgrade.txt @@ -34,7 +34,7 @@ Before you upgrade, perform the following actions: application runs on. See the :ref:`` page for this information. - Address any breaking changes between the version of {+odm-short+} that - your application currently uses and your planned upgrade version in the + your application now uses and your planned upgrade version in the :ref:`` section of this guide. To upgrade your library version, run the following command in your application's diff --git a/docs/usage-examples.txt b/docs/usage-examples.txt index 629ba5eca..a17fd1b70 100644 --- a/docs/usage-examples.txt +++ b/docs/usage-examples.txt @@ -42,7 +42,7 @@ Before You Get Started ~~~~~~~~~~~~~~~~~~~~~~ You can run the usage examples from your own Laravel application or from the -``{+quickstart-app-name+}`` application created in the :ref:`laravel-quick-start` guide. +``{+quickstart-app-name+}`` application created in the :ref:`laravel-quick-start` guide. The usage examples are designed to run operations on a MongoDB deployment that contains the MongoDB Atlas sample datasets. Before running the usage examples, ensure that you load @@ -50,10 +50,14 @@ the sample data into the MongoDB cluster to which your application connects. Oth operation output might not match the text included in the ``{+code-output-label+}`` tab of the usage example page. -.. tip:: +Unless otherwise mentioned, usage examples use the ``Movie.php`` model class +created in the Quick Start to demonstrate operations on the ``movies`` MongoDB +collection. + +.. tip:: For instructions on loading the sample data into a MongoDB cluster, see - :atlas:`Load Sample Data ` in the Atlas documentation. + :atlas:`Load Sample Data ` in the Atlas documentation. .. _run-usage-examples: @@ -67,6 +71,25 @@ Laravel application. To view the expected output of the operation, you can add a web route to your application that calls the controller function and returns the result to a web interface. +.. _usage-example-list: + +Usage Example List +------------------ + +See code examples of the following operations in this section: + +- :ref:`laravel-find-one-usage` +- :ref:`laravel-find-usage` +- :ref:`laravel-insert-one-usage` +- :ref:`laravel-insert-many-usage` +- :ref:`laravel-update-one-usage` +- :ref:`laravel-update-many-usage` +- :ref:`laravel-delete-one-usage` +- :ref:`laravel-delete-many-usage` +- :ref:`laravel-count-usage` +- :ref:`laravel-distinct-usage` +- :ref:`laravel-run-command-usage` + .. toctree:: :titlesonly: :maxdepth: 1 diff --git a/docs/usage-examples/count.txt b/docs/usage-examples/count.txt index dc3720fc0..c3af477ee 100644 --- a/docs/usage-examples/count.txt +++ b/docs/usage-examples/count.txt @@ -17,11 +17,15 @@ Count Documents :depth: 1 :class: singlecol -You can count the number of documents returned by a query by calling the ``where()`` and -``count()`` methods on a collection of models or a query builder. +.. include:: /includes/usage-examples/operation-description.rst -To return the number of documents that match a filter, pass the query filter to the ``where()`` -method and call the ``count()`` method. + .. replacement:: operator-description + + You can count the number of documents returned by a query + + .. replacement:: result-operation + + the ``count()`` method to retrieve the results. Example ------- @@ -50,8 +54,6 @@ The example calls the following methods on the ``Movie`` model: :language: console :visible: false - Matching documents: 1267 - + Number of documents: 1267 -To learn how to edit your Laravel application to run the usage example, see the -:ref:`Usage Examples landing page `. +.. include:: /includes/usage-examples/fact-edit-laravel-app.rst diff --git a/docs/usage-examples/deleteMany.txt b/docs/usage-examples/deleteMany.txt index ec80f1140..14a1091f8 100644 --- a/docs/usage-examples/deleteMany.txt +++ b/docs/usage-examples/deleteMany.txt @@ -37,8 +37,8 @@ The example calls the following methods on the ``Movie`` model: - ``where()``: matches documents in which the value of the ``year`` field is less than or equal to ``1910``. -- ``delete()``: deletes the retrieved documents. This method returns the number of documents - that were successfully deleted. +- ``delete()``: deletes the matched documents. This method returns the number + of documents that the method successfully deletes. .. io-code-block:: :copyable: true @@ -55,14 +55,10 @@ The example calls the following methods on the ``Movie`` model: Deleted documents: 7 -To learn how to edit your Laravel application to run the usage example, see the -:ref:`Usage Examples landing page `. +.. include:: /includes/usage-examples/fact-edit-laravel-app.rst .. tip:: To learn more about deleting documents with {+odm-short+}, see the :ref:`laravel-fundamentals-delete-documents` section of the Write Operations guide. - For more information about query filters, see the :ref:`laravel-retrieve-matching` section of - the Read Operations guide. - diff --git a/docs/usage-examples/deleteOne.txt b/docs/usage-examples/deleteOne.txt index 3f934b273..9c8d6b127 100644 --- a/docs/usage-examples/deleteOne.txt +++ b/docs/usage-examples/deleteOne.txt @@ -36,7 +36,7 @@ This usage example performs the following actions: The example calls the following methods on the ``Movie`` model: -- ``where()``: matches documents in which the value of the ``title`` field is ``'Quiz Show'`` +- ``where()``: matches documents in which the value of the ``title`` field is ``"Quiz Show"`` - ``orderBy()``: sorts matched documents by their ascending ``_id`` values - ``limit()``: retrieves only the first matching document - ``delete()``: deletes the retrieved document @@ -56,8 +56,7 @@ The example calls the following methods on the ``Movie`` model: Deleted documents: 1 -For instructions on editing your Laravel application to run the usage example, see the -:ref:`Usage Example landing page `. +.. include:: /includes/usage-examples/fact-edit-laravel-app.rst .. tip:: @@ -65,6 +64,3 @@ For instructions on editing your Laravel application to run the usage example, s `__ section of the Laravel documentation. - For more information about query filters, see the :ref:`laravel-retrieve-matching` section of - the Read Operations guide. - diff --git a/docs/usage-examples/distinct.txt b/docs/usage-examples/distinct.txt index 8765bea1b..5d62ec8be 100644 --- a/docs/usage-examples/distinct.txt +++ b/docs/usage-examples/distinct.txt @@ -36,10 +36,10 @@ This usage example performs the following actions: The example calls the following methods on the ``Movie`` model: -- ``where()``: matches documents in which the value of the ``directors`` field includes ``'Sofia Coppola'``. +- ``where()``: matches documents in which the value of the ``directors`` field includes ``"Sofia Coppola"``. - ``select()``: retrieves the matching documents' ``imdb.rating`` field values. -- ``distinct()``: accesses the unique values of the ``imdb.rating`` field among the matching - documents. This method returns a list of values. +- ``distinct()``: retrieves the unique values of the selected field and returns + the list of values. - ``get()``: retrieves the query results. .. io-code-block:: @@ -57,8 +57,7 @@ The example calls the following methods on the ``Movie`` model: [[5.6],[6.4],[7.2],[7.8]] -To learn how to edit your Laravel application to run the usage example, see the -:ref:`Usage Examples landing page `. +.. include:: /includes/usage-examples/fact-edit-laravel-app.rst .. tip:: diff --git a/docs/usage-examples/find.txt b/docs/usage-examples/find.txt index 3e9115661..b12c97f41 100644 --- a/docs/usage-examples/find.txt +++ b/docs/usage-examples/find.txt @@ -17,9 +17,15 @@ Find Multiple Documents :depth: 1 :class: singlecol -You can retrieve multiple documents from a collection by creating a query -builder using a method such as ``Model::where()`` or by using the ``DB`` -facade, and then chaining the ``get()`` method to retrieve the result. +.. include:: /includes/usage-examples/operation-description.rst + + .. replacement:: operator-description + + You can retrieve multiple documents from a collection + + .. replacement:: result-operation + + the ``get()`` method to retrieve the results. Pass a query filter to the ``where()`` method to retrieve documents that meet a set of criteria. When you call the ``get()`` method, MongoDB returns the @@ -76,8 +82,7 @@ The example calls the following methods on the ``Movie`` model: ... ] -For instructions on editing your Laravel application to run the usage example, see the -:ref:`Usage Examples landing page `. +.. include:: /includes/usage-examples/fact-edit-laravel-app.rst .. tip:: diff --git a/docs/usage-examples/findOne.txt b/docs/usage-examples/findOne.txt index 2a66726d1..815d7923e 100644 --- a/docs/usage-examples/findOne.txt +++ b/docs/usage-examples/findOne.txt @@ -4,12 +4,24 @@ Find a Document =============== -You can retrieve a single document from a collection by calling the ``where()`` and -``first()`` methods on an Eloquent model or a query builder. +.. facet:: + :name: genre + :values: reference -Pass a query filter to the ``where()`` method and then call the ``first()`` method to -return one document in the collection that matches the filter. If multiple documents match -the query filter, ``first()`` returns the first matching document according to the documents' +.. meta:: + :keywords: find one, retrieve, code example, first + +.. include:: /includes/usage-examples/operation-description.rst + + .. replacement:: operator-description + + You can retrieve a single document from a collection + + .. replacement:: result-operation + + the ``first()`` method to return one document. + +If multiple documents match the query filter, ``first()`` returns the first matching document according to the documents' :term:`natural order` in the database or according to the sort order that you can specify by using the ``orderBy()`` method. @@ -25,7 +37,7 @@ This usage example performs the following actions: The example calls the following methods on the ``Movie`` model: -- ``where()``: matches documents in which the value of the ``directors`` field includes ``'Rob Reiner'``. +- ``where()``: matches documents in which the value of the ``directors`` field includes ``"Rob Reiner"``. - ``orderBy()``: sorts matched documents by their ascending ``_id`` values. - ``first()``: retrieves only the first matching document. @@ -42,34 +54,17 @@ The example calls the following methods on the ``Movie`` model: :visible: false // Result is truncated - + { - "_id": "573a1398f29313caabce94a3", - "plot": "Spinal Tap, one of England's loudest bands, is chronicled by film director - Marty DeBergi on what proves to be a fateful tour.", - "genres": [ - "Comedy", - "Music" - ], - "runtime": 82, - "metacritic": 85, - "rated": "R", - "cast": [ - "Rob Reiner", - "Kimberly Stringer", - "Chazz Dominguez", - "Shari Hall" - ], - "poster": "https://m.media-amazon.com/images/M/MV5BMTQ2MTIzMzg5Nl5BMl5BanBnXkFtZTgwOTc5NDI1MDE@._V1_SY1000_SX677_AL_.jpg", - "title": "This Is Spinal Tap", + "_id": ..., + "title": "This Is Spinal Tap", + "directors": [ "Rob Reiner" ], ... } - -For instructions on editing your Laravel application to run the usage example, see the -:ref:`Usage Example landing page `. +.. include:: /includes/usage-examples/fact-edit-laravel-app.rst .. tip:: To learn more about retrieving documents with {+odm-short+}, see the - :ref:`laravel-fundamentals-retrieve` guide \ No newline at end of file + :ref:`laravel-fundamentals-retrieve` guide. diff --git a/docs/usage-examples/insertMany.txt b/docs/usage-examples/insertMany.txt index bf771aa8d..2d59a78ab 100644 --- a/docs/usage-examples/insertMany.txt +++ b/docs/usage-examples/insertMany.txt @@ -9,7 +9,7 @@ Insert Multiple Documents :values: reference .. meta:: - :keywords: insert many, add, create, bulk, code example + :keywords: insert many, add multiple, code example .. contents:: On this page :local: @@ -32,11 +32,12 @@ This usage example performs the following actions: - Uses the ``Movie`` Eloquent model to represent the ``movies`` collection in the ``sample_mflix`` database - Inserts documents into the ``movies`` collection -- Prints the result of the insert operation +- Prints whether the insert operation succeeds -The example calls the ``insert()`` method to insert documents that represent movies released -in 2023. This method returns a value of ``1`` if the operation is successful, and it throws -an exception if the operation is unsuccessful. +The example calls the ``insert()`` method to insert documents that contain +information about movies released in ``2023``. If the insert operation is +successful, it returns a value of ``1``. If the operation fails, it throws +an exception. .. io-code-block:: :copyable: true @@ -53,8 +54,7 @@ an exception if the operation is unsuccessful. Insert operation success: yes -To learn how to edit your Laravel application to run the usage example, see the -:ref:`Usage Examples landing page `. +.. include:: /includes/usage-examples/fact-edit-laravel-app.rst .. tip:: diff --git a/docs/usage-examples/insertOne.txt b/docs/usage-examples/insertOne.txt index 785bf2578..e28e12090 100644 --- a/docs/usage-examples/insertOne.txt +++ b/docs/usage-examples/insertOne.txt @@ -61,13 +61,12 @@ information: "_id": "..." } -To learn how to edit your Laravel application to run the usage example, see the -:ref:`Usage Examples landing page `. +.. include:: /includes/usage-examples/fact-edit-laravel-app.rst .. 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 + 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 index 51f0cca83..7d3d95ac9 100644 --- a/docs/usage-examples/runCommand.txt +++ b/docs/usage-examples/runCommand.txt @@ -4,6 +4,19 @@ Run a Command ============= +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: server command, list collections, code example + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + You can run a MongoDB command directly on a database by calling the ``command()`` method on a database connection instance. @@ -44,8 +57,7 @@ returns a cursor that contains a result document for each collection in the data embedded_movies users -To learn how to edit your Laravel application to run the usage example, see the -:ref:`Usage Examples landing page `. +.. include:: /includes/usage-examples/fact-edit-laravel-app.rst .. tip:: diff --git a/docs/usage-examples/updateMany.txt b/docs/usage-examples/updateMany.txt index 3a7482336..7fd5bfd1b 100644 --- a/docs/usage-examples/updateMany.txt +++ b/docs/usage-examples/updateMany.txt @@ -1,4 +1,4 @@ -.. _laravel-update-one-usage: +.. _laravel-update-many-usage: ========================= Update Multiple Documents @@ -37,7 +37,7 @@ This usage example performs the following actions: 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.0``. - ``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. @@ -57,8 +57,7 @@ The example calls the following methods on the ``Movie`` model: Updated documents: 20 -To learn how to edit your Laravel application to run the usage example, see the -:ref:`Usage Examples landing page `. +.. include:: /includes/usage-examples/fact-edit-laravel-app.rst .. tip:: diff --git a/docs/usage-examples/updateOne.txt b/docs/usage-examples/updateOne.txt index 12aec17ff..42fcda477 100644 --- a/docs/usage-examples/updateOne.txt +++ b/docs/usage-examples/updateOne.txt @@ -31,16 +31,16 @@ 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 +- Updates a document from the ``movies`` collection that matches the 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 ``title`` field is ``'Carol'``. +- ``where()``: matches documents in which the value of the ``title`` field is ``"Carol"``. - ``orderBy()``: sorts matched documents by their ascending ``_id`` values. - ``first()``: retrieves only the first matching document. - ``update()``: updates the value of the ``imdb.rating`` nested field to from ``6.9`` to - ``7.3``. This method also updates the ``imdb.votes`` nested field from ``493`` to ``142000``. + ``7.3`` and the value of the ``imdb.votes`` nested field from ``493`` to ``142000``. .. io-code-block:: :copyable: true @@ -57,12 +57,10 @@ The example calls the following methods on the ``Movie`` model: Updated documents: 1 -For instructions on editing your Laravel application to run the usage example, see the -:ref:`Usage Example landing page `. +.. include:: /includes/usage-examples/fact-edit-laravel-app.rst .. 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.