DOCSP-41966: Write operations landing

snooty.toml

@@ -18,6 +18,7 @@ toc_landing_pages = [
     "/reference/class/MongoDBModelDatabaseInfo",
     "/reference/class/MongoDBModelIndexInfo",
     "/get-started",
+    "/write",
 ]
 
 [substitutions]

source/includes/usage-examples/write-code-examples.php

@@ -0,0 +1,116 @@
+<?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);
+$collection = $client->db->coll;
+
+// Inserts one document that stores the specified values
+// start-insert-one
+$result = $collection->insertOne([
+    '<field name 1>' => '<value 1>',
+    '<field name 2>' => '<value 2>',
+]);
+// end-insert-one
+
+// Inserts multiple documents that store the specified values
+// start-insert-multiple
+$result = $collection->insertMany(
+    [
+        '<field name 1>' => '<value 1>',
+        '<field name 2>' => '<value 2>',
+    ],
+    [
+        '<field name 1>' => '<value 1>',
+        '<field name 2>' => '<value 2>',
+    ],
+);
+// end-insert-multiple
+
+// Updates a document that matches the specified criteria
+// start-update-one
+$result = $collection->updateOne(
+    ['<field to match>' => '<value to match>'],
+    ['$set' => ['<field name>' => '<value>']],
+);
+// end-update-one
+
+// Updates all documents that match the specified criteria
+// start-update-multiple
+$result = $collection->updateMany(
+    ['<field to match>' => '<value to match>'],
+    ['$set' => ['<field name>' => '<value>']],
+);
+// end-update-multiple
+
+// start-replace-one
+$result = $collection->replaceOne(
+    ['<field to match>' => '<value to match>'],
+    [
+        '<new field 1>' => '<value 1>',
+        '<new field 2>' => '<value 2>',
+    ],
+);
+// end-replace-one
+
+// Deletes a document that matches the specified criteria
+// start-delete-one
+$result = $collection->deleteOne(['<field name>' => '<value>']);
+// end-delete-one
+
+// Deletes all documents that match the specified criteria
+// start-delete-multiple
+$result = $collection->deleteMany(['<field name>' => '<value>']);
+// end-delete-multiple
+
+// Runs a bulk operation based on the instructions in each array entry
+// start-bulk-write
+$result = $collection->bulkWrite(
+    [
+        [
+            'insertOne' => [
+                ['<field name>' => '<value>'], 
+            ],
+        ],
+        [
+            'replaceOne' => [
+                ['<field to match>' => '<value to match>'],
+                [
+                    '<first new field>' => '<value>',
+                    '<second new field>' => '<value>',
+                ],
+            ],
+        ],
+        [
+            'updateOne' => [
+                ['<field to match>' => '<value to match>'],
+                ['$set' => ['<field to update>' => '<value to update>']],
+            ],
+        ],
+        [
+            'updateMany' => [
+                ['<field to match>' => '<value to match>'],
+                ['$set' => ['<field to update>' => '<value to update>']],
+            ],
+        ],
+        [
+            'deleteOne' => [
+                ['<field name>' => '<value>'],
+            ],
+        ],
+        [
+            'deleteMany' => [
+                ['<field name>' => '<value>'],
+            ],
+        ],
+    ]
+);
+// end-bulk-write
+
+// Stores a file in a GridFS bucket and writes data to the file
+// start-gridfs-upload
+$bucket = $client->selectDatabase('<database name>')->selectGridFSBucket();
+$stream = $bucket->openUploadStream('<file name>');
+fwrite($stream, '<data>');
+fclose($stream);
+// end-gridfs-upload

source/write.txt

@@ -4,6 +4,20 @@
 Write Data to MongoDB
 =====================
 
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :description: Learn how to use the PHP Library to write data to MongoDB.
+   :keywords: usage examples, save, crud, create, code example
+
 .. toctree::
    :titlesonly:
    :maxdepth: 1
@@ -12,3 +26,161 @@ Write Data to MongoDB
    /write/replace
    /write/insert
    /write/update
