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

examples/aggregation-builder.php

@@ -0,0 +1,82 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * This example demonstrates how you can use the builder provided by this library to build an aggregation pipeline.
+ */
+
+namespace MongoDB\Examples\AggregationBuilder;
+
+use MongoDB\Builder\Aggregation;
+use MongoDB\Builder\BuilderEncoder;
+use MongoDB\Builder\Expression;
+use MongoDB\Builder\Pipeline;
+use MongoDB\Builder\Stage;
+use MongoDB\Client;
+
+use function assert;
+use function getenv;
+use function is_object;
+use function MongoDB\BSON\fromPHP;
+use function MongoDB\BSON\toRelaxedExtendedJSON;
+use function printf;
+use function random_int;
+
+require __DIR__ . '/../vendor/autoload.php';
+
+function toJSON(object $document): string
+{
+    return toRelaxedExtendedJSON(fromPHP($document));
+}
+
+$client = new Client(getenv('MONGODB_URI') ?: 'mongodb://127.0.0.1/');
+
+$collection = $client->test->aggregate;
+$collection->drop();
+
+$documents = [];
+
+for ($i = 0; $i < 100; $i++) {
+    $documents[] = ['randomValue' => random_int(0, 1000)];
+}
+
+$collection->insertMany($documents);
+
+$pipeline = new Pipeline(
+    Stage::group(
+        _id: null,
+        totalCount: Aggregation::sum(1),
+        evenCount: Aggregation::sum(
+            Aggregation::mod(
+                Expression::fieldPath('randomValue'),
+                2,
+            ),
+        ),
+        oddCount: Aggregation::sum(
+            Aggregation::subtract(
+                1,
+                Aggregation::mod(
+                    Expression::fieldPath('randomValue'),
+                    2,
+                ),
+            ),
+        ),
+        maxValue: Aggregation::max(
+            Expression::fieldPath('randomValue'),
+        ),
+        minValue: Aggregation::min(
+            Expression::fieldPath('randomValue'),
+        ),
+    ),
+);
+
+// @todo Accept a Pipeline instance in Collection::aggregate() and automatically encode it
+$encoder = new BuilderEncoder();
+$pipeline = $encoder->encode($pipeline);
+
+$cursor = $collection->aggregate($pipeline);
+
+foreach ($cursor as $document) {
+    assert(is_object($document));
+    printf("%s\n", toJSON($document));
+}

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: `./generate`
+
+## Configuration
+
+The `generator/config/*.yaml` files contains the list of operators and stages that are supported by the library.

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,116 @@
+<?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 [
+    'null' => ['scalar' => true, 'types' => ['null']],
+    'number' => ['scalar' => true, 'types' => ['int']],
+    'decimal' => ['scalar' => true, 'types' => ['float']],
+    'string' => ['scalar' => true, 'types' => ['string']],
+    'boolean' => ['scalar' => true, 'types' => ['bool']],
+
+    // 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,
+        ],
+    ],
+];