DOCSP-43464: operations with builders (#206)

* DOCSP-43464: operations with builders

* fix desc

* shared include fix?

* shared include fix?

* revert

* netlify trigger

* small fix

* LM PR fixes 1

* LM PR fixes 2

* link fix

* reformat comments

* JT tech review 2

* fix code example

* JT tech review comments

(cherry picked from commit e6182b8)

Author: rustagir

source/aggregation.txt

@@ -228,6 +228,12 @@ The examples in this section are adapted from the {+mdb-server+} manual.
 Each example provides a link to the sample data that you can insert into
 your database to test the aggregation operation.
 
+.. tip:: Operations with Builders
+    
+   You can use builders to support non-aggregation operations such as
+   find and update operations. To learn more, see the :ref:`php-builders`
+   guide.
+
 Filter and Group Example
 ~~~~~~~~~~~~~~~~~~~~~~~~
 

source/builders.txt

@@ -0,0 +1,326 @@
+.. _php-builders:
+
+========================
+Operations with Builders
+========================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: aggregation, query, code example, type-safe
+
+Overview
+--------
+
+In this guide, you can learn about the **builder classes**
+that the {+library-short+} provides to create types used in your
+operations. You can use the builder classes and factory methods from the
+Aggregation Builder feature to create filters for other operations such
+as find, update, and delete operations. To learn more about the Aggregation
+Builder, see the :ref:`php-aggregation-builder-api` section of the
+Aggregation guide. 
+
+Using builders to create queries helps you identify errors at compile
+time and avoid them at runtime. This guide provides information on
+builder classes that you can use to perform the following tasks:
+
+- :ref:`php-builders-filter`
+- :ref:`php-builders-update`
+- :ref:`php-builders-changestream`
+
+.. note:: Setting Operation Options
+
+   You cannot specify options by using factory methods for the equivalent
+   aggregation stages. For example, you cannot use the ``Stage::limit()`` method
+   to set a returned documents limit on your find operation. You must specify
+   options by using the string-based syntax, as shown in the following code:
+   
+   .. code-block:: php
+   
+      $options = [
+          'limit' => 5,
+          '<option name>' => '<specification>',
+      ];
+
+This guide provides examples of how to use builders in non-aggregation
+operations. To view aggregation examples, see the :ref:`php-aggregation`
+guide.
+
+Sample Data
+~~~~~~~~~~~
+
+The examples in this guide use the ``shipwrecks`` collection in the
+``sample_geospatial`` 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/builders.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.
+
+Import Builder Classes
+----------------------
+
+To run the examples in this guide, you must import the following classes
+into your application:
+
+.. literalinclude:: /includes/builders.php
+   :language: php
+   :dedent:
+   :start-after: start-imports
+   :end-before: end-imports
+
+.. _php-builders-filter:
+
+Create a Filter
+---------------
+
+You can use factory methods from the ``Query`` builder class to create
+filter definitions to use in find, update, and delete operations. When
+using the ``Query::query()`` factory method to create queries, you can
+use named argument syntax and implement type safety. To learn more about
+creating filters, see the :ref:`php-specify-query` guide.
+
+The following steps describe how to create a filter definition by using
+builders:
+
+1. Call the ``Query::query()`` method to create a query.
+   
+#. Pass the field name to filter on and a factory method from the
+   ``Query`` class. You can pass one or more pairs of field names and
+   criteria in the filter to apply multiple clauses.
+
+The following code shows the template to create a filter definition by
+using builders:
+
+.. code-block:: php
+    
+   $filter = Query::query(
+       <field name>: Query::<factory method>(<parameters>),
+       <field name>: Query::<factory method>(<parameters>),
+       ...
+   );
+
+To combine query criteria by using logical query operators
+(``$and``, ``$or``, ``$not``, ``$nor``), you can use the following
+query template:
+
+.. code-block:: php
+    
+   $filter = Query::<logical operator>(
+       Query::query(<field name>: Query::<factory method>(<parameters>)),
+       Query::query(<field name>: Query::<factory method>(<parameters>)),
+       ...
+   );
+
+To learn more, see :manual:`Logical Query Operators
+</reference/operator/query-logical/>` in the {+mdb-server+} manual.
+
+The following sections provide examples that use builders to create
+filter definitions for different operations.
+
+Retrieve Example
+~~~~~~~~~~~~~~~~
+
+This example performs the following actions:
+
+- Uses the ``Query::eq()`` factory method to match documents in which
+  the ``feature_type`` field value is ``'Wrecks - Visible'``
+- Uses the ``Query::near()`` factory method to match documents in which
+  the ``coordinates`` location field is within ``10000`` meters of the
+  specified coordinates
+- Calls the :phpmethod:`MongoDB\Collection::find()`
+  method to retrieve the matching documents
+- Prints the matching documents
+
+.. io-code-block::
+   :copyable:   
+
+   .. input:: /includes/builders.php
+      :start-after: start-find
+      :end-before: end-find
+      :language: php
+      :dedent:
+
+   .. output::
+      :language: json
+      :visible: false
+
+      {"_id":...,"feature_type":"Wrecks - Visible","coordinates":[-79.9137115,9.3390503],...}
+      {"_id":...,"feature_type":"Wrecks - Visible","coordinates":[-79.9357223,9.3340302],...}
+      {"_id":...,"feature_type":"Wrecks - Visible","coordinates":[-79.9081268,9.3547792],...}
+      // Results truncated
+
+To learn more about find operations, see the :ref:`php-retrieve` guide.
+
+Delete Example
+~~~~~~~~~~~~~~
+
+This example performs the following actions:
+
+- Uses the ``Query::or()`` factory method to match documents that
+  satisfy the either of the following query clauses:
+  
+  - Clause that uses the ``Query::regex()`` factory method to check if
+    the ``feature_type`` field value contains the string ``'nondangerous'``
+  
+  - Clause that uses the ``Query::gt()`` factory method to check if the
+    ``depth`` field value is greater than ``10.0``
+
+- Calls the :phpmethod:`MongoDB\Collection::deleteOne()`
+  method to delete the first matching document
+
+- Prints the number of deleted documents
+
+.. io-code-block::
+   :copyable:   
+
+   .. input:: /includes/builders.php
+      :start-after: start-deleteone
+      :end-before: end-deleteone
+      :language: php
+      :dedent:
+
+   .. output::
+      :language: none
+      :visible: false
+
+      Deleted documents: 1
+
+To learn more about delete operations, see the :ref:`php-write-delete`
+guide.
+
+.. _php-builders-update:
+
+Define an Update Document
+-------------------------
+
+You can use factory methods from the ``Stage`` builder class to create
+update documents. Update documents describe the updates to make to target
+documents. To learn more about updating documents, see the
+:ref:`php-write-update` guide.
+
+The following steps describe how to create an update document by using
+builders:
+
+1. Create a ``Pipeline`` instance.
+   
+#. Pass one or more stages by calling methods from the ``Stage`` class
+   such as ``Stage::set()`` and passing field names and values.
+
+The following code shows the template to define an update by using
+builders:
+
+.. code-block:: php
+    
+   $update = new Pipeline(
+       Stage::set(<field name>: <value>),
+       Stage::set(<field name>: <value>),
+       ...
+   );
+
+This example performs the following actions:
+
+- Uses the ``Query::eq()`` factory method to match documents in which
+  the ``watlev`` field value is ``'partly submerged at high water'``
+- Uses the ``Stage::set()`` method to set the ``year`` field to ``1870``
+- Calls the :phpmethod:`MongoDB\Collection::updateOne()`
+  method to perform the update
+- Prints the number of updated documents
+
+.. io-code-block::
+   :copyable:   
+
+   .. input:: /includes/builders.php
+      :start-after: start-updateone
+      :end-before: end-updateone
+      :language: php
+      :dedent:
+
+   .. output::
+      :language: none
+      :visible: false
+
+      Updated documents: 1
+
+.. _php-builders-changestream:
+
+Modify Change Stream Output
+---------------------------
+
+You can use factory methods from the ``Stage`` class to modify a change
+stream's output by creating a pipeline. To learn more about change
+streams, see the :ref:`php-change-streams` guide.
+
+The following steps describe how to create a change stream filter by
+using builders:
+
+1. Create an array.
+   
+#. Pass one or more ``$match`` stages by calling factory methods from
+   the ``Stage`` class and the required parameters.
+
+The following code shows the template to modify change stream output by
+using builders:
+
+.. code-block:: php
+
+   $pipeline = [
+       Stage::<factory method>(...),
+       Stage::<factory method>(...),
+       ...
+   ];
+
+You can pass this pipeline to the following methods:
+
+- :phpmethod:`MongoDB\Client::watch()`
+- :phpmethod:`MongoDB\Database::watch()`
+- :phpmethod:`MongoDB\Collection::watch()`
+
+This example performs the following actions:
+
+- Uses the ``Stage::match()`` method to filter for only change
+  events for update operations
+- Uses the ``Stage::project()`` method to output only the
+  ``operationType``, ``ns`` (namespace), and ``fullDocument`` fields
+- Calls the :phpmethod:`MongoDB\Collection::watch()`
+  method to open the change stream and sets the ``fullDocument`` option
+  to output the full document after update
+- Prints change events as they occur
+
+.. io-code-block::
+   :copyable:   
+
+   .. input:: /includes/builders.php
+      :start-after: start-cs
+      :end-before: end-cs
+      :language: php
+      :dedent:
+
+   .. output::
+      :language: json
+      :visible: false
+
+      {
+        "_id":...,
+        "operationType":"update",
+        "fullDocument":{"_id":...,"feature_type":"Wrecks - Visible",...},
+        "ns":{"db":"sample_geospatial","coll":"shipwrecks"}
+      }
+
+To learn more about the information provided by change events, see
+:manual:`Change Events </reference/change-events>` in the {+mdb-server+} manual.