From c658d7185e1e7ad721d2f830a903914ccb63a22c Mon Sep 17 00:00:00 2001
From: Rea Rustagi <85902999+rustagir@users.noreply.github.com>
Date: Mon, 3 Mar 2025 10:46:33 -0500
Subject: [PATCH] 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 e6182b80b469c1953e5b0907eb744d81643e6a3e)
---
 source/aggregation.txt          |   6 +
 source/builders.txt             | 326 ++++++++++++++++++++++++++++++++
 source/includes/builders.php    |  94 +++++++++
 source/index.txt                |   7 +
 source/read/change-streams.txt  |   7 +-
 source/read/specify-a-query.txt |   7 +-
 6 files changed, 445 insertions(+), 2 deletions(-)
 create mode 100644 source/builders.txt
 create mode 100644 source/includes/builders.php

diff --git a/source/aggregation.txt b/source/aggregation.txt
index 2ec29c8f..7fb5c52f 100644
--- a/source/aggregation.txt
+++ b/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
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/source/builders.txt b/source/builders.txt
new file mode 100644
index 00000000..5f6f77ae
--- /dev/null
+++ b/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.
diff --git a/source/includes/builders.php b/source/includes/builders.php
new file mode 100644
index 00000000..3044147b
--- /dev/null
+++ b/source/includes/builders.php
@@ -0,0 +1,94 @@
+<?php
+
+// start-imports
+use MongoDB\Builder\Pipeline;
+use MongoDB\Builder\Query;
+use MongoDB\Builder\Stage;
+// end-imports
+
+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_geospatial->shipwrecks;
+// end-db-coll
+
+// start-find
+// Creates a query filter by using builders and
+// retrieves matching documents
+$docs = $collection->find(
+    Query::query(
+        feature_type: Query::eq('Wrecks - Visible'),
+        coordinates: Query::near(
+            Query::geometry(
+                type: 'Point',
+                coordinates: [-79.9, 9.3],
+            ),
+            maxDistance: 10000,
+        )
+    )
+);
+
+// Prints matching documents
+foreach ($docs as $doc) {
+    echo json_encode($doc), PHP_EOL;
+}
+// end-find
+
+// start-deleteone
+// Creates a query filter by using builders
+// and deletes the first matching document
+$result = $collection->deleteOne(
+    Query::or(
+        Query::query(feature_type: Query::regex('nondangerous$', '')),
+        Query::query(depth: Query::gt(10.0)),
+    )
+);
+
+// Prints number of deleted documents
+echo 'Deleted documents: ', $result->getDeletedCount(), PHP_EOL;
+// end-deleteone
+
+// start-updateone
+// Creates a query filter and an update document by
+// using builders and updates the first matching document
+$result = $collection->updateOne(
+    Query::query(watlev: Query::eq('partly submerged at high water')),
+    new Pipeline(
+        Stage::set(year: 1870),
+    ),
+);
+
+// Prints number of updated documents
+echo 'Updated documents: ', $result->getModifiedCount(), PHP_EOL;
+// end-updateone
+
+// start-cs
+// Creates a pipeline to filter for update operations and return
+// only specific fields
+$pipeline = [
+    Stage::match(operationType: Query::eq('update')),
+    Stage::project(operationType: 1, ns: 1, fullDocument: 1),
+];
+
+// Opens the change stream
+$changeStream = $collection->watch(
+    $pipeline,
+    ['fullDocument' => MongoDB\Operation\Watch::FULL_DOCUMENT_UPDATE_LOOKUP]
+);
+
+// Prints change events based on the pipeline specifications
+for ($changeStream->rewind(); true; $changeStream->next()) {
+    if (! $changeStream->valid()) {
+        continue;
+    }
+    $event = $changeStream->current();
+    echo json_encode($event), PHP_EOL;
+
+    if ($event['operationType'] === 'invalidate') {
+        break;
+    }
+}
+// end-cs
diff --git a/source/index.txt b/source/index.txt
index 3274f5db..bafa053c 100644
--- a/source/index.txt
+++ b/source/index.txt
@@ -15,6 +15,7 @@ MongoDB PHP Library
    Databases & Collections </databases-collections>
    Read Data </read>
    Write Data </write>
+   Operations with Builders </builders>
    CRUD Operations & Replica Sets </read-write-pref>
    Run a Database Command </run-command>
    Data Aggregation </aggregation>
@@ -71,6 +72,12 @@ Write Data to MongoDB
 
 Learn how you can write data to MongoDB in the :ref:`php-write` section.
 
+Operations with Builders
+------------------------
+
+Learn how to use builder classes and factory methods to create queries
+in the :ref:`php-builders` section.
+
 Specify How CRUD Operations Run on Replica Sets
 -----------------------------------------------
 
diff --git a/source/read/change-streams.txt b/source/read/change-streams.txt
index 37bc6340..35cf9f5a 100644
--- a/source/read/change-streams.txt
+++ b/source/read/change-streams.txt
@@ -129,6 +129,11 @@ when update operations occur:
    :language: php
    :dedent:
 
+.. tip:: Operations with Builders
+
+   You can use a builder pattern to create the change stream pipeline.
+   To learn more, see the :ref:`php-builders` guide.
+
 Modify ``watch()`` Behavior
 ---------------------------
 
@@ -265,4 +270,4 @@ guide, see the following API documentation:
 - :phpmethod:`MongoDB\Client::watch()`
 - :phpmethod:`MongoDB\Database::watch()`
 - :phpmethod:`MongoDB\Collection::watch()`
-- :phpmethod:`MongoDB\Collection::updateOne()`
\ No newline at end of file
+- :phpmethod:`MongoDB\Collection::updateOne()`
diff --git a/source/read/specify-a-query.txt b/source/read/specify-a-query.txt
index 53e00809..31f54ea2 100644
--- a/source/read/specify-a-query.txt
+++ b/source/read/specify-a-query.txt
@@ -29,6 +29,11 @@ In a query filter, you can prompt the driver to search for documents that have
 an exact match to your query, or you can compose query filters to express more
 complex matching criteria.
 
+.. tip:: Operations with Builders
+
+   You can use a builder pattern to create filters to use in your queries.
+   To learn more, see the :ref:`php-builders` guide.
+
 Sample Data
 ~~~~~~~~~~~
 
@@ -262,4 +267,4 @@ To learn more about any of the methods or types discussed in this
 guide, see the following API documentation:
 
 - :phpmethod:`MongoDB\Collection::insertMany()`
-- :phpmethod:`MongoDB\Collection::find()`
\ No newline at end of file
+- :phpmethod:`MongoDB\Collection::find()`