PHPLIB-1249 Init code generator project for aggregation 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,3 +15,15 @@ phpunit.evergreen.xml export-ignore
 phpunit.xml.dist export-ignore
 psalm.xml.dist export-ignore
 psalm-baseline.xml export-ignore
+
+# Keep generated files from displaying in diffs by default
+# https://docs.github.com/en/repositories/working-with-files/managing-files/customizing-how-changed-files-appear-on-github
+/src/Builder/Aggregation.php linguist-generated=true
+/src/Builder/Aggregation/*.php linguist-generated=true
+/src/Builder/Expression.php linguist-generated=true
+/src/Builder/Expression/*.php linguist-generated=true
+/src/Builder/Query.php linguist-generated=true
+/src/Builder/Query/*.php linguist-generated=true
+/src/Builder/Stage.php linguist-generated=true
+/src/Builder/Stage/*.php linguist-generated=true
+/src/Builder/Stage/Stage.php linguist-generated=false

generator/README.md

@@ -0,0 +1,18 @@
+# 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.2+ installed and Composer.
+
+1. Move to the `generator` directory: `cd generator`
+1. Install dependencies: `composer install`
+1. Run the generator: `bin/console generate`
+
+## Configuration
+
+The `generator/config/*.yaml` files contains the list of operators and stages that are supported by the library.

generator/bin/console

@@ -0,0 +1,16 @@
+#!/usr/bin/env php
+<?php declare(strict_types=1);
+
+use MongoDB\CodeGenerator\Command\GenerateCommand;
+use Symfony\Component\Console\Application;
+
+if (!file_exists(__DIR__ . '/../vendor/autoload.php')) {
+    echo "Run `composer install` before you run the `console` script.\n";
+    exit(1);
+}
+
+require __DIR__ . '/../vendor/autoload.php';
+
+$application = new Application();
+$application->add(new GenerateCommand(__DIR__ . '/../../', __DIR__ . '/../config'));
+$application->run();

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": {
+        "php": ">=8.2",
+        "ext-mongodb": "^1.16.0",
+        "mongodb/mongodb": "@dev",
+        "nette/php-generator": "^4",
+        "symfony/console": "^6.3",
+        "symfony/yaml": "^6.3"
+    },
+    "license": "Apache-2.0",
+    "autoload": {
+        "psr-4": {
+            "MongoDB\\CodeGenerator\\": "src/"
+        }
+    },
+    "config": {
+        "sort-packages": true
+    }
+}

generator/config/expressions.php

@@ -0,0 +1,110 @@
+<?php
+
+// Target namespace for the generated files, allows to use ::class notation without use statements
+
+namespace MongoDB\Builder\Expression;
+
+use MongoDB\BSON;
+use MongoDB\Model\BSONArray;
+use stdClass;
+
+/** @param class-string $resolvesTo */
+function typeFieldPath(string $resolvesTo): array
+{
+    return [
+        'class' => true,
+        'extends' => FieldPath::class,
+        'implements' => [$resolvesTo],
+        'types' => ['string'],
+    ];
+}
+
+return [
+    // Use Interface suffix to avoid confusion with MongoDB\Builder\Expression factory class
+    ExpressionInterface::class => [
+        'types' => ['mixed'],
+    ],
+    // @todo must not start with $
+    // Allows ORMs to translate field names
+    FieldName::class => [
+        'class' => true,
+        'types' => ['string'],
+    ],
+    // @todo if replaced by a string, it must start with $
+    FieldPath::class => [
+        'class' => true,
+        'implements' => [ExpressionInterface::class],
+        'types' => ['string'],
+    ],
+    // @todo if replaced by a string, it must start with $$
+    Variable::class => [
+        'class' => true,
+        'implements' => [ExpressionInterface::class],
+        'types' => ['string'],
+    ],
+    Literal::class => [
+        'class' => true,
+        'implements' => [ExpressionInterface::class],
+        'types' => ['mixed'],
+    ],
+    // @todo check for use-case
+    ExpressionObject::class => [
+        'implements' => [ExpressionInterface::class],
+        'types' => ['array', stdClass::class, BSON\Document::class, BSON\Serializable::class],
+    ],
+    // @todo check for use-case
+    Operator::class => [
+        'implements' => [ExpressionInterface::class],
+        'types' => ['array', stdClass::class, BSON\Document::class, BSON\Serializable::class],
+    ],
+    ResolvesToArray::class => [
+        'implements' => [ExpressionInterface::class],
+        'types' => ['list', BSONArray::class, BSON\PackedArray::class],
+    ],
+    ArrayFieldPath::class => typeFieldPath(ResolvesToArray::class),
+    ResolvesToBool::class => [
+        'implements' => [ExpressionInterface::class],
+        'types' => ['bool'],
+    ],
+    BoolFieldPath::class => typeFieldPath(ResolvesToBool::class),
+    ResolvesToDate::class => [
+        'implements' => [ExpressionInterface::class],
+        'types' => ['DateTimeInterface', 'UTCDateTime'],
+    ],
+    DateFieldPath::class => typeFieldPath(ResolvesToDate::class),
+    ResolvesToObject::class => [
+        'implements' => [ExpressionInterface::class],
+        'types' => ['array', 'object', BSON\Document::class, BSON\Serializable::class],
+    ],
+    ObjectFieldPath::class => typeFieldPath(ResolvesToObject::class),
+    ResolvesToNull::class => [
+        'implements' => [ExpressionInterface::class],
+        'types' => ['null'],
+    ],
+    NullFieldPath::class => typeFieldPath(ResolvesToNull::class),
+    ResolvesToNumber::class => [
+        'implements' => [ExpressionInterface::class],
+        'types' => ['int', 'float', BSON\Int64::class, BSON\Decimal128::class],
+    ],
+    NumberFieldPath::class => typeFieldPath(ResolvesToNumber::class),
+    ResolvesToDecimal::class => [
+        'implements' => [ResolvesToNumber::class],
+        'types' => ['int', 'float', BSON\Int64::class, BSON\Decimal128::class],
+    ],
+    DecimalFieldPath::class => typeFieldPath(ResolvesToDecimal::class),
+    ResolvesToFloat::class => [
+        'implements' => [ResolvesToNumber::class],
+        'types' => ['int', 'float', BSON\Int64::class],
+    ],
+    FloatFieldPath::class => typeFieldPath(ResolvesToFloat::class),
+    ResolvesToInt::class => [
+        'implements' => [ResolvesToNumber::class],
+        'types' => ['int', BSON\Int64::class],
+    ],
+    IntFieldPath::class => typeFieldPath(ResolvesToInt::class),
+    ResolvesToString::class => [
+        'implements' => [ExpressionInterface::class],
+        'types' => ['string'],
+    ],
+    StringFieldPath::class => typeFieldPath(ResolvesToString::class),
+];

