Merge v1.x into v2.x (#1550)

mongodb · Dec 4, 2024 · 99b1889 · 99b1889
2 parents 213648f + c386f6d
commit 99b1889
Show file tree

Hide file tree

Showing 375 changed files with 10,727 additions and 1,956 deletions.
diff --git a/.gitattributes b/.gitattributes
@@ -22,6 +22,6 @@ rector.php export-ignore
 /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/Search/*.php linguist-generated=true
 /src/Builder/Stage/*.php linguist-generated=true
 /tests/Builder/*/Pipelines.php linguist-generated=true
diff --git a/generator/README.md b/generator/README.md
@@ -10,25 +10,40 @@ Updating the generated code can be done only by modifying the code generator, or
 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`
+2. Install dependencies: `composer install`
+3. Run the generator: `./generate`
 
 ## Configuration
 
 The `generator/config/*.yaml` files contains the list of operators and stages that are supported by the library.
 
+### Arguments
+
+| Field         | Type                | Description                                                                                                                                                               |
+|---------------|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `name`        | `string`            | The name of the argument. If it starts with `$`, the dollar is trimmed from the class property name                                                                       |
+| `type`        | list of `string`    | The list of accepted types                                                                                                                                                |
+| `description` | `string`            | The description of the argument from MongoDB's documentation                                                                                                              |
+| `optional`    | `boolean`           | Whether the argument is optional or not                                                                                                                                   |
+| `valueMin`    | `number`            | The minimum value for a numeric argument                                                                                                                                  |
+| `valueMax`    | `number`            | The maximum value for a numeric argument                                                                                                                                  |
+| `variadic`    | `string`            | If sent, the argument is variadic. Defines the format `array` for a list or `object` for a map                                                                            |
+| `variadicMin` | `integer`           | The minimum number of arguments for a variadic parameter                                                                                                                  |
+| `default`     | `scalar` or `array` | The default value for the argument                                                                                                                                        |
+| `mergeObject` | `bool`              | Default `false`. If `true`, the value must be an object and the properties of the value object are merged into the parent operator. `$group` stage uses it for the fields |
+
 ### 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:
+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`                                  |
+| ObjectId    | `!bson_ObjectId '5a9427648b0beebeb69589a1`             |
 | Binary      | `!bson_binary 'IA=='`                                  |
+| Binary UUID | `!bson_uuid 'fac32260-b511-4c69-8485-a2be5b7dda9e'`    |
 
-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.
+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.
diff --git a/generator/composer.json b/generator/composer.json
@@ -4,7 +4,7 @@
     "repositories": [
         {
             "type": "path",
-            "url": "../",
+            "url": "..",
             "symlink": true
         }
     ],

diff --git a/generator/config/definitions.php b/generator/config/definitions.php
@@ -58,4 +58,16 @@
             OperatorTestGenerator::class,
         ],
     ],
+
+    // Search Operators
+    [
+        'configFiles' => __DIR__ . '/search',
+        'namespace' => 'MongoDB\\Builder\\Search',
+        'classNameSuffix' => 'Operator',
+        'generators' => [
+            OperatorClassGenerator::class,
+            OperatorFactoryGenerator::class,
+            OperatorTestGenerator::class,
+        ],
+    ],
 ];
diff --git a/generator/config/expression/case.yaml b/generator/config/expression/case.yaml
@@ -3,7 +3,8 @@ name: $case
 link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/switch/'
 type:
     - switchBranch
-encode: flat_object
+encode: object
+wrapObject: false
 description: |
     Represents a single case in a $switch expression
 arguments:

diff --git a/generator/config/expressions.php b/generator/config/expressions.php
@@ -109,6 +109,10 @@
         'implements' => [ResolvesToAny::class],
         'acceptedTypes' => ['string'],
     ],
+    'searchOperator' => [
+        'returnType' => Type\SearchOperatorInterface::class,
+        'acceptedTypes' => [Type\SearchOperatorInterface::class, ...$bsonTypes['object']],
+    ],
     'geometry' => [
         'returnType' => Type\GeometryInterface::class,
         'acceptedTypes' => [Type\GeometryInterface::class, ...$bsonTypes['object']],
@@ -168,4 +172,12 @@
     'GeoPoint' => [
         'acceptedTypes' => [...$bsonTypes['object']],
     ],
+
+    // Search
+    'searchPath' => [
+        'acceptedTypes' => ['string', 'array'],
+    ],
+    'searchScore' => [
+        'acceptedTypes' => [...$bsonTypes['object']],
+    ],
 ];
diff --git a/generator/config/query/geoIntersects.yaml b/generator/config/query/geoIntersects.yaml
@@ -3,12 +3,13 @@ name: $geoIntersects
 link: 'https://www.mongodb.com/docs/manual/reference/operator/query/geoIntersects/'
 type:
     - fieldQuery
-encode: single
+encode: object
 description: |
     Selects geometries that intersect with a GeoJSON geometry. The 2dsphere index supports $geoIntersects.
 arguments:
     -
         name: geometry
+        mergeObject: true
         type:
             - geometry
 tests:

diff --git a/generator/config/query/geoWithin.yaml b/generator/config/query/geoWithin.yaml
@@ -3,12 +3,13 @@ name: $geoWithin
 link: 'https://www.mongodb.com/docs/manual/reference/operator/query/geoWithin/'
 type:
     - fieldQuery
-encode: single
+encode: object
 description: |
     Selects geometries within a bounding GeoJSON geometry. The 2dsphere and 2d indexes support $geoWithin.
 arguments:
     -
         name: geometry
+        mergeObject: true
         type:
             - geometry
 tests:

diff --git a/generator/config/query/near.yaml b/generator/config/query/near.yaml
@@ -3,23 +3,24 @@ name: $near
 link: 'https://www.mongodb.com/docs/manual/reference/operator/query/near/'
 type:
     - fieldQuery
-encode: dollar_object
+encode: object
 description: |
     Returns geospatial objects in proximity to a point. Requires a geospatial index. The 2dsphere and 2d indexes support $near.
 arguments:
     -
         name: geometry
+        mergeObject: true
         type:
             - geometry
     -
-        name: maxDistance
+        name: $maxDistance
         type:
             - number
         optional: true
         description: |
             Distance in meters. Limits the results to those documents that are at most the specified distance from the center point.
     -
-        name: minDistance
+        name: $minDistance
         type:
             - number
         optional: true

diff --git a/generator/config/query/nearSphere.yaml b/generator/config/query/nearSphere.yaml
@@ -3,23 +3,24 @@ name: $nearSphere
 link: 'https://www.mongodb.com/docs/manual/reference/operator/query/nearSphere/'
 type:
     - fieldQuery
-encode: dollar_object
+encode: object
 description: |
     Returns geospatial objects in proximity to a point on a sphere. Requires a geospatial index. The 2dsphere and 2d indexes support $nearSphere.
 arguments:
     -
         name: geometry
+        mergeObject: true
         type:
             - geometry
     -
-        name: maxDistance
+        name: $maxDistance
         type:
             - number
         optional: true
         description: |
             Distance in meters.
     -
-        name: minDistance
+        name: $minDistance
         type:
             - number
         optional: true

diff --git a/generator/config/query/text.yaml b/generator/config/query/text.yaml
@@ -3,33 +3,33 @@ name: $text
 link: 'https://www.mongodb.com/docs/manual/reference/operator/query/text/'
 type:
     - query
-encode: dollar_object
+encode: object
 description: |
     Performs text search.
 arguments:
     -
-        name: search
+        name: $search
         type:
             - string
         description: |
             A string of terms that MongoDB parses and uses to query the text index. MongoDB performs a logical OR search of the terms unless specified as a phrase.
     -
-        name: language
+        name: $language
         type:
             - string
         optional: true
         description: |
             The language that determines the list of stop words for the search and the rules for the stemmer and tokenizer. If not specified, the search uses the default language of the index.
             If you specify a default_language value of none, then the text index parses through each word in the field, including stop words, and ignores suffix stemming.
     -
-        name: caseSensitive
+        name: $caseSensitive
         type:
             - bool
         optional: true
         description: |
             A boolean flag to enable or disable case sensitive search. Defaults to false; i.e. the search defers to the case insensitivity of the text index.
     -
-        name: diacriticSensitive
+        name: $diacriticSensitive
         type:
             - bool
         optional: true

diff --git a/generator/config/schema.json b/generator/config/schema.json
@@ -46,7 +46,8 @@
                             "resolvesToInt",
                             "resolvesToTimestamp",
                             "resolvesToLong",
-                            "resolvesToDecimal"
+                            "resolvesToDecimal",
+                            "searchOperator"
                         ]
                     }
                 },
@@ -60,16 +61,19 @@
                     "enum": [
                         "array",
                         "object",
-                        "flat_object",
-                        "dollar_object",
                         "single",
-                        "group"
+                        "search"
                     ]
                 },
                 "description": {
                     "$comment": "The description of the argument from MongoDB's documentation.",
                     "type": "string"
                 },
+                "wrapObject": {
+                    "$comment": "Wrap the properties in an object with the operator name",
+                    "type": "boolean",
+                    "default": true
+                },
                 "arguments": {
                     "$comment": "An optional list of arguments for the operator.",
                     "type": "array",
@@ -100,7 +104,7 @@
             "properties": {
                 "name": {
                     "type": "string",
-                    "pattern": "^(_?[a-z][a-zA-Z0-9]*|N)$"
+                    "pattern": "^([_$]?[a-z][a-zA-Z0-9]*|N)$"
                 },
                 "type": {
                     "type": "array",
@@ -133,7 +137,8 @@
                             "resolvesToInt", "intFieldPath", "int",
                             "resolvesToTimestamp", "timestampFieldPath", "timestamp",
                             "resolvesToLong", "longFieldPath", "long",
-                            "resolvesToDecimal", "decimalFieldPath", "decimal"
+                            "resolvesToDecimal", "decimalFieldPath", "decimal",
+                            "searchPath", "searchScore", "searchOperator"
                         ]
                     }
                 },
@@ -150,7 +155,7 @@
                     "type": "number"
                 },
                 "valueMax": {
-                    "$comment": "The minimum value for a numeric argument.",
+                    "$comment": "The maximum value for a numeric argument.",
                     "type": "number"
                 },
                 "variadic": {
@@ -169,6 +174,11 @@
                 "default": {
                     "$comment": "The default value for the argument.",
                     "type": ["array", "boolean", "number", "string"]
+                },
+                "mergeObject": {
+                    "$comment": "Skip the name in object encoding and merge the properties of the value into the operator",
+                    "type": "boolean",
+                    "default": false
                 }
             },
             "required": [