From 33ca6c437107ecc14096bc88f85e6f9d1d240717 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= <jerome@tamarelle.net>
Date: Tue, 29 Jul 2025 09:44:48 +0200
Subject: [PATCH] PHPLIB-1695 Add $createObjectId operator to the agg builder

---
 .../config/expression/createObjectId.yaml     | 17 +++++++++++
 .../Expression/CreateObjectIdOperator.php     | 28 +++++++++++++++++++
 src/Builder/Expression/FactoryTrait.php       | 10 +++++++
 .../Expression/CreateObjectIdOperatorTest.php | 27 ++++++++++++++++++
 tests/Builder/Expression/Pipelines.php        | 17 +++++++++++
 5 files changed, 99 insertions(+)
 create mode 100644 generator/config/expression/createObjectId.yaml
 create mode 100644 src/Builder/Expression/CreateObjectIdOperator.php
 create mode 100644 tests/Builder/Expression/CreateObjectIdOperatorTest.php

diff --git a/generator/config/expression/createObjectId.yaml b/generator/config/expression/createObjectId.yaml
new file mode 100644
index 000000000..bab85d7f7
--- /dev/null
+++ b/generator/config/expression/createObjectId.yaml
@@ -0,0 +1,17 @@
+# $schema: ../schema.json
+name: $createObjectId
+link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/createObjectId/'
+type:
+  - resolvesToObjectId
+encode: object
+description: |
+  Returns a random object ID
+tests:
+  -
+    name: 'Example'
+    link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/createObjectId/#example'
+    pipeline:
+      -
+        $project:
+          objectId:
+            $createObjectId: {}
diff --git a/src/Builder/Expression/CreateObjectIdOperator.php b/src/Builder/Expression/CreateObjectIdOperator.php
new file mode 100644
index 000000000..eef57b3ca
--- /dev/null
+++ b/src/Builder/Expression/CreateObjectIdOperator.php
@@ -0,0 +1,28 @@
+<?php
+
+/**
+ * THIS FILE IS AUTO-GENERATED. ANY CHANGES WILL BE LOST!
+ */
+
+declare(strict_types=1);
+
+namespace MongoDB\Builder\Expression;
+
+use MongoDB\Builder\Type\Encode;
+use MongoDB\Builder\Type\OperatorInterface;
+
+/**
+ * Returns a random object ID
+ *
+ * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/createObjectId/
+ * @internal
+ */
+final class CreateObjectIdOperator implements ResolvesToObjectId, OperatorInterface
+{
+    public const ENCODE = Encode::Object;
+    public const NAME = '$createObjectId';
+
+    public function __construct()
+    {
+    }
+}
diff --git a/src/Builder/Expression/FactoryTrait.php b/src/Builder/Expression/FactoryTrait.php
index c7bd1d801..9eab9328d 100644
--- a/src/Builder/Expression/FactoryTrait.php
+++ b/src/Builder/Expression/FactoryTrait.php
@@ -427,6 +427,16 @@ public static function cosh(Decimal128|Int64|ResolvesToNumber|float|int|string $
         return new CoshOperator($expression);
     }
 
+    /**
+     * Returns a random object ID
+     *
+     * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/createObjectId/
+     */
+    public static function createObjectId(): CreateObjectIdOperator
+    {
+        return new CreateObjectIdOperator();
+    }
+
     /**
      * Adds a number of time units to a date object.
      *
diff --git a/tests/Builder/Expression/CreateObjectIdOperatorTest.php b/tests/Builder/Expression/CreateObjectIdOperatorTest.php
new file mode 100644
index 000000000..687d80638
--- /dev/null
+++ b/tests/Builder/Expression/CreateObjectIdOperatorTest.php
@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MongoDB\Tests\Builder\Expression;
+
+use MongoDB\Builder\Expression;
+use MongoDB\Builder\Pipeline;
+use MongoDB\Builder\Stage;
+use MongoDB\Tests\Builder\PipelineTestCase;
+
+/**
+ * Test $createObjectId expression
+ */
+class CreateObjectIdOperatorTest extends PipelineTestCase
+{
+    public function testExample(): void
+    {
+        $pipeline = new Pipeline(
+            Stage::project(
+                objectId: Expression::createObjectId(),
+            ),
+        );
+
+        $this->assertSamePipeline(Pipelines::CreateObjectIdExample, $pipeline);
+    }
+}
diff --git a/tests/Builder/Expression/Pipelines.php b/tests/Builder/Expression/Pipelines.php
index f84d00984..ab995bf68 100644
--- a/tests/Builder/Expression/Pipelines.php
+++ b/tests/Builder/Expression/Pipelines.php
@@ -910,6 +910,23 @@ enum Pipelines: string
     ]
     JSON;
 
+    /**
+     * Example
+     *
+     * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/createObjectId/#example
+     */
+    case CreateObjectIdExample = <<<'JSON'
+    [
+        {
+            "$project": {
+                "objectId": {
+                    "$createObjectId": {}
+                }
+            }
+        }
+    ]
+    JSON;
+
     /**
      * Add a Future Date
      *