From 70f1b801cbecdc7531d15dcb31027c98875104e8 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 28 Aug 2024 11:54:16 -0400 Subject: [PATCH 1/7] DOCSP-41967: Insert documents --- source/includes/write/insert.php | 37 +++++++ source/index.txt | 1 + source/write.txt | 11 ++ source/write/insert.txt | 171 +++++++++++++++++++++++++++++++ 4 files changed, 220 insertions(+) create mode 100644 source/includes/write/insert.php create mode 100644 source/write.txt create mode 100644 source/write/insert.txt diff --git a/source/includes/write/insert.php b/source/includes/write/insert.php new file mode 100644 index 00000000..3561a65e --- /dev/null +++ b/source/includes/write/insert.php @@ -0,0 +1,37 @@ +sample_restaurants->restaurants; +// end-db-coll + +// Inserts a document that stores a "name" value of "Mongo's Burgers" into the collection +// start-insert-one +$result = $collection->insertOne(['name' => 'Mongo\'s Burgers']); +// end-insert-one + +// Inserts documents representing restaurants into the collection +// start-insert-many +$restaurants = [ + ['name' => 'Mongo\'s Burgers'], + ['name' => 'Mongo\'s Pizza'] +]; + +$result = $collection->insertMany($restaurants); +// end-insert-many + +// Inserts multiple documents and instructs the insert operation to skip document-level validation +// start-modify +$docs = [ + ['name' => 'Mongo\'s Burgers'], + ['name' => 'Mongo\'s Pizza'], + ['name' => 'Mongo\'s Tacos'] +]; + +$result = $collection->insertMany($docs, ['bypassDocumentValidation' => true]); +// end-modify + diff --git a/source/index.txt b/source/index.txt index 38ff991f..7805e642 100644 --- a/source/index.txt +++ b/source/index.txt @@ -12,6 +12,7 @@ MongoDB PHP Library Get Started /read + /write /tutorial /upgrade /reference diff --git a/source/write.txt b/source/write.txt new file mode 100644 index 00000000..4db76455 --- /dev/null +++ b/source/write.txt @@ -0,0 +1,11 @@ +.. _php-write: + +===================== +Write Data to MongoDB +===================== + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /write/insert \ No newline at end of file diff --git a/source/write/insert.txt b/source/write/insert.txt new file mode 100644 index 00000000..72a41c47 --- /dev/null +++ b/source/write/insert.txt @@ -0,0 +1,171 @@ +.. _php-write-insert: + +================ +Insert Documents +================ + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example, write, save, create + +Overview +-------- + +In this guide, you can learn how to use the {+php-library+} to add +documents to a MongoDB collection by performing **insert operations**. + +An insert operation inserts one or more documents into a MongoDB collection. +You can perform an insert operation by using the ``MongoDB\Collection::insertOne()`` +method to insert a single document or the ``MongoDB\Collection::insertMany()`` +method to insert one or more documents. + +Sample Data +~~~~~~~~~~~ + +The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants`` +database from the :atlas:`Atlas sample datasets `. To access this collection +from your PHP application, instantiate a ``MongoDB\Client`` that connects to an Atlas cluster +and assign the following value to your ``collection`` variable: + +.. literalinclude:: /includes/read/insert.php + :language: php + :dedent: + :start-after: start-db-coll + :end-before: end-db-coll + +To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the +:atlas:`Get Started with Atlas ` guide. + +The ``_id`` Field +----------------- + +In a MongoDB collection, each document *must* contain an ``_id`` field +with a unique field value. + +MongoDB allows you to manage this field in two ways: + +- You can set this field for each document yourself, ensuring each + ``_id`` field value is unique. +- You can let the driver automatically generate unique ``ObjectId`` + values for each document ``_id``. + +Unless you can guarantee uniqueness, we recommend +letting the driver automatically generate ``_id`` values. + +.. note:: + + Duplicate ``_id`` values violate unique index constraints, which + causes the driver to return a ``MongoDB\Driver\Exception\BulkWriteException`` + error. + +To learn more about the ``_id`` field, see the +:manual:`Unique Indexes ` guide in the {+mdb-server+} manual. + +To learn more about document structure and rules, see the +:manual:`Documents ` guide in the {+mdb-server+} manual. + +Insert One Document +------------------- + +To add a single document to a MongoDB collection, call the ``MongoDB\Collection::insertOne()`` +method and pass the document you want to add. + +The following example inserts a document into the ``restaurants`` collection: + +.. literalinclude:: /includes/write/insert.php + :language: php + :dedent: + :start-after: start-insert-one + :end-before: end-insert-one + +Insert Multiple Documents +------------------------- + +To add multiple documents to a MongoDB collection, call the ``MongoDB\Collection::insertMany()`` +method and pass an array that stores the documents you want to add. + +The following example inserts two documents into the ``restaurants`` collection: + +.. literalinclude:: /includes/write/insert.php + :language: php + :dedent: + :start-after: start-insert-many + :end-before: end-insert-many + +Modify Insert Behavior +---------------------- + +You can modify the behavior of the ``MongoDB\Collection::insertOne()`` and +``MongoDB\Collection::insertMany()`` methods by passing an array that specifies +option values as a parameter. The following table describes some options +you can set in the array: + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Field + - Description + + * - ``bypassDocumentValidation`` + - | If set to ``true``, allows the write to opt out of + :manual:`document-level validation `. + | Defaults to ``false``. + | **Type**: ``bool`` + + * - ``writeConcern`` + - | Sets the write concern for the operation. + | Defaults to the write concern of the namespace. + | **Type**: ``MongoDB\Driver\WriteConcern`` + + * - ``ordered`` + - | If set to ``true``, the operation stops inserting documents when one insert + fails. If ``false``, the operation continues to insert the remaining documents + when one insert fails. You cannot pass this option to the ``insertOne()`` method. + | Defaults to ``true``. + | **Type**: ``bool`` + + * - ``comment`` + - | A comment to attach to the operation. For more information, see the :manual:`insert command + fields ` guide in the + {+mdb-server+} manual. + | **Type**: any valid BSON type + +Example +~~~~~~~ + +The following code uses the ``insertMany()`` method to insert three new +documents into a collection. Because the ``bypassDocumentValidation`` field +is set to ``true`` in an options array, this +insert operation bypasses document-level validation: + +.. literalinclude:: /includes/write/insert.php + :language: php + :dedent: + :start-after: start-modify + :end-before: end-modify + +Additional Information +---------------------- + +.. TODO: + For runnable code examples of inserting documents with the {+php-library+}, see + :ref:`php-write`. + +API Documentation +~~~~~~~~~~~~~~~~~ + +To learn more about any of the methods or types discussed in this +guide, see the following API documentation: + +- `MongoDB\\Collection::insertOne() <{+api+}/method/MongoDBCollection-insertOne/>`__ +- `MongoDB\\Collection::insertMany() <{+api+}/method/MongoDBCollection-insertMany/>`__ \ No newline at end of file From ff1a86d00a84df13b5aaea3c8a88c6b1d51cf70e Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 28 Aug 2024 11:55:41 -0400 Subject: [PATCH 2/7] build From 745d5fef065889f37be025710f4ce6b57aec6ec9 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 28 Aug 2024 11:57:10 -0400 Subject: [PATCH 3/7] snooty --- snooty.toml | 2 -- 1 file changed, 2 deletions(-) diff --git a/snooty.toml b/snooty.toml index e30bbbc3..c7440893 100644 --- a/snooty.toml +++ b/snooty.toml @@ -24,9 +24,7 @@ toc_landing_pages = [ php-library = "MongoDB PHP Library" [constants] - php-library = "MongoDB PHP Library" driver-short = "PHP library" mdb-server = "MongoDB Server" -driver-short = "PHP library" api = "https://www.mongodb.com/docs/php-library/current/reference" From 404bf924f295f3f0398cc55442ac506d5a88cf9d Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 28 Aug 2024 12:01:55 -0400 Subject: [PATCH 4/7] edit --- source/write/insert.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/write/insert.txt b/source/write/insert.txt index 72a41c47..5215664a 100644 --- a/source/write/insert.txt +++ b/source/write/insert.txt @@ -36,7 +36,7 @@ database from the :atlas:`Atlas sample datasets `. To access this from your PHP application, instantiate a ``MongoDB\Client`` that connects to an Atlas cluster and assign the following value to your ``collection`` variable: -.. literalinclude:: /includes/read/insert.php +.. literalinclude:: /includes/write/insert.php :language: php :dedent: :start-after: start-db-coll From 3add653ccfdfa49ce0f5c0779b428797149cf42b Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 28 Aug 2024 14:41:08 -0400 Subject: [PATCH 5/7] JS feedback --- source/write/insert.txt | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/source/write/insert.txt b/source/write/insert.txt index 5215664a..497e3d6e 100644 --- a/source/write/insert.txt +++ b/source/write/insert.txt @@ -53,10 +53,10 @@ with a unique field value. MongoDB allows you to manage this field in two ways: -- You can set this field for each document yourself, ensuring each - ``_id`` field value is unique. -- You can let the driver automatically generate unique ``ObjectId`` - values for each document ``_id``. +- Set the ``_id`` field for each document yourself, ensuring each + value is unique. +- Let the driver automatically generate unique ``ObjectId`` + values for each document ``_id`` field. Unless you can guarantee uniqueness, we recommend letting the driver automatically generate ``_id`` values. @@ -91,7 +91,7 @@ Insert Multiple Documents ------------------------- To add multiple documents to a MongoDB collection, call the ``MongoDB\Collection::insertMany()`` -method and pass an array that stores the documents you want to add. +method and pass an array that contains the documents you want to add. The following example inserts two documents into the ``restaurants`` collection: @@ -117,7 +117,7 @@ you can set in the array: - Description * - ``bypassDocumentValidation`` - - | If set to ``true``, allows the write to opt out of + - | If set to ``true``, allows the write operation to opt out of :manual:`document-level validation `. | Defaults to ``false``. | **Type**: ``bool`` From 6b5d620e8181c2371059e5906295e14c9c79a9fa Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 6 Sep 2024 16:48:16 -0400 Subject: [PATCH 6/7] JT feedback --- source/write/insert.txt | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/source/write/insert.txt b/source/write/insert.txt index 497e3d6e..937bfbc1 100644 --- a/source/write/insert.txt +++ b/source/write/insert.txt @@ -24,9 +24,10 @@ In this guide, you can learn how to use the {+php-library+} to add documents to a MongoDB collection by performing **insert operations**. An insert operation inserts one or more documents into a MongoDB collection. -You can perform an insert operation by using the ``MongoDB\Collection::insertOne()`` -method to insert a single document or the ``MongoDB\Collection::insertMany()`` -method to insert one or more documents. +You can perform an insert operation by using the following methods: + +- ``MongoDB\Collection::insertOne()`` to insert a single document +- ``MongoDB\Collection::insertMany()`` method to insert one or more documents Sample Data ~~~~~~~~~~~ @@ -91,7 +92,7 @@ Insert Multiple Documents ------------------------- To add multiple documents to a MongoDB collection, call the ``MongoDB\Collection::insertMany()`` -method and pass an array that contains the documents you want to add. +method and pass an array that contains the list of documents you want to add. The following example inserts two documents into the ``restaurants`` collection: From 519dc413c4f74efe8b5a7fe810c84e36f4bee5cb Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 9 Sep 2024 10:12:37 -0400 Subject: [PATCH 7/7] JT feedback 2 --- source/write/insert.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/write/insert.txt b/source/write/insert.txt index 937bfbc1..340c9410 100644 --- a/source/write/insert.txt +++ b/source/write/insert.txt @@ -26,7 +26,7 @@ documents to a MongoDB collection by performing **insert operations**. An insert operation inserts one or more documents into a MongoDB collection. You can perform an insert operation by using the following methods: -- ``MongoDB\Collection::insertOne()`` to insert a single document +- ``MongoDB\Collection::insertOne()`` method to insert a single document - ``MongoDB\Collection::insertMany()`` method to insert one or more documents Sample Data