PHPLIB-1506 Import mongodb/builder

.gitattributes

@@ -4,6 +4,7 @@ tests export-ignore
 benchmark export-ignore
 docs export-ignore
 examples export-ignore
+generator export-ignore
 mongo-orchestration export-ignore
 stubs export-ignore
 tools export-ignore
@@ -14,6 +15,13 @@ phpunit.evergreen.xml export-ignore
 phpunit.xml.dist export-ignore
 psalm.xml.dist export-ignore
 psalm-baseline.xml export-ignore
+rector.php export-ignore
 
 # Prevent generated build files from showing diffs in pull requests
 .evergreen/config/generated/** linguist-generated=true
+/src/Builder/Accumulator/*.php linguist-generated=true
+/src/Builder/Expression/*.php linguist-generated=true
+/src/Builder/Query/*.php linguist-generated=true
+/src/Builder/Projection/*.php linguist-generated=true
+/src/Builder/Stage/*.php linguist-generated=true
+/tests/Builder/*/Pipelines.php linguist-generated=true

.github/actions/setup/action.yml

@@ -11,6 +11,9 @@ inputs:
     description: "INI values to pass along to setup-php action"
     required: false
     default: ""
+  working-directory:
+    description: "The directory where composer.json is located, if it is not in the repository root."
+    required: false
 
 runs:
   using: composite
@@ -49,3 +52,4 @@ runs:
         # Revert when psalm supports PHP 8.4
         # composer-options: "--no-suggest"
         composer-options: "--no-suggest ${{ inputs.php-version == '8.4' && '--ignore-platform-req=php+' || '' }}"
+        working-directory: "${{ inputs.working-directory }}"

.github/workflows/generator.yml

@@ -0,0 +1,42 @@
+name: "Generator"
+
+on:
+  merge_group:
+  pull_request:
+    branches:
+      - "v*.*"
+      - "master"
+      - "feature/*"
+  push:
+    branches:
+      - "v*.*"
+      - "master"
+      - "feature/*"
+
+env:
+  PHP_VERSION: "8.2"
+  # TODO: change to "stable" once 1.20.0 is released
+  # DRIVER_VERSION: "stable"
+  DRIVER_VERSION: "mongodb/mongo-php-driver@v1.20"
+
+jobs:
+  psalm:
+    name: "Diff check"
+    runs-on: "ubuntu-22.04"
+
+    steps:
+      - name: "Checkout"
+        uses: "actions/checkout@v4"
+
+      - name: "Setup"
+        uses: "./.github/actions/setup"
+        with:
+          php-version: ${{ env.PHP_VERSION }}
+          driver-version: ${{ env.DRIVER_VERSION }}
+          working-directory: "generator"
+
+      - name: "Run Generator"
+        run: "generator/generate"
+
+      - name: "Check file diff"
+        run: git add . -N && git diff --exit-code

composer.json

@@ -26,6 +26,9 @@
         "symfony/phpunit-bridge": "^5.2",
         "vimeo/psalm": "^5.13"
     },