generator/config/operators.php

@@ -0,0 +1,41 @@
+<?php
+
+namespace MongoDB\CodeGenerator\Config;
+
+use MongoDB\CodeGenerator\OperatorClassGenerator;
+use MongoDB\CodeGenerator\OperatorFactoryGenerator;
+
+return [
+    // Aggregation Pipeline Stages
+    [
+        'configFile' => __DIR__ . '/stages.yaml',
+        'namespace' => 'MongoDB\\Builder\\Stage',
+        'classNameSuffix' => 'Stage',
+        'generators' => [
+            OperatorClassGenerator::class,
+            OperatorFactoryGenerator::class,
+        ],
+    ],
+
+    // Aggregation Pipeline Operators
+    [
+        'configFile' => __DIR__ . '/pipeline-operators.yaml',
+        'namespace' => 'MongoDB\\Builder\\Aggregation',
+        'classNameSuffix' => 'Aggregation',
+        'generators' => [
+            OperatorClassGenerator::class,
+            OperatorFactoryGenerator::class,
+        ],
+    ],
+
+    // Query Operators
+    [
+        'configFile' => __DIR__ . '/query-operators.yaml',
+        'namespace' => 'MongoDB\\Builder\\Query',
+        'classNameSuffix' => 'Query',
+        'generators' => [
+            OperatorClassGenerator::class,
+            OperatorFactoryGenerator::class,
+        ],
+    ],
+];

generator/config/pipeline-operators.yaml

@@ -0,0 +1,66 @@
+- name: and
+  type: resolvesToBool
+  args:
+    - name: expressions
+      type: expression
+      isVariadic: true
+      variadicMin: 1
+- name: eq
+  encode: array
+  type: resolvesToBool
+  args:
+    - name: expression1
+      type: expression
+    - name: expression2
+      type: expression
+- name: gt
+  encode: array
+  type: resolvesToBool
+  args:
+    - name: expression1
+      type: expression
+    - name: expression2
+      type: expression
+- name: gte
+  encode: array
+  type: resolvesToBool
+  args:
+    - name: expression1
+      type: expression
+    - name: expression2
+      type: expression
+- name: lt
+  encode: array
+  type: resolvesToBool
+  args:
+    - name: expression1
+      type: expression
+    - name: expression2
+      type: expression
+- name: ne
+  encode: array
+  type: resolvesToBool
+  args:
+    - name: expression1
+      type: expression
+    - name: expression2
+      type: expression
+- name: filter
+  encode: object
+  type: resolvesToArray
+  args:
+    - name: input
+      type: resolvesToArray
+    - name: cond
+      type: resolvesToBool
+    - name: as
+      type: resolvesToString
+      isOptional: true
+    - name: limit
+      type: resolvesToInt
+      isOptional: true
+- name: sum
+  type: resolvesToInt
+  args:
+    - name: expression
+      type: expression

generator/config/query-operators.yaml

@@ -0,0 +1,32 @@
+- name: and
+  type: resolvesToBool
+  args:
+    - name: query
+      type: resolvesToBool
+      isVariadic: true
+- name: or
+  type: resolvesToBool
+  args:
+    - name: query
+      type: expression
+      isVariadic: true
+- name: expr
+  type: expression
+  args:
+    - name: expression
+      type: expression
+- name: gt
+  type: resolvesToBool
+  args:
+    - name: value
+      type: expression
+- name: lt
+  type: resolvesToBool
+  args:
+    - name: value
+      type: expression
+- name: gte
+  type: resolvesToBool
+  args:
+    - name: value
+      type: expression

generator/config/stages.yaml

@@ -0,0 +1,32 @@
+- name: match
+  type: stage
+  args:
+    - name: query
+      type: expression
+- name: sort
+  type: stage
+  args:
+    - name: sortSpecification
+      type: resolvesToObject
+- name: limit
+  type: stage
+  args:
+    - name: limit
+      type: resolvesToInt
+- name: group
+  type: stage
+  encode: object
+  args:
+    # @todo _id is not optional but only nullable
+    - name: _id
+      type: expression
+      isOptional: true
+    # @todo fields are optional and encoded at the same level as _id
+    - name: fields
+      type: resolvesToObject
+      isOptional: true
+- name: project
+  type: stage
+  args:
+    - name: specifications
+      type: resolvesToObject