DOCSP-47217: pipeline param (#217)

* DOCSP-47217: pipeline param

* JT tech review comment

(cherry picked from commit b287751)

Author: rustagir

source/aggregation.txt

@@ -111,7 +111,7 @@ shown in the following code:
    $pipeline = [
        ['<stage>' => <parameters>],
        ['<stage>' => <parameters>],
-       ...
+       // ...
    ];
 
    $cursor = $collection->aggregate($pipeline);
@@ -196,7 +196,7 @@ 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.
+1. Create a ``MongoDB\Builder\Pipeline`` instance 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
@@ -212,15 +212,15 @@ aggregation pipelines:
 
 .. code-block:: php
 
-   $pipeline = [
+   $pipeline = new Pipeline(
        Stage::<factory method>(
            <stage specification>
        ),
        Stage::<factory method>(
            <stage specification>
        ),
-       ...
-   ];
+       // ...
+   );
 
    $cursor = $collection->aggregate($pipeline);
 

source/aggregation/atlas-search.txt

@@ -65,7 +65,7 @@ Search queries by using the Aggregation Builder:
 To create a ``$search`` stage in your aggregation pipeline, perform the
 following actions:
 
-1. Create an array to store the pipeline stages.
+1. Create a ``Pipeline`` instance to store the pipeline stages.
 
 #. Call the ``Stage::search()`` method to create the Atlas Search stage.
 
@@ -77,12 +77,12 @@ queries:
 
 .. code-block:: php
 
-   $pipeline = [
+   $pipeline = new Pipeline(
        Stage::search(
            /* Atlas Search query specifications
            Search::compound(...) */
        ),
-   ];
+   );
 
 Atlas Search Query Examples
 ---------------------------

source/aggregation/vector-search.txt

@@ -66,7 +66,7 @@ Search queries by using the Aggregation Builder:
 To create a ``$vectorSearch`` stage in your aggregation pipeline, perform the
 following actions:
 
-1. Create an array to store the pipeline stages.
+1. Create a ``Pipeline`` instance to store the pipeline stages.
 
 #. Call the ``Stage::vectorSearch()`` method to create the Atlas Vector
    Search stage.
@@ -79,13 +79,13 @@ queries:
 
 .. code-block:: php
 
-   $pipeline = [
+   $pipeline = new Pipeline(
        Stage::vectorSearch(
            /* Atlas Vector Search query specifications
            index: '<index name>',
            path: '<path to embeddings>', ...*/
        ),
-   ];
+   );
 
 You must pass the following parameters to the ``vectorSearch()`` method:
 

source/includes/aggregation/aggregation.php

@@ -40,7 +40,7 @@
 // end-array-explain
 
 // start-builder-match-group
-$pipeline = [
+$pipeline = new MongoDB\Builder\Pipeline(
     MongoDB\Builder\Stage::match(
         date: [
             MongoDB\Builder\Query::gte(new MongoDB\BSON\UTCDateTime(new DateTimeImmutable('2014-01-01'))),
@@ -63,7 +63,7 @@
     MongoDB\Builder\Stage::sort(
         totalSaleAmount: MongoDB\Builder\Type\Sort::Desc,
     ),
-];
+);
 
 $cursor = $collection->aggregate($pipeline);
 
@@ -73,7 +73,7 @@
 // end-builder-match-group
 
 // start-builder-unwind
-$pipeline = [
+$pipeline = new MongoDB\Builder\Pipeline(
     MongoDB\Builder\Stage::unwind(MongoDB\Builder\Expression::arrayFieldPath('items')),
     MongoDB\Builder\Stage::unwind(MongoDB\Builder\Expression::arrayFieldPath('items.tags')),
     MongoDB\Builder\Stage::group(
@@ -85,7 +85,7 @@
             ),
         ),
     ),
-];
+);
 
 $cursor = $collection->aggregate($pipeline);
 
@@ -97,14 +97,14 @@
 $collection = $client->db->orders;
 
 // start-builder-lookup
-$pipeline = [
+$pipeline = new MongoDB\Builder\Pipeline(
     MongoDB\Builder\Stage::lookup(
         from: 'inventory',
         localField: 'item',
         foreignField: 'sku',
         as: 'inventory_docs',
     ),
-];
+);
 
 /* Performs the aggregation on the orders collection */
 $cursor = $collection->aggregate($pipeline);

source/includes/aggregation/atlas-search.php

@@ -1,6 +1,7 @@
 <?php
 
 // start-imports
+use MongoDB\Builder\Pipeline;
 use MongoDB\Builder\Search;
 use MongoDB\Builder\Stage;
 // end-imports
@@ -34,7 +35,7 @@
 echo "\n";
 
 // start-compound-search-query
-$pipeline = [
+$pipeline = new Pipeline(
     Stage::search(
         Search::compound(
             must: [
@@ -63,7 +64,7 @@
         name: 1
     ),
     Stage::limit(3)
-];
+);
 
 $cursor = $collection->aggregate($pipeline);
 
@@ -109,7 +110,7 @@
 echo "\n";
 
 // start-autocomplete-search-query
-$pipeline = [
+$pipeline = new Pipeline(
     Stage::search(
         Search::autocomplete(
             query: 'Lucy',
@@ -118,7 +119,7 @@
     ),
     Stage::limit(3),
     Stage::project(_id: 0, name: 1),
-];
+);
 
 $cursor = $collection->aggregate($pipeline);
 

source/includes/aggregation/vector-search.php

@@ -1,6 +1,7 @@
 <?php
 
 // start-imports
+use MongoDB\Builder\Pipeline;
 use MongoDB\Builder\Stage;
 // end-imports
 
@@ -42,7 +43,7 @@
 echo "\n";
 
 // start-basic-query
-$pipeline = [
+$pipeline = new Pipeline(
     Stage::vectorSearch(
         index: 'vector',
         path: 'plot_embedding',
@@ -54,7 +55,7 @@
         _id: 0,
         title: 1,
     ),
-];
+);
 
 $cursor = $collection->aggregate($pipeline);
 
@@ -64,7 +65,7 @@
 // end-basic-query
 
 // start-score-query
-$pipeline = [
+$pipeline = new Pipeline(
     Stage::vectorSearch(
         index: 'vector',
         path: 'plot_embedding',
@@ -77,7 +78,7 @@
         title: 1,
         score: ['$meta' => 'vectorSearchScore'],
     ),
-];
+);
 
 $cursor = $collection->aggregate($pipeline);
 

source/read/cursor.txt

@@ -115,8 +115,10 @@ Retrieve All Documents
 To retrieve all documents from a cursor, convert the cursor into an array by using
 either of the following methods:
 
-- ``MongoDB\\Driver\\Cursor::toArray()``: Call on a ``MongoDB\Driver\Cursor`` object
-- ``iterator_to_array()``: Pass a ``MongoDB\Driver\Cursor`` object as a parameter
+- :php:`MongoDB\Driver\Cursor::toArray() <mongodb-driver-cursor.toarray>`: Call
+  on a ``MongoDB\Driver\Cursor`` object
+- :php:`iterator_to_array() <function.iterator-to-array>`: Pass a
+  ``MongoDB\Driver\Cursor`` object as a parameter
 
 The following example calls the ``toArray()`` method on a cursor to store its results
 in an array:
@@ -187,4 +189,4 @@ API Documentation
 ~~~~~~~~~~~~~~~~~
 
 To learn more about the ``find()`` method, see the API documentation for
-:phpmethod:`MongoDB\Collection::find()`.
+:phpmethod:`MongoDB\Collection::find()`.

source/reference/method/MongoDBCollection-aggregate.txt

@@ -20,16 +20,17 @@ Definition
    .. code-block:: php
 
       function aggregate(
-          array $pipeline,
+          array|Pipeline $pipeline,
           array $options = []
       ): Traversable
 
 Parameters
 ----------
 
-``$pipeline`` : array
+``$pipeline`` : array|Pipeline
   Specifies an :manual:`aggregation pipeline </core/aggregation-pipeline>`
-  operation.
+  operation. You can include aggregation stages in a
+  ``MongoDB\Builder\Pipeline`` instance or in an array.
 
 ``$options`` : array
   An array specifying the desired options.
@@ -186,6 +187,7 @@ group, and sorts the results by name.
 See Also
 --------
 
+- :ref:`php-aggregation`
 - :phpmethod:`MongoDB\Database::aggregate()`
 - :manual:`aggregate </reference/command/aggregate>` command reference in the
   MongoDB manual

source/reference/method/MongoDBDatabase-aggregate.txt

@@ -24,16 +24,17 @@ Definition
    .. code-block:: php
 
       function aggregate(
-          array $pipeline,
+          array|Pipeline $pipeline,
           array $options = []
       ): Traversable
 
 Parameters
 ----------
 
-``$pipeline`` : array
+``$pipeline`` : array|Pipeline
   Specifies an :manual:`aggregation pipeline </core/aggregation-pipeline>`
-  operation.
+  operation. You can include aggregation stages in a
+  ``MongoDB\Builder\Pipeline`` instance or in an array.
 
 ``$options`` : array
   An array specifying the desired options.
@@ -169,6 +170,7 @@ running command operations.
 See Also
 --------
 
+- :ref:`php-aggregation`
 - :phpmethod:`MongoDB\Collection::aggregate()`
 - :manual:`aggregate </reference/command/aggregate>` command reference in the
   MongoDB manual

source/whats-new.txt

@@ -64,6 +64,12 @@ and removals:
   replaced by these new methods in a future driver release, so consider
   changing the usages in your application.
 
+- Modifies the :phpmethod:`MongoDB\Database::aggregate()` and
+  :phpmethod:`MongoDB\Collection::aggregate()` methods so they can
+  accept a ``Pipeline`` instance as the ``$pipeline`` parameter. To view
+  examples that use this construction, see the
+  :ref:`php-aggregation-builder-api` section of the Aggregation guide.
+
 - Removes deprecated fields in GridFS types.
 
   - The library does not calculate the ``md5`` field when a file is