fix merge conflicts

Author: rustagir

.github/workflows/coding-standards.yml

@@ -8,9 +8,7 @@ on:
 
 env:
   PHP_VERSION: "8.2"
-  # TODO: change to "stable" once 1.20.0 is released
-  # DRIVER_VERSION: "stable"
-  DRIVER_VERSION: "mongodb/mongo-php-driver@master"
+  DRIVER_VERSION: "stable"
 
 jobs:
   phpcs:

.github/workflows/static-analysis.yml

@@ -14,9 +14,7 @@ on:
 
 env:
   PHP_VERSION: "8.2"
-  # TODO: change to "stable" once 1.20.0 is released
-  # DRIVER_VERSION: "stable"
-  DRIVER_VERSION: "mongodb/mongo-php-driver@master"
+  DRIVER_VERSION: "stable"
 
 jobs:
   psalm:

.github/workflows/vale-tdbx.yml

@@ -18,20 +18,20 @@ jobs:
       - id: files
         uses: masesgroup/retrieve-changed-files@v2
         with:
-          format: 'csv'
+          format: "csv"
 
       - name: checkout-latest-rules
         uses: actions/checkout@v4
         with:
           repository: mongodb/mongodb-vale-action
-          path: './tdbx-vale-rules'
+          path: "./tdbx-vale-rules"
           token: ${{secrets.GITHUB_TOKEN}}
 
       - name: move-files-for-vale-action
         run: |
-            cp tdbx-vale-rules/.vale.ini .vale.ini
-            mkdir -p .github/styles/
-            cp -rf tdbx-vale-rules/.github/styles/ .github/
+          cp tdbx-vale-rules/.vale.ini .vale.ini
+          mkdir -p .github/styles/
+          cp -rf tdbx-vale-rules/.github/styles/ .github/
 
       - name: run-vale
         uses: errata-ai/vale-action@reviewdog

snooty.toml

@@ -29,6 +29,7 @@ toc_landing_pages = [
     "/security",
     "/data-formats",
     "/upgrade",
+    "/aggregation",
 ]
 
 sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"
@@ -38,7 +39,8 @@ php-library = "MongoDB PHP Library"
 
 [constants]
 php-library = "MongoDB PHP Library"
-version = "1.20"
+version = "1.21"
+source-gh-branch = "v1.x"
 full-version = "{+version+}.0"
 extension-short = "PHP extension"
 mdb-server = "MongoDB Server"

source/aggregation.txt

@@ -18,12 +18,12 @@ Transform Your Data with Aggregation
    :depth: 2
    :class: singlecol
 
-.. TODO:
- .. toctree::
-    :titlesonly:
-    :maxdepth: 1
+.. toctree::
+   :titlesonly:
+   :maxdepth: 1
 
-    /aggregation/aggregation-tutorials
+   Atlas Search </aggregation/atlas-search>
+   Atlas Vector Search </aggregation/vector-search>
 
 Overview
 --------
@@ -47,8 +47,8 @@ The **aggregation pipeline** is the assembly line, **aggregation stages** are th
 assembly stations, and **operator expressions** are the
 specialized tools.
 
-Aggregation Versus Find Operations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Compare Aggregation and Find Operations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You can use find operations to perform the following actions:
 
@@ -72,6 +72,7 @@ Consider the following limitations when performing aggregation operations:
 - Returned documents cannot violate the
   :manual:`BSON document size limit </reference/limits/#mongodb-limit-BSON-Document-Size>`
   of 16 megabytes.
+
 - Pipeline stages have a memory limit of 100 megabytes by default. You can exceed this
   limit by creating an options array that sets the ``allowDiskUse`` option to ``true``
   and passing the array to the ``MongoDB\Collection::aggregate()`` method.