+    "replace": {
+        "mongodb/builder": "*"
+    },
     "autoload": {
         "psr-4": { "MongoDB\\": "src/" },
         "files": [ "src/functions.php" ]

generator/README.md

@@ -0,0 +1,34 @@
+# Code Generator for MongoDB PHP Library
+
+This subproject is used to generate the code that is committed to the repository.
+The `generator` directory is not included in `mongodb/mongodb` package and is not installed by Composer.
+
+## Contributing
+
+Updating the generated code can be done only by modifying the code generator, or its configuration.
+
+To run the generator, you need to have PHP 8.1+ installed and Composer.
+
+1. Move to the `generator` directory: `cd generator`
+1. Install dependencies: `composer install`
+1. Run the generator: `./generate`
+
+## Configuration
+
+The `generator/config/*.yaml` files contains the list of operators and stages that are supported by the library.
+
+### Test pipelines
+
+Each operator can contain a `tests` section with a list if pipelines. To represent specific BSON objects,
+it is necessary to use Yaml tags:
+
+| BSON Type   | Example                                                |
+|-------------|--------------------------------------------------------|
+| Regex       | `!bson_regex '^abc'` <br/> `!bson_regex ['^abc', 'i']` |
+| Int64       | `!bson_int64 '123456789'`                              |
+| Decimal128  | `!bson_decimal128 '0.9'`                               |
+| UTCDateTime | `!bson_utcdatetime 0`                                  |
+| Binary      | `!bson_binary 'IA=='`                                  |
+
+To add new test cases to operators, you can get inspiration from the official MongoDB documentation and use
+the `generator/js2yaml.html` web page to manually convert a pipeline array from JS to Yaml.

generator/composer.json

@@ -0,0 +1,32 @@
+{
+    "name": "mongodb/code-generator",
+    "type": "project",
+    "repositories": [
+        {
+            "type": "path",
+            "url": "../",
+            "symlink": true
+        }
+    ],
+    "replace": {
+        "symfony/polyfill-php80": "*",
+        "symfony/polyfill-php81": "*"
+    },
+    "require": {
+        "mongodb/mongodb": "@dev",
+        "nette/php-generator": "^4.1.5",
+        "nikic/php-parser": "^5",
+        "symfony/console": "^7",
+        "symfony/finder": "^7",
+        "symfony/yaml": "^7"
+    },
+    "license": "Apache-2.0",
+    "autoload": {
+        "psr-4": {
+            "MongoDB\\CodeGenerator\\": "src/"
+        }
+    },
+    "config": {
+        "sort-packages": true
+    }
+}

generator/config/accumulator/accumulator.yaml

@@ -0,0 +1,133 @@
+# $schema: ../schema.json
+name: $accumulator
+link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/accumulator/'
+type:
+    - accumulator
+encode: object
+description: |
+    Defines a custom accumulator function.
+    New in MongoDB 4.4.
+arguments:
+    -
+        name: init
+        type:
+            - javascript
+        description: |
+            Function used to initialize the state. The init function receives its arguments from the initArgs array expression. You can specify the function definition as either BSON type Code or String.
+    -
+        name: initArgs
+        type:
+            - resolvesToArray
+        optional: true
+        description: |
+            Arguments passed to the init function.
+    -
+        name: accumulate
+        type:
+            - javascript
+        description: |
+            Function used to accumulate documents. The accumulate function receives its arguments from the current state and accumulateArgs array expression. The result of the accumulate function becomes the new state. You can specify the function definition as either BSON type Code or String.
+    -
+        name: accumulateArgs
+        type:
+            - resolvesToArray
+        description: |
+            Arguments passed to the accumulate function. You can use accumulateArgs to specify what field value(s) to pass to the accumulate function.
+    -
+        name: merge
+        type:
+            - javascript
+        description: |
+            Function used to merge two internal states. merge must be either a String or Code BSON type. merge returns the combined result of the two merged states. For information on when the merge function is called, see Merge Two States with $merge.
+    -
+        name: finalize
+        type:
+            - javascript
+        optional: true
+        description: |
+            Function used to update the result of the accumulation.
+    -
+        name: lang
+        type:
+            - string
+        description: |
+            The language used in the $accumulator code.
+
+tests:
+    -
+        name: 'Use $accumulator to Implement the $avg Operator'
+        link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/accumulator/#use--accumulator-to-implement-the--avg-operator'
+        pipeline:
+            -
+                $group:
+                    _id: '$author'
+                    avgCopies:
+                        $accumulator:
+                            init:
+                                $code: |-
+                                    function() {
+                                        return { count: 0, sum: 0 }
+                                    }
+                            accumulate:
+                                $code: |-
+                                    function(state, numCopies) {
+                                        return { count: state.count + 1, sum: state.sum + numCopies }
+                                    }
+                            accumulateArgs: [ "$copies" ],
+                            merge:
+                                $code: |-
+                                    function(state1, state2) {
+                                        return {
+                                            count: state1.count + state2.count,
+                                            sum: state1.sum + state2.sum
+                                        }
+                                    }
+                            finalize:
+                                $code: |-
+                                    function(state) {
+                                        return (state.sum / state.count)
+                                    }
+                            lang: 'js'
+
+    -
+        name: 'Use initArgs to Vary the Initial State by Group'
+        link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/accumulator/#use-initargs-to-vary-the-initial-state-by-group'
+        pipeline:
+            -
+                $group:
+                    _id:
+                        city: '$city'
+                    restaurants:
+                        $accumulator:
+                            init:
+                                $code: |-
+                                    function(city, userProfileCity) {
+                                        return { max: city === userProfileCity ? 3 : 1, restaurants: [] }
+                                    }
+                            initArgs:
+                                - '$city'
+                                - 'Bettles'
+                            accumulate:
+                                $code: |-
+                                    function(state, restaurantName) {
+                                        if (state.restaurants.length < state.max) {
+                                            state.restaurants.push(restaurantName);
+                                        }
+                                        return state;
+                                    }
+                            accumulateArgs:
+                                - '$name'
+                            merge:
+                                $code: |-
+                                    function(state1, state2) {
+                                        return {
+                                            max: state1.max,
+                                            restaurants: state1.restaurants.concat(state2.restaurants).slice(0, state1.max)
+                                        }
+                                    }
+                            finalize:
+                                $code: |-
+                                    function(state) {
+                                        return state.restaurants
+                                    }
+                            lang: 'js'

generator/config/accumulator/addToSet.yaml

@@ -0,0 +1,47 @@
+# $schema: ../schema.json
+name: $addToSet
+link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/addToSet/'
+type:
+    - accumulator
+    - window
+encode: single
+description: |
+    Returns an array of unique expression values for each group. Order of the array elements is undefined.
+    Changed in MongoDB 5.0: Available in the $setWindowFields stage.
+arguments:
+    -
+        name: expression
+        type:
+            - expression
+
+tests:
+    -
+        name: 'Use in $group Stage'
+        link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/addToSet/#use-in--group-stage'
+        pipeline:
+            - $group:
+                _id:
+                    day:
+                        $dayOfYear:
+                            date: '$date'
+                    year:
+                        $year:
+                            date: '$date'
+                itemsSold:
+                    $addToSet: '$item'
+    -
+        name: 'Use in $setWindowFields Stage'
+        link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/addToSet/#use-in--setwindowfields-stage'
+        pipeline:
+            -
+                $setWindowFields:
+                    partitionBy: '$state'
+                    sortBy:
+                        orderDate: 1
+                    output:
+                        cakeTypesForState:
+                            $addToSet: '$type'
+                            window:
+                                documents:
+                                    - 'unbounded'
+                                    - 'current'

generator/config/accumulator/avg.yaml

@@ -0,0 +1,45 @@
+# $schema: ../schema.json
+name: $avg
+link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/avg/'
+type:
+    - accumulator
+    - window
+encode: single
+description: |
+    Returns an average of numerical values. Ignores non-numeric values.
+    Changed in MongoDB 5.0: Available in the $setWindowFields stage.
+arguments:
+    -
+        name: expression
+        type:
+            - resolvesToNumber
+tests:
+    -
+        name: 'Use in $group Stage'
+        link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/avg/#use-in--group-stage'
+        pipeline:
+            - $group:
+                    _id: '$item'
+                    avgAmount:
+                        $avg:
+                            $multiply:
+                                - '$price'
+                                - '$quantity'
+                    avgQuantity:
+                        $avg: '$quantity'
+    -
+        name: 'Use in $setWindowFields Stage'
+        link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/avg/#use-in--setwindowfields-stage'
+        pipeline:
+            -
+                $setWindowFields:
+                    partitionBy: '$state'
+                    sortBy:
+                        orderDate: 1
+                    output:
+                        averageQuantityForState:
+                            $avg: '$quantity'
+                            window:
+                                documents:
+                                    - 'unbounded'
+                                    - 'current'