From c74e04ab3cc53ea792affc6448132d2109603c73 Mon Sep 17 00:00:00 2001
From: rustagir <rea.rustagi@mongodb.com>
Date: Tue, 18 Feb 2025 09:56:58 -0500
Subject: [PATCH 01/14] DOCSP-43464: operations with builders

---
 source/aggregation.txt          |   6 +
 source/builders.txt             | 304 ++++++++++++++++++++++++++++++++
 source/includes/builders.php    |  76 ++++++++
 source/index.txt                |   7 +
 source/read/change-streams.txt  |   7 +-
 source/read/specify-a-query.txt |   7 +-
 6 files changed, 405 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..477e87e4
--- /dev/null
+++ b/source/builders.txt
@@ -0,0 +1,304 @@
+.. _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
+:ref:`php-aggregation-builder-api` feature to create filters for other
+operations such as find, update, and delete operations.
+
+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 for the following tasks:
+
+- :ref:`Creating a filter definition <php-builders-filter>`
+- :ref:`Defining an update operation <php-builders-update>`
+- :ref:`Filtering a change stream <php-builders-changestream>`
+
+.. note:: 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. 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. Instantiate the ``QueryInterface`` by calling the ``Query::query()``
+   method.
+   
+#. Pass the field name to compare and a factory method from the
+   ``Query`` class. You can pass one or more pairs of field names and
+   criteria to the ``QueryInterface``.
+
+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>),
+       ...
+   );
+
+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 ``feature_type`` field value is ``'Wrecks - Visible'``
+- 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::regex()`` factory method to match documents in which
+  the ``feature_type`` field value contains the string ``'nondangerous'``
+- 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 update
+or create field values in your update operations. To learn more about
+updating documents, see the :ref:`php-write-update` guide.
+
+.. important::
+    
+   The only update operation that you can express by using builders uses
+   the ``$set`` operator. This operator allows you to replace the value of
+   a field with a specified value or create a new field that has a specified
+   value. To learn more, see the :manual:`$set </reference/operator/update/set/>`
+   reference in the {+mdb-server+} manual.
+
+The following steps describe how to create an update document by using
+builders:
+
+1. Create a ``Pipeline`` instance.
+   
+#. Pass one or more ``$set`` stages by calling the ``Stage::set()``
+   method and passing a field name and a value.
+
+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 builders to specify an update that sets
+  sets 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 = new 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 update change
+  events
+- Uses the ``Stage::project()`` method to output only the specified change
+  event fields
+- Calls the :phpmethod:`MongoDB\Collection::watch()`
+  method to open the change stream with the 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"}
+      }
diff --git a/source/includes/builders.php b/source/includes/builders.php
new file mode 100644
index 00000000..cebf7ef4
--- /dev/null
+++ b/source/includes/builders.php
@@ -0,0 +1,76 @@
+<?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
+$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,
+    )
+));
+
+foreach ($docs as $doc) {
+    echo json_encode($doc), PHP_EOL;
+}
+// end-find
+
+// start-deleteone
+$result = $collection->deleteOne(Query::query(
+    feature_type: Query::regex('nondangerous$', '')
+));
+
+echo 'Deleted documents: ', $result->getDeletedCount(), PHP_EOL;
+// end-deleteone
+
+// start-updateone
+$result = $collection->updateOne(
+    Query::query(watlev: Query::eq('partly submerged at high water')),
+    new Pipeline(
+        Stage::set(year: 1870),
+    ),
+);
+
+echo 'Updated documents: ', $result->getModifiedCount(), PHP_EOL;
+// end-updateone
+
+// start-cs
+$pipeline = [
+    Stage::match(operationType: Query::eq('update')),
+    Stage::project(operationType: 1, ns: 1, fullDocument: 1),
+];
+
+$changeStream = $collection->watch(
+    $pipeline,
+    ['fullDocument' => MongoDB\Operation\Watch::FULL_DOCUMENT_UPDATE_LOOKUP]
+);
+
+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()`

From b6022a9f7bec591f37ec5aae457da2d98d4c5372 Mon Sep 17 00:00:00 2001
From: rustagir <rea.rustagi@mongodb.com>
Date: Tue, 18 Feb 2025 10:20:48 -0500
Subject: [PATCH 02/14] fix desc

---
 source/builders.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/source/builders.txt b/source/builders.txt
index 477e87e4..3f2e7683 100644
--- a/source/builders.txt
+++ b/source/builders.txt
@@ -123,7 +123,8 @@ 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 ``feature_type`` field value is ``'Wrecks - Visible'``
+  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

From c37d49e16258b04b124ba456f2661d381848724f Mon Sep 17 00:00:00 2001
From: rustagir <rea.rustagi@mongodb.com>
Date: Tue, 18 Feb 2025 10:35:56 -0500
Subject: [PATCH 03/14] shared include fix?

---
 source/write/transaction.txt | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/source/write/transaction.txt b/source/write/transaction.txt
index 5a929cc0..d74356f2 100644
--- a/source/write/transaction.txt
+++ b/source/write/transaction.txt
@@ -163,6 +163,8 @@ completes the following actions:
 
 .. sharedinclude:: dbx/transactions-parallelism.rst
 
+   .. replacement:: driver-specific-content
+
 Additional Information
 ----------------------
 

From ec35439fc57d2c892506d9197b416b11d4b52c29 Mon Sep 17 00:00:00 2001
From: rustagir <rea.rustagi@mongodb.com>
Date: Tue, 18 Feb 2025 10:42:57 -0500
Subject: [PATCH 04/14] shared include fix?

---
 source/write/transaction.txt | 44 +++++++++++++++++++-----------------
 1 file changed, 23 insertions(+), 21 deletions(-)

diff --git a/source/write/transaction.txt b/source/write/transaction.txt
index d74356f2..fe96166a 100644
--- a/source/write/transaction.txt
+++ b/source/write/transaction.txt
@@ -92,24 +92,24 @@ following table describes these methods:
    :header-rows: 1
 
    * - Method
-     - Description
+	 - Description
 
    * - ``startTransaction()``
-     - | Starts a new transaction on this session. The session
-         must be passed into each operation within the transaction, or
-         the operation will run outside of the transaction.
-       |
-       | You can set transaction options by passing an options parameter.
+	 - | Starts a new transaction on this session. The session
+		 must be passed into each operation within the transaction, or
+		 the operation will run outside of the transaction.
+	   |
+	   | You can set transaction options by passing an options parameter.
 
    * - ``commitTransaction()``
-     - | Commits the active transaction for this session. This method returns an
-         error if there is no active transaction for the session, the
-         transaction was previously ended, or if there is a write conflict.
+	 - | Commits the active transaction for this session. This method returns an
+		 error if there is no active transaction for the session, the
+		 transaction was previously ended, or if there is a write conflict.
 
    * - ``abortTransaction()``
-     - | Ends the active transaction for this session. This method returns an
-         error if there is no active transaction for the session or if the
-         transaction was committed or ended.
+	 - | Ends the active transaction for this session. This method returns an
+		 error if there is no active transaction for the session or if the
+		 transaction was committed or ended.
 
 .. _php-txn-example:
 
@@ -148,22 +148,24 @@ completes the following actions:
    :copyable:
 
    .. input:: /includes/write/transaction.php
-      :language: php
-      :dedent:
-      :start-after: begin-txn
-      :end-before: end-txn
-      :emphasize-lines: 1, 4
+	  :language: php
+	  :dedent:
+	  :start-after: begin-txn
+	  :end-before: end-txn
+	  :emphasize-lines: 1, 4
 
    .. output:: 
-      :language: console
-      :visible: false
+	  :language: console
+	  :visible: false
 
-      Successfully performed transaction!
-      Summary: SAVINGS +1000 CHECKING -1000
+	  Successfully performed transaction!
+	  Summary: SAVINGS +1000 CHECKING -1000
 
 .. sharedinclude:: dbx/transactions-parallelism.rst
 
    .. replacement:: driver-specific-content
+	  
+	   
 
 Additional Information
 ----------------------

From 549d91470e9d53b7c6e92965e1a677e08ca6b822 Mon Sep 17 00:00:00 2001
From: rustagir <rea.rustagi@mongodb.com>
Date: Tue, 18 Feb 2025 10:57:45 -0500
Subject: [PATCH 05/14] revert

---
 source/write/transaction.txt | 46 ++++++++++++++++--------------------
 1 file changed, 21 insertions(+), 25 deletions(-)

diff --git a/source/write/transaction.txt b/source/write/transaction.txt
index fe96166a..5a929cc0 100644
--- a/source/write/transaction.txt
+++ b/source/write/transaction.txt
@@ -92,24 +92,24 @@ following table describes these methods:
    :header-rows: 1
 
    * - Method
-	 - Description
+     - Description
 
    * - ``startTransaction()``
-	 - | Starts a new transaction on this session. The session
-		 must be passed into each operation within the transaction, or
-		 the operation will run outside of the transaction.
-	   |
-	   | You can set transaction options by passing an options parameter.
+     - | Starts a new transaction on this session. The session
+         must be passed into each operation within the transaction, or
+         the operation will run outside of the transaction.
+       |
+       | You can set transaction options by passing an options parameter.
 
    * - ``commitTransaction()``
-	 - | Commits the active transaction for this session. This method returns an
-		 error if there is no active transaction for the session, the
-		 transaction was previously ended, or if there is a write conflict.
+     - | Commits the active transaction for this session. This method returns an
+         error if there is no active transaction for the session, the
+         transaction was previously ended, or if there is a write conflict.
 
    * - ``abortTransaction()``
-	 - | Ends the active transaction for this session. This method returns an
-		 error if there is no active transaction for the session or if the
-		 transaction was committed or ended.
+     - | Ends the active transaction for this session. This method returns an
+         error if there is no active transaction for the session or if the
+         transaction was committed or ended.
 
 .. _php-txn-example:
 
@@ -148,25 +148,21 @@ completes the following actions:
    :copyable:
 
    .. input:: /includes/write/transaction.php
-	  :language: php
-	  :dedent:
-	  :start-after: begin-txn
-	  :end-before: end-txn
-	  :emphasize-lines: 1, 4
+      :language: php
+      :dedent:
+      :start-after: begin-txn
+      :end-before: end-txn
+      :emphasize-lines: 1, 4
 
    .. output:: 
-	  :language: console
-	  :visible: false
+      :language: console
+      :visible: false
 
-	  Successfully performed transaction!
-	  Summary: SAVINGS +1000 CHECKING -1000
+      Successfully performed transaction!
+      Summary: SAVINGS +1000 CHECKING -1000
 
 .. sharedinclude:: dbx/transactions-parallelism.rst
 
-   .. replacement:: driver-specific-content
-	  
-	   
-
 Additional Information
 ----------------------
 

From c139265f8cf1db9ea2e8bfcb67882f23c01f6354 Mon Sep 17 00:00:00 2001
From: rustagir <rea.rustagi@mongodb.com>
Date: Tue, 18 Feb 2025 11:32:30 -0500
Subject: [PATCH 06/14] netlify trigger


From 5639d317e90ea1dc978183a888105262349c5ea9 Mon Sep 17 00:00:00 2001
From: rustagir <rea.rustagi@mongodb.com>
Date: Tue, 18 Feb 2025 12:12:49 -0500
Subject: [PATCH 07/14] small fix

---
 source/builders.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/source/builders.txt b/source/builders.txt
index 3f2e7683..df6e88cb 100644
--- a/source/builders.txt
+++ b/source/builders.txt
@@ -260,12 +260,12 @@ The following code shows the template to modify change stream output by
 using builders:
 
 .. code-block:: php
-    
-   $pipeline = new Pipeline(
+
+   $pipeline = [
        Stage::<factory method>(...),
        Stage::<factory method>(...),
        ...
-   );
+   ];
 
 You can pass this pipeline to the following methods:
 

From 61bf47f965bec4446cc4dc4fe05e762b6e009960 Mon Sep 17 00:00:00 2001
From: rustagir <rea.rustagi@mongodb.com>
Date: Wed, 19 Feb 2025 12:17:05 -0500
Subject: [PATCH 08/14] LM PR fixes 1

---
 source/builders.txt          | 31 ++++++++++++++++---------------
 source/includes/builders.php | 11 +++++++++++
 2 files changed, 27 insertions(+), 15 deletions(-)

diff --git a/source/builders.txt b/source/builders.txt
index df6e88cb..23ae0ee2 100644
--- a/source/builders.txt
+++ b/source/builders.txt
@@ -23,19 +23,21 @@ 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
-:ref:`php-aggregation-builder-api` feature to create filters for other
-operations such as find, update, and delete operations.
+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 for the following tasks:
+builder classes that you can use to perform the following tasks:
 
-- :ref:`Creating a filter definition <php-builders-filter>`
-- :ref:`Defining an update operation <php-builders-update>`
-- :ref:`Filtering a change stream <php-builders-changestream>`
+- :ref:`php-builders-filter`
+- :ref:`php-builders-update`
+- :ref:`php-builders-changestream`
+
+.. note:: Setting Operation Options
 
-.. note:: 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
@@ -97,7 +99,7 @@ builders:
 1. Instantiate the ``QueryInterface`` by calling the ``Query::query()``
    method.
    
-#. Pass the field name to compare and a factory method from the
+#. 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 to the ``QueryInterface``.
 
@@ -187,8 +189,8 @@ You can use factory methods from the ``Stage`` builder class to update
 or create field values in your update operations. To learn more about
 updating documents, see the :ref:`php-write-update` guide.
 
-.. important::
-    
+.. important:: Only $set Operator Supported
+
    The only update operation that you can express by using builders uses
    the ``$set`` operator. This operator allows you to replace the value of
    a field with a specified value or create a new field that has a specified
@@ -218,8 +220,7 @@ 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 builders to specify an update that sets
-  sets the ``year`` field to ``1870``
+- Uses the ``Stage::set()`` method to update the ``year`` field to ``1870``
 - Calls the :phpmethod:`MongoDB\Collection::updateOne()`
   method to perform the update
 - Prints the number of updated documents
@@ -280,8 +281,8 @@ This example performs the following actions:
 - Uses the ``Stage::project()`` method to output only the specified change
   event fields
 - Calls the :phpmethod:`MongoDB\Collection::watch()`
-  method to open the change stream with the option to output the full
-  document after update
+  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::
diff --git a/source/includes/builders.php b/source/includes/builders.php
index cebf7ef4..5673f163 100644
--- a/source/includes/builders.php
+++ b/source/includes/builders.php
@@ -16,6 +16,8 @@
 // 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(
@@ -27,12 +29,15 @@
     )
 ));
 
+/* 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::query(
     feature_type: Query::regex('nondangerous$', '')
 ));
@@ -41,6 +46,8 @@
 // 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(
@@ -52,16 +59,20 @@
 // end-updateone
 
 // start-cs
+/* Creates a pipeline to filter for update operations and returns
+   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;

From c854ffdd1ba0d69e0244c2cdb93fbee1f0486549 Mon Sep 17 00:00:00 2001
From: rustagir <rea.rustagi@mongodb.com>
Date: Wed, 19 Feb 2025 15:05:29 -0500
Subject: [PATCH 09/14] LM PR fixes 2

---
 source/builders.txt | 24 ++++++++++++++----------
 1 file changed, 14 insertions(+), 10 deletions(-)

diff --git a/source/builders.txt b/source/builders.txt
index 23ae0ee2..dbd4c12b 100644
--- a/source/builders.txt
+++ b/source/builders.txt
@@ -185,13 +185,14 @@ guide.
 Define an Update Document
 -------------------------
 
-You can use factory methods from the ``Stage`` builder class to update
-or create field values in your update operations. To learn more about
-updating documents, see the :ref:`php-write-update` guide.
+You can use the ``Stage::set()`` factory method when creating 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.
 
-.. important:: Only $set Operator Supported
+.. important:: Only $set Operator Supported in Update Documents
 
-   The only update operation that you can express by using builders uses
+   The only update operation that you can express with builders uses
    the ``$set`` operator. This operator allows you to replace the value of
    a field with a specified value or create a new field that has a specified
    value. To learn more, see the :manual:`$set </reference/operator/update/set/>`
@@ -220,7 +221,7 @@ 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 update the ``year`` field to ``1870``
+- 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
@@ -276,10 +277,10 @@ You can pass this pipeline to the following methods:
 
 This example performs the following actions:
 
-- Uses the ``Stage::match()`` method to filter for only update change
-  events
-- Uses the ``Stage::project()`` method to output only the specified change
-  event fields
+- 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
@@ -304,3 +305,6 @@ This example performs the following actions:
         "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.

From 763f4f008473a6c9efbd6241c7572743d62fd86a Mon Sep 17 00:00:00 2001
From: rustagir <rea.rustagi@mongodb.com>
Date: Wed, 19 Feb 2025 15:23:24 -0500
Subject: [PATCH 10/14] link fix

---
 source/builders.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/builders.txt b/source/builders.txt
index dbd4c12b..a587fdaa 100644
--- a/source/builders.txt
+++ b/source/builders.txt
@@ -307,4 +307,4 @@ This example performs the following actions:
       }
 
 To learn more about the information provided by change events, see
-:manual:`Change Events <reference/change-events/>` in the {+mdb-server+} manual.
+:manual:`Change Events </reference/change-events>` in the {+mdb-server+} manual.

From 1ba5a81307f1e31aa1de0a00a18488ebb46cc683 Mon Sep 17 00:00:00 2001
From: rustagir <rea.rustagi@mongodb.com>
Date: Wed, 19 Feb 2025 16:56:32 -0500
Subject: [PATCH 11/14] reformat comments

---
 source/includes/builders.php | 24 +++++++++++++-----------
 1 file changed, 13 insertions(+), 11 deletions(-)

diff --git a/source/includes/builders.php b/source/includes/builders.php
index 5673f163..e8988513 100644
--- a/source/includes/builders.php
+++ b/source/includes/builders.php
@@ -16,8 +16,8 @@
 // end-db-coll
 
 // start-find
-/* Creates a query filter by using builders and
-   retrieves matching documents */
+// 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(
@@ -29,25 +29,26 @@
     )
 ));
 
-/* Prints matching documents */
+// 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 */
+// Creates a query filter by using builders
+// and deletes the first matching document
 $result = $collection->deleteOne(Query::query(
     feature_type: Query::regex('nondangerous$', '')
 ));
 
+// 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 */
+// 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(
@@ -55,24 +56,25 @@
     ),
 );
 
+// 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 returns
-   only specific fields */
+// 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 */
+// Opens the change stream
 $changeStream = $collection->watch(
     $pipeline,
     ['fullDocument' => MongoDB\Operation\Watch::FULL_DOCUMENT_UPDATE_LOOKUP]
 );
 
-/* Prints change events based on the pipeline specifications */
+// Prints change events based on the pipeline specifications
 for ($changeStream->rewind(); true; $changeStream->next()) {
     if (! $changeStream->valid()) {
         continue;

From dd6d1c0ca5f8bbb8908ff51b3c9951dfe50934af Mon Sep 17 00:00:00 2001
From: rustagir <rea.rustagi@mongodb.com>
Date: Fri, 21 Feb 2025 15:36:46 -0500
Subject: [PATCH 12/14] JT tech review 2

---
 source/builders.txt | 38 +++++++++++++++++++++++++++++++-------
 1 file changed, 31 insertions(+), 7 deletions(-)

diff --git a/source/builders.txt b/source/builders.txt
index a587fdaa..017e10ca 100644
--- a/source/builders.txt
+++ b/source/builders.txt
@@ -90,18 +90,19 @@ 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. To
-learn more about creating filters, see the :ref:`php-specify-query` guide.
+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. Instantiate the ``QueryInterface`` by calling the ``Query::query()``
-   method.
+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 to the ``QueryInterface``.
+   criteria in the filter to apply multiple clauses.
 
 The following code shows the template to create a filter definition by
 using builders:
@@ -114,6 +115,21 @@ using builders:
        ...
    );
 
+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.
 
@@ -156,10 +172,18 @@ Delete Example
 
 This example performs the following actions:
 
-- Uses the ``Query::regex()`` factory method to match documents in which
-  the ``feature_type`` field value contains the string ``'nondangerous'``
+- 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::

From bdc6d51a60d6275db538f6f07afcc0879f8f2580 Mon Sep 17 00:00:00 2001
From: rustagir <rea.rustagi@mongodb.com>
Date: Thu, 27 Feb 2025 09:47:03 -0500
Subject: [PATCH 13/14] fix code example

---
 source/includes/builders.php | 29 +++++++++++++++++------------
 1 file changed, 17 insertions(+), 12 deletions(-)

diff --git a/source/includes/builders.php b/source/includes/builders.php
index e8988513..3044147b 100644
--- a/source/includes/builders.php
+++ b/source/includes/builders.php
@@ -18,16 +18,18 @@
 // 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,
+$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) {
@@ -38,9 +40,12 @@
 // start-deleteone
 // Creates a query filter by using builders
 // and deletes the first matching document
-$result = $collection->deleteOne(Query::query(
-    feature_type: Query::regex('nondangerous$', '')
-));
+$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;

From 3724c51d1c38c2e4bbc4d935cc739e7fd100e7d5 Mon Sep 17 00:00:00 2001
From: rustagir <rea.rustagi@mongodb.com>
Date: Mon, 3 Mar 2025 10:27:31 -0500
Subject: [PATCH 14/14] JT tech review comments

---
 source/builders.txt | 16 ++++------------
 1 file changed, 4 insertions(+), 12 deletions(-)

diff --git a/source/builders.txt b/source/builders.txt
index 017e10ca..5f6f77ae 100644
--- a/source/builders.txt
+++ b/source/builders.txt
@@ -209,26 +209,18 @@ guide.
 Define an Update Document
 -------------------------
 
-You can use the ``Stage::set()`` factory method when creating update
-documents. Update documents describe the updates to make to target
+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.
 
-.. important:: Only $set Operator Supported in Update Documents
-
-   The only update operation that you can express with builders uses
-   the ``$set`` operator. This operator allows you to replace the value of
-   a field with a specified value or create a new field that has a specified
-   value. To learn more, see the :manual:`$set </reference/operator/update/set/>`
-   reference in the {+mdb-server+} manual.
-
 The following steps describe how to create an update document by using
 builders:
 
 1. Create a ``Pipeline`` instance.
    
-#. Pass one or more ``$set`` stages by calling the ``Stage::set()``
-   method and passing a field name and a value.
+#. 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: