PHPLIB-1635 BuilderEncoder accepts an instance of encoder instead of a class string

Author: GromNaN

psalm-baseline.xml

@@ -41,6 +41,11 @@
       <code><![CDATA[stdClass]]></code>
     </MoreSpecificReturnType>
   </file>
+  <file src="src/Builder/BuilderEncoder.php">
+    <MixedReturnStatement>
+      <code><![CDATA[$encoder->encode($value)]]></code>
+    </MixedReturnStatement>
+  </file>
   <file src="src/Builder/Encoder/AbstractExpressionEncoder.php">
     <MixedAssignment>
       <code><![CDATA[$val]]></code>

src/Builder/BuilderEncoder.php

@@ -49,10 +49,10 @@ final class BuilderEncoder implements Encoder
         OperatorInterface::class => OperatorEncoder::class,
     ];
 
-    /** @var array<class-string, ExpressionEncoder|null> */
+    /** @var array<class-string, Encoder|null> */
     private array $cachedEncoders = [];
 
-    /** @param array<class-string, class-string<ExpressionEncoder>> $customEncoders */
+    /** @param array<class-string, Encoder> $customEncoders */
     public function __construct(private readonly array $customEncoders = [])
     {
     }
@@ -67,7 +67,7 @@ public function canEncode(mixed $value): bool
         return (bool) $this->getEncoderFor($value)?->canEncode($value);
     }
 
-    public function encode(mixed $value): stdClass|array|string|int
+    public function encode(mixed $value): mixed
     {
         $encoder = $this->getEncoderFor($value);
 
@@ -78,7 +78,7 @@ public function encode(mixed $value): stdClass|array|string|int
         return $encoder->encode($value);
     }
 
-    private function getEncoderFor(object $value): ExpressionEncoder|null
+    private function getEncoderFor(object $value): Encoder|null
     {
         $valueClass = $value::class;
         if (array_key_exists($valueClass, $this->cachedEncoders)) {
@@ -89,13 +89,22 @@ private function getEncoderFor(object $value): ExpressionEncoder|null
 
         // First attempt: match class name exactly
         if (isset($encoderList[$valueClass])) {
-            return $this->cachedEncoders[$valueClass] = new $encoderList[$valueClass]($this);
+            $encoder = $encoderList[$valueClass];
+            if (is_string($encoder)) {
+                $encoder = new $encoder($this);
+            }
+
+            return $this->cachedEncoders[$valueClass] = $encoder;
         }
 
         // Second attempt: catch child classes
-        foreach ($encoderList as $className => $encoderClass) {
+        foreach ($encoderList as $className => $encoder) {
             if ($value instanceof $className) {
-                return $this->cachedEncoders[$valueClass] = new $encoderClass($this);
+                if (is_string($encoder)) {
+                    $encoder = new $encoder($this);
+                }
+
+                return $this->cachedEncoders[$valueClass] = $encoder;
             }
         }
 

tests/Builder/BuilderEncoderTest.php

@@ -12,8 +12,11 @@
 use MongoDB\Builder\Pipeline;
 use MongoDB\Builder\Query;
 use MongoDB\Builder\Stage;
+use MongoDB\Builder\Type\FieldPathInterface;
 use MongoDB\Builder\Type\Sort;
 use MongoDB\Builder\Variable;
+use MongoDB\Codec\EncodeIfSupported;
+use MongoDB\Codec\Encoder;
 use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\TestCase;
 
@@ -337,10 +340,50 @@ public function testRedactStage(): void
         $this->assertSamePipeline($expected, $pipeline);
     }
 
+    public function testCustomEncoder(): void
+    {
+        $customEncoders = [
+            FieldPathInterface::class => new class implements Encoder {
+                use EncodeIfSupported;
+
+                public function canEncode(mixed $value): bool
+                {
+                    return $value instanceof FieldPathInterface;
+                }
+
+                public function encode(mixed $value)
+                {
+                    return '$prefix.' . $value->name;
+                }
+            },
+        ];
+        $codec = new BuilderEncoder($customEncoders);
+
+        $pipeline = new Pipeline(
+            Stage::project(
+                threeFavorites: Expression::slice(
+                    Expression::arrayFieldPath('items'),
+                    n: 3,
+                ),
+            ),
+        );
+
+        $expected = [
+            [
+                '$project' => [
+                    'threeFavorites' => [
+                        '$slice' => ['$prefix.items', 3],
+                    ],
+                ],
+            ],
+        ];
+
+        $this->assertSamePipeline($expected, $pipeline, $codec);
+    }
+
     /** @param list<array<string, mixed>> $expected */
-    private static function assertSamePipeline(array $expected, Pipeline $pipeline): void
+    private static function assertSamePipeline(array $expected, Pipeline $pipeline, BuilderEncoder $codec = new BuilderEncoder()): void
     {
-        $codec = new BuilderEncoder();
         $actual = $codec->encode($pipeline);
 
         // Normalize with BSON round-trip