DOCSP-41967: Insert documents

snooty.toml

@@ -24,7 +24,6 @@ toc_landing_pages = [
 php-library = "MongoDB PHP Library"
 
 [constants]
-
 php-library = "MongoDB PHP Library"
 driver-short = "PHP library"
 stable-api = "Stable API"

source/includes/write/insert.php

@@ -0,0 +1,37 @@
+<?php
+
+require 'vendor/autoload.php';
+
+$uri = getenv('MONGODB_URI') ?: throw new RuntimeException('Set the MONGODB_URI variable to your Atlas URI that connects to the sample dataset');
+$client = new MongoDB\Client($uri);
+
+// start-db-coll
+$collection = $client->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
+

source/write.txt

@@ -8,4 +8,5 @@ Write Data to MongoDB
    :titlesonly:
    :maxdepth: 1
 
-   /write/update
+   /write/insert
+   /write/update

source/write/insert.txt

@@ -0,0 +1,172 @@
+.. _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 following methods:
+
+- ``MongoDB\Collection::insertOne()`` method to insert a single document
+- ``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 </sample-data>`. 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/write/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 </getting-started>` 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:
+
+- 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.
+
+.. 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 </core/index-unique/>` guide in the {+mdb-server+} manual.
+
+To learn more about document structure and rules, see the
+:manual:`Documents </core/document>` 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 contains the list of 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 operation to opt out of
+         :manual:`document-level validation </core/schema-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 </reference/command/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/>`__