+
+Overview
+--------
+
+On this page, you can see copyable code examples that show common
+{+php-library+} methods for writing data to MongoDB.
+
+.. tip::
+
+   To learn more about any of the methods shown on this page, see the link
+   provided in each section.
+
+To use an example from this page, copy the code example into the
+:ref:`sample application <php-write-sample>` or your own application.
+Make sure to set the ``MONGODB_URI`` environment variable to the
+connection string for your MongoDB deployment, and replace the
+``<database>`` and ``<collection>`` placeholders with values for your
+target namespace.
+
+.. _php-write-sample:
+
+.. include:: /includes/usage-examples/sample-app-intro.rst
+
+.. literalinclude:: /includes/usage-examples/sample-app.php
+   :language: php
+   :dedent:
+   :linenos:
+   :emphasize-lines: 10-12
+
+Insert One
+----------
+
+The following code shows how to insert a single document into a collection:
+
+.. literalinclude:: /includes/usage-examples/write-code-examples.php
+   :start-after: start-insert-one
+   :end-before: end-insert-one
+   :language: php
+   :dedent:
+
+To learn more about the ``MongoDB\Collection::insertOne()`` method, see the
+:ref:`Insert Documents <php-write-insert>` guide.
+
+Insert Multiple
+---------------
+
+The following code shows how to insert multiple documents into a collection:
+
+.. literalinclude:: /includes/usage-examples/write-code-examples.php
+   :start-after: start-insert-multiple
+   :end-before: end-insert-multiple
+   :language: php
+   :dedent:
+
+To learn more about the ``MongoDB\Collection::insertMany()`` method, see the
+:ref:`Insert Documents <php-write-insert>` guide.
+
+Update One
+----------
+
+The following code shows how to update a single document in a collection by creating
+or editing a field:
+
+.. literalinclude:: /includes/usage-examples/write-code-examples.php
+   :start-after: start-update-one
+   :end-before: end-update-one
+   :language: php
+   :dedent:
+
+To learn more about the ``MongoDB\Collection::updateOne()`` method, see the
+:ref:`Update Documents <php-write-update>` guide.
+
+Update Multiple
+---------------
+
+The following code shows how to update multiple documents in a collection by creating
+or editing a field:
+
+.. literalinclude:: /includes/usage-examples/write-code-examples.php
+   :start-after: start-update-multiple
+   :end-before: end-update-multiple
+   :language: php
+   :dedent:
+
+To learn more about the ``MongoDB\Collection::updateMany()`` method, see the
+:ref:`Update Documents <php-write-update>` guide.
+
+Replace One
+-----------
+
+The following code shows how to replace a single document in a collection
+with another document:
+
+.. literalinclude:: /includes/usage-examples/write-code-examples.php
+   :start-after: start-replace-one
+   :end-before: end-replace-one
+   :language: php
+   :dedent:
+
+To learn more about the ``MongoDB\Collection::replaceOne()`` method, see the
+:ref:`Replace Documents <php-write-replace>` guide.
+
+Delete One
+----------
+
+The following code shows how to delete a single document in a collection:
+
+.. literalinclude:: /includes/usage-examples/write-code-examples.php
+   :start-after: start-delete-one
+   :end-before: end-delete-one
+   :language: php
+   :dedent:
+
+To learn more about the ``MongoDB\Collection::deleteOne()`` method, see the
+:ref:`Delete Documents <php-write-delete>` guide.
+
+Delete Multiple
+---------------
+
+The following code shows how to delete multiple documents in a collection:
+
+.. literalinclude:: /includes/usage-examples/write-code-examples.php
+   :start-after: start-delete-multiple
+   :end-before: end-delete-multiple
+   :language: php
+   :dedent:
+
+To learn more about the ``MongoDB\Collection::deleteMany()`` method, see the
+:ref:`Delete Documents <php-write-delete>` guide.
+
+Bulk Write
+----------
+
+The following code shows how to perform multiple write operations in a single bulk
+operation:
+
+.. literalinclude:: /includes/usage-examples/write-code-examples.php
+   :start-after: start-bulk-write
+   :end-before: end-bulk-write
+   :language: php
+   :dedent:
+
+To learn more about the ``MongoDB\Collection::bulkWrite()`` method, see the
+:ref:`Bulk Write <php-bulk-write>` guide.
+
+Store Large Files
+-----------------
+
+The following code shows how to store files in a GridFS bucket by
+creating an upload stream:
+
+.. literalinclude:: /includes/usage-examples/write-code-examples.php
+   :start-after: start-gridfs-upload
+   :end-before: end-gridfs-upload
+   :language: php
+   :dedent:
+
+To learn more about GridFS, see the :ref:`Store Large Files <php-gridfs>` guide.