@@ -82,37 +83,63 @@ Consider the following limitations when performing aggregation operations:
      </reference/operator/aggregation/graphLookup/>` stage has a strict
      memory limit of 100 megabytes and ignores the ``allowDiskUse`` option.
 
-.. _php-aggregation-example:
+Aggregation APIs
+----------------
 
-Aggregation Example
--------------------
+The {+library-short+} provides the following APIs to create aggregation
+pipelines:
+
+- :ref:`php-aggregation-array-api`: Create aggregation pipelines by
+  passing arrays that specify the aggregation stages.
+- :ref:`php-aggregation-builder-api`: Create aggregation pipelines by
+  using factory methods to make your application more type-safe and debuggable.
+
+The following sections describe each API and provide examples for
+creating aggregation pipelines.
 
-.. note::
+.. _php-aggregation-array-api:
+
+Array API
+---------
+
+To perform an aggregation, pass an array containing the pipeline stages
+as BSON documents to the ``MongoDB\Collection::aggregate()`` method, as
+shown in the following code:
+
+.. code-block:: php
+    
+   $pipeline = [
+       ['<stage>' => <parameters>],
+       ['<stage>' => <parameters>],
+       ...
+   ];
+   
+   $cursor = $collection->aggregate($pipeline);
 
-   The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants``
-   database from the :atlas:`Atlas sample datasets </sample-data>`. 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 examples in this section use the ``restaurants`` collection in the ``sample_restaurants``
+database from the :atlas:`Atlas sample datasets </sample-data>`. 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.
 
-To perform an aggregation, pass an array containing the pipeline stages to
-the ``MongoDB\Collection::aggregate()`` method.
+Filter and Group Example
+~~~~~~~~~~~~~~~~~~~~~~~~
 
 The following code example produces a count of the number of bakeries in each borough
 of New York. To do so, it uses an aggregation pipeline that contains the following stages:
 
-- :manual:`$match </reference/operator/aggregation/match/>` stage to filter for documents
-  in which the ``cuisine`` field contains the value ``'Bakery'``
+1. :manual:`$match </reference/operator/aggregation/match/>` stage to filter for documents
+   in which the ``cuisine`` field contains the value ``'Bakery'``
 
-- :manual:`$group </reference/operator/aggregation/group/>` stage to group the matching
-  documents by the ``borough`` field, accumulating a count of documents for each distinct
-  value
+#. :manual:`$group </reference/operator/aggregation/group/>` stage to group the matching
+   documents by the ``borough`` field, accumulating a count of documents for each distinct
+   value
 
 .. io-code-block::
    :copyable:
 
-   .. input:: /includes/aggregation.php
-      :start-after: start-match-group
-      :end-before: end-match-group
+   .. input:: /includes/aggregation/aggregation.php
+      :start-after: start-array-match-group
+      :end-before: end-array-match-group
       :language: php
       :dedent:
 
@@ -141,18 +168,18 @@ and pass the database, collection, and pipeline stages as parameters. Then, pass
 ``MongoDB\Operation\Aggregate`` object to the ``MongoDB\Collection::explain()`` method.
 
 The following example instructs MongoDB to explain the aggregation operation
-from the preceding :ref:`php-aggregation-example`:
+from the preceding section:
 
 .. io-code-block::
    :copyable:
 
-   .. input:: /includes/aggregation.php
-      :start-after: start-explain
-      :end-before: end-explain
+   .. input:: /includes/aggregation/aggregation.php
+      :start-after: start-array-explain
+      :end-before: end-array-explain
       :language: php
       :dedent:
 
-   .. output:: 
+   .. output::
       :visible: false
 
       {"explainVersion":"2","queryPlanner":{"namespace":"sample_restaurants.restaurants",
@@ -161,6 +188,158 @@ from the preceding :ref:`php-aggregation-example`:
       "maxIndexedAndSolutionsReached":false,"maxScansToExplodeReached":false,"winningPlan":{
       ... }
 
+.. _php-aggregation-builder-api:
+
+Aggregation Builder
+-------------------
+
+To create an aggregation pipeline by using the Aggregation Builder,
+perform the following actions:
+
+1. Create an array to store the pipeline stages.
+
+#. For each stage, call the a factory method from the
+   ``Stage`` that shares the same name as your desired aggregation
+   stage. For example, to create an ``$unwind`` stage, call the
+   ``Stage::unwind()`` method.
+
+#. Within the body of the ``Stage`` method, use methods from other
+   builder classes such as ``Query``, ``Expression``, or ``Accumulator``
+   to express your aggregation specifications.
+
+The following code demonstrates the template for constructing
+aggregation pipelines:
+
+.. code-block:: php
+
+   $pipeline = [
+       Stage::<factory method>(
+           <stage specification>
+       ),
+       Stage::<factory method>(
+           <stage specification>
+       ),
+       ...
+   ];
+   
+   $cursor = $collection->aggregate($pipeline);
+
+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.
+
+Filter and Group Example
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+This example uses the sample data given in the :manual:`Calculate Count,
+Sum, and Average </reference/operator/aggregation/group/#calculate-count--sum--and-average>`
+section of the ``$group`` stage reference in the Server manual.
+
+The following code example calculates the total sales amount, average
+sales quantity, and sale count for each day in the year 2014. To do so,
+it uses an aggregation pipeline that contains the following stages:
+
+1. :manual:`$match </reference/operator/aggregation/match/>` stage to
+   filter for documents that contain a ``date`` field in which the year is
+   2014
+
+#. :manual:`$group </reference/operator/aggregation/group/>` stage to
+   group the documents by date and calculate the total sales amount,
+   average sales quantity, and sale count for each group
+  
+#. :manual:`$sort </reference/operator/aggregation/sort/>` stage to
+   sort the results by the total sale amount for each group in descending
+   order
+  
+.. io-code-block::
+   :copyable:
+
+   .. input:: /includes/aggregation/aggregation.php
+      :start-after: start-builder-match-group
+      :end-before: end-builder-match-group
+      :language: php
+      :dedent:
+
+   .. output:: 
+      :visible: false
+
+      {"_id":"2014-04-04","totalSaleAmount":{"$numberDecimal":"200"},"averageQuantity":15,"count":2}
+      {"_id":"2014-03-15","totalSaleAmount":{"$numberDecimal":"50"},"averageQuantity":10,"count":1}
+      {"_id":"2014-03-01","totalSaleAmount":{"$numberDecimal":"40"},"averageQuantity":1.5,"count":2}
+
+Unwind Embedded Arrays Example
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This example uses the sample data given in the :manual:`Unwind Embedded Arrays
+</reference/operator/aggregation/unwind/#unwind-embedded-arrays>`
+section of the ``$unwind`` stage reference in the Server manual.
+
+The following code example groups sold items by their tags and
+calculates the total sales amount for each tag. To do so,
+it uses an aggregation pipeline that contains the following stages:
+
+1. :manual:`$unwind </reference/operator/aggregation/unwind/>` stage to
+   output a separate document for each element in the ``items`` array
+
+#. :manual:`$unwind </reference/operator/aggregation/unwind/>` stage to
+   output a separate document for each element in the ``items.tags`` arrays
+  
+#. :manual:`$group </reference/operator/aggregation/group/>` stage to
+   group the documents by the tag value and calculate the total sales
+   amount of items that have each tag
+  
+.. io-code-block::
+   :copyable:
+
+   .. input:: /includes/aggregation/aggregation.php
+      :start-after: start-builder-unwind
+      :end-before: end-builder-unwind
+      :language: php
+      :dedent:
+
+   .. output:: 
+      :visible: false
+
+      {"_id":"office","totalSalesAmount":{"$numberDecimal":"1019.60"}}
+      {"_id":"school","totalSalesAmount":{"$numberDecimal":"104.85"}}
+      {"_id":"stationary","totalSalesAmount":{"$numberDecimal":"264.45"}}
+      {"_id":"electronics","totalSalesAmount":{"$numberDecimal":"800.00"}}
+      {"_id":"writing","totalSalesAmount":{"$numberDecimal":"60.00"}}
+
+Single Equality Join Example
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This example uses the sample data given in the :manual:`Perform a Single
+Equality Join with $lookup
+</reference/operator/aggregation/lookup/#perform-a-single-equality-join-with--lookup>`
+section of the ``$lookup`` stage reference in the Server manual.
+
+The following code example joins the documents from the ``orders``
+collection with the documents from the ``inventory`` collection by using
+the ``item`` field from the ``orders`` collection and the ``sku`` field
+from the ``inventory`` collection.
+
+To do so, the example uses an aggregation pipeline that contains a 
+:manual:`$lookup </reference/operator/aggregation/lookup/>` stage that
+specifies the collection to retrieve data from and the local and
+foreign field names.
+
+.. io-code-block::
+   :copyable:
+
+   .. input:: /includes/aggregation/aggregation.php
+      :start-after: start-builder-lookup
+      :end-before: end-builder-lookup
+      :language: php
+      :dedent:
+
+   .. output:: 
+      :visible: false
+
+      {"_id":1,"item":"almonds","price":12,"quantity":2,"inventory_docs":[{"_id":1,"sku":"almonds","description":"product 1","instock":120}]}
+      {"_id":2,"item":"pecans","price":20,"quantity":1,"inventory_docs":[{"_id":4,"sku":"pecans","description":"product 4","instock":70}]}
+      {"_id":3,"inventory_docs":[{"_id":5,"sku":null,"description":"Incomplete"},{"_id":6}]}
+
 Additional Information
 ----------------------
 
@@ -169,6 +348,11 @@ pipelines, see `Complex Aggregation Pipelines with Vanilla PHP and MongoDB
 <https://www.mongodb.com/developer/products/mongodb/aggregations-php-mongodb/>`__
 in the MongoDB Developer Center.
 
+To view more examples of aggregation pipelines built by using the Aggregation
+Builder, see the :github:`Stage class test suite
+<mongodb/mongo-php-library/tree/{+source-gh-branch+}/tests/Builder/Stage>` in the
+{+library-short+} source code on GitHub.
+
 MongoDB Server Manual
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -188,6 +372,15 @@ pages in the {+mdb-server+} manual:
   :manual:`Explain Output </reference/explain-results/>` and
   :manual:`Query Plans </core/query-plans/>`.
 
+Atlas Search and Vector Search
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can perform full-text searches by using the Atlas Search feature. To
+learn more, see the :ref:`php-atlas-search` guide.
+
+You can perform similarity searches on vector embeddings by using the
+Atlas Vector Search feature. To learn more, see the :ref:`php-vector-search` guide.
+
 .. TODO:
  Aggregation Tutorials
  ~~~~~~~~~~~~~~~~~~~~~