+ added SetField stage

+ added tests for SetField stage

Author: vincent-le-henaff

Diff for: lib/Doctrine/ODM/MongoDB/Aggregation/Builder.php

@@ -520,6 +520,22 @@ public function sample(int $size): Stage\Sample
         return $stage;
     }
 
+    /**
+     * Adds, updates, or removes a specified field in a document.
+     *
+     * You can use $setField to add, update, or remove fields with names that contain periods (.) or start with
+     * dollar signs ($).
+     *
+     * @see https://www.mongodb.com/docs/v5.0/reference/operator/aggregation/setField/#-setfield--aggregation-
+     */
+    public function setField(): Stage\SetField
+    {
+        $stage = new Stage\SetField($this);
+        $this->addStage($stage);
+
+        return $stage;
+    }
+
     /**
      * Skips over the specified number of documents that pass into the stage and
      * passes the remaining documents to the next stage in the pipeline.

Diff for: lib/Doctrine/ODM/MongoDB/Aggregation/Stage/SetField.php

@@ -0,0 +1,63 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\ODM\MongoDB\Aggregation\Stage;
+
+/**
+ * Fluent interface for adding a $setField stage to an aggregation pipeline.
+ */
+final class SetField extends Operator
+{
+    private ?string $field = null;
+
+    private ?string $input = null;
+
+    private ?string $value = null;
+
+    public function getExpression(): array
+    {
+        return [
+            '$setField' => [
+                'field' => $this->field,
+                'input' => $this->input,
+                'value' => $this->value,
+            ],
+        ];
+    }
+
+    /**
+     * Field in the input object that you want to add, update, or remove.
+     * Field can be any valid expression that resolves to a string constant.
+     */
+    public function field(string $field): self
+    {
+        $this->field = $field;
+
+        return $this;
+    }
+
+    /**
+     * Document that will contain the field that you want to add or update.
+     * Input must resolve to an object, missing, null, or undefined.
+     *
+     * Use $$ROOT to refer at the root document
+     */
+    public function input(string $input): self
+    {
+        $this->input = $input;
+
+        return $this;
+    }
+
+    /**
+     * The value that you want to assign to field. Value can be any valid expression.
+     * Set to $$REMOVE to remove field from the input document.
+     */
+    public function value(string $value): self
+    {
+        $this->value = $value;
+
+        return $this;
+    }
+}

Diff for: lib/Doctrine/ODM/MongoDB/Query/Builder.php

@@ -464,9 +464,8 @@ public function equals($value): self
      * If fields have been selected for inclusion, only the "_id" field may be
      * excluded.
      *
-     * @param string[]|string $fieldName,...
-     * @param null|string|string[] $fieldName
-     *
+     * @param string[]|string      $fieldName,...
+     * @param string|string[]|null $fieldName
      * @psalm-param 'comments'|array{0: 'name', 1: 'issues'}|null $fieldName
      */
     public function exclude($fieldName = null): self
@@ -1291,7 +1290,7 @@ public function returnNew(bool $bool = true): self
     /**
      * Set one or more fields to be included in the query projection.
      *
-     * @param null|string|string[] $fieldName
+     * @param string|string[]|null $fieldName
      *
      * @return Builder
      */

Diff for: lib/Doctrine/ODM/MongoDB/Types/DateImmutableType.php

@@ -7,6 +7,7 @@
 use DateTime;
 use DateTimeImmutable;
 use DateTimeInterface;
+use MongoDB\BSON\UTCDateTime;
 use RuntimeException;
 
 use function get_class;
@@ -15,9 +16,9 @@
 class DateImmutableType extends DateType
 {
     /**
-     * @return DateTimeImmutable
+     * @param UTCDateTime|float $value
      *
-     * @param \MongoDB\BSON\UTCDateTime|float $value
+     * @return DateTimeImmutable
      */
     public static function getDateTime($value): DateTimeInterface
     {

Diff for: tests/Doctrine/ODM/MongoDB/Tests/Aggregation/Stage/SetFieldTest.php

@@ -0,0 +1,55 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\ODM\MongoDB\Tests\Aggregation\Stage;
+
+use Doctrine\ODM\MongoDB\Aggregation\Stage\SetField;
+use Doctrine\ODM\MongoDB\Tests\Aggregation\AggregationTestTrait;
+use Doctrine\ODM\MongoDB\Tests\BaseTest;
+
+class SetFieldTest extends BaseTest
+{
+    use AggregationTestTrait;
+
+    public function testSetFieldStage(): void
+    {
+        $setFieldStage = new SetField($this->getTestAggregationBuilder());
+        $setFieldStage
+            ->field('hello')
+            ->input('$$ROOT')
+            ->value('world');
+
+        $expectedExpression = [
+            '$setField' => [
+                'field' => 'hello',
+                'input' => '$$ROOT',
+                'value' => 'world',
+            ]
+        ];
+
+        self::assertSame($expectedExpression, $setFieldStage->getExpression());
+    }
+
+    public function testStageFromBuilder(): void
+    {
+        $builder = $this->getTestAggregationBuilder();
+        $builder
+            ->setField()
+            ->field('hello')
+            ->input('$$ROOT')
+            ->value('world');
+
+        $expectedPipeline = [
+            [
+                '$setField' => [
+                    'field' => 'hello',
+                    'input' => '$$ROOT',
+                    'value' => 'world',
+                ]
+            ]
+        ];
+
+        self::assertSame($expectedPipeline, $builder->getPipeline());
+    }
+}