PHPLIB-1505 Add driver option "builderEncoder"

mongodb · Sep 10, 2024 · c767ffe · c767ffe
1 parent d2a9458
commit c767ffe
Show file tree

Hide file tree

Showing 7 changed files with 151 additions and 64 deletions.
diff --git a/psalm-baseline.xml b/psalm-baseline.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<files psalm-version="5.25.0@01a8eb06b9e9cc6cfb6a320bf9fb14331919d505">
+<files psalm-version="5.26.1@d747f6500b38ac4f7dfc5edbcae6e4b637d7add0">
   <file src="examples/atlas_search.php">
     <MixedArgument>
       <code><![CDATA[$document['name']]]></code>
@@ -195,6 +195,9 @@
     <MixedAssignment>
       <code><![CDATA[$mergedDriver['platform']]]></code>
     </MixedAssignment>
+    <MixedPropertyTypeCoercion>
+      <code><![CDATA[$driverOptions['builderEncoder'] ?? new BuilderEncoder()]]></code>
+    </MixedPropertyTypeCoercion>
   </file>
   <file src="src/Codec/EncodeIfSupported.php">
     <ArgumentTypeCoercion>
@@ -216,6 +219,11 @@
       <code><![CDATA[$value]]></code>
     </MixedArgumentTypeCoercion>
   </file>
+  <file src="src/Collection.php">
+    <MixedPropertyTypeCoercion>
+      <code><![CDATA[$options['builderEncoder'] ?? new BuilderEncoder()]]></code>
+    </MixedPropertyTypeCoercion>
+  </file>
   <file src="src/Command/ListCollections.php">
     <MixedAssignment>
       <code><![CDATA[$cmd[$option]]]></code>
@@ -228,6 +236,11 @@
       <code><![CDATA[$options['session']]]></code>
     </MixedAssignment>
   </file>
+  <file src="src/Database.php">
+    <MixedPropertyTypeCoercion>
+      <code><![CDATA[$options['builderEncoder'] ?? new BuilderEncoder()]]></code>
+    </MixedPropertyTypeCoercion>
+  </file>
   <file src="src/GridFS/Bucket.php">
     <MixedArgument>
       <code><![CDATA[$options['revision']]]></code>

diff --git a/src/Client.php b/src/Client.php
@@ -19,6 +19,10 @@
 
 use Composer\InstalledVersions;
 use Iterator;
+use MongoDB\BSON\Document;
+use MongoDB\BSON\PackedArray;
+use MongoDB\Builder\BuilderEncoder;
+use MongoDB\Codec\Encoder;
 use MongoDB\Driver\ClientEncryption;
 use MongoDB\Driver\Exception\InvalidArgumentException as DriverInvalidArgumentException;
 use MongoDB\Driver\Exception\RuntimeException as DriverRuntimeException;
@@ -38,8 +42,10 @@
 use MongoDB\Operation\ListDatabaseNames;
 use MongoDB\Operation\ListDatabases;
 use MongoDB\Operation\Watch;
+use stdClass;
 use Throwable;
 
+use function array_diff_key;
 use function is_array;
 use function is_string;
 
@@ -67,6 +73,9 @@ class Client
 
     private array $typeMap;
 
+    /** @psalm-var Encoder<array|stdClass|Document|PackedArray, mixed> */
+    private readonly Encoder $builderEncoder;
+
     private WriteConcern $writeConcern;
 
     /**
@@ -78,6 +87,9 @@ class Client
      *
      * Supported driver-specific options:
      *
+     *  * builderEncoder (MongoDB\Builder\Encoder): Encoder for query and
+     *    aggregation builders. If not given, the default encoder will be used.
+     *
      *  * typeMap (array): Default type map for cursors and BSON documents.
      *
      * Other options are documented in MongoDB\Driver\Manager::__construct().
@@ -108,12 +120,17 @@ public function __construct(?string $uri = null, array $uriOptions = [], array $
             }
         }
 
+        if (isset($driverOptions['builderEncoder']) && ! $driverOptions['builderEncoder'] instanceof Encoder) {
+            throw InvalidArgumentException::invalidType('"builderEncoder" option', $driverOptions['builderEncoder'], Encoder::class);
+        }
+
         $driverOptions['driver'] = $this->mergeDriverInfo($driverOptions['driver'] ?? []);
 
         $this->uri = $uri ?? self::DEFAULT_URI;
+        $this->builderEncoder = $driverOptions['builderEncoder'] ?? new BuilderEncoder();
         $this->typeMap = $driverOptions['typeMap'];
 
-        unset($driverOptions['typeMap']);
+        $driverOptions = array_diff_key($driverOptions, ['builderEncoder' => 1, 'typeMap' => 1]);
 
         $this->manager = new Manager($uri, $uriOptions, $driverOptions);
         $this->readConcern = $this->manager->getReadConcern();
@@ -133,6 +150,7 @@ public function __debugInfo()
             'manager' => $this->manager,
             'uri' => $this->uri,
             'typeMap' => $this->typeMap,
+            'builderEncoder' => $this->builderEncoder,
             'writeConcern' => $this->writeConcern,
         ];
     }
@@ -329,7 +347,7 @@ final public function removeSubscriber(Subscriber $subscriber): void
      */
     public function selectCollection(string $databaseName, string $collectionName, array $options = [])
     {
-        $options += ['typeMap' => $this->typeMap];
+        $options += ['typeMap' => $this->typeMap, 'builderEncoder' => $this->builderEncoder];
 
         return new Collection($this->manager, $databaseName, $collectionName, $options);
     }
@@ -345,7 +363,7 @@ public function selectCollection(string $databaseName, string $collectionName, a
      */
     public function selectDatabase(string $databaseName, array $options = [])
     {
-        $options += ['typeMap' => $this->typeMap];
+        $options += ['typeMap' => $this->typeMap, 'builderEncoder' => $this->builderEncoder];
 
         return new Database($this->manager, $databaseName, $options);
     }

diff --git a/src/Collection.php b/src/Collection.php
@@ -19,8 +19,12 @@
 
 use Countable;
 use Iterator;
+use MongoDB\BSON\Document;
 use MongoDB\BSON\JavascriptInterface;
+use MongoDB\BSON\PackedArray;
+use MongoDB\Builder\BuilderEncoder;
 use MongoDB\Codec\DocumentCodec;
+use MongoDB\Codec\Encoder;
 use MongoDB\Driver\CursorInterface;
 use MongoDB\Driver\Exception\RuntimeException as DriverRuntimeException;
 use MongoDB\Driver\Manager;
@@ -66,6 +70,7 @@
 use MongoDB\Operation\UpdateOne;
 use MongoDB\Operation\UpdateSearchIndex;
 use MongoDB\Operation\Watch;
+use stdClass;
 
 use function array_diff_key;
 use function array_intersect_key;
@@ -84,6 +89,9 @@ class Collection
 
     private const WIRE_VERSION_FOR_READ_CONCERN_WITH_WRITE_STAGE = 8;
 
+    /** @psalm-var Encoder<array|stdClass|Document|PackedArray, mixed> */
+    private readonly Encoder $builderEncoder;
+
     private ?DocumentCodec $codec = null;
 
     private ReadConcern $readConcern;
@@ -102,6 +110,9 @@ class Collection
      *
      * Supported options:
      *
+     *  * builderEncoder (MongoDB\Builder\Encoder): Encoder for query and
+     *    aggregation builders. If not given, the default encoder will be used.
+     *
      *  * codec (MongoDB\Codec\DocumentCodec): Codec used to decode documents
      *    from BSON to PHP objects.
      *
@@ -134,6 +145,10 @@ public function __construct(private Manager $manager, private string $databaseNa
             throw new InvalidArgumentException('$collectionName is invalid: ' . $collectionName);
         }
 
+        if (isset($options['builderEncoder']) && ! $options['builderEncoder'] instanceof Encoder) {
+            throw InvalidArgumentException::invalidType('"builderEncoder" option', $options['builderEncoder'], Encoder::class);
+        }
+
         if (isset($options['codec']) && ! $options['codec'] instanceof DocumentCodec) {
             throw InvalidArgumentException::invalidType('"codec" option', $options['codec'], DocumentCodec::class);
         }
@@ -154,6 +169,7 @@ public function __construct(private Manager $manager, private string $databaseNa
             throw InvalidArgumentException::invalidType('"writeConcern" option', $options['writeConcern'], WriteConcern::class);
         }
 
+        $this->builderEncoder = $options['builderEncoder'] ?? new BuilderEncoder();
         $this->codec = $options['codec'] ?? null;
         $this->readConcern = $options['readConcern'] ?? $this->manager->getReadConcern();
         $this->readPreference = $options['readPreference'] ?? $this->manager->getReadPreference();
@@ -170,6 +186,7 @@ public function __construct(private Manager $manager, private string $databaseNa
     public function __debugInfo()
     {
         return [
+            'builderEncoder' => $this->builderEncoder,
             'codec' => $this->codec,
             'collectionName' => $this->collectionName,
             'databaseName' => $this->databaseName,
@@ -1084,6 +1101,7 @@ public function watch(array $pipeline = [], array $options = [])
     public function withOptions(array $options = [])
     {
         $options += [
+            'builderEncoder' => $this->builderEncoder,
             'codec' => $this->codec,
             'readConcern' => $this->readConcern,
             'readPreference' => $this->readPreference,

diff --git a/src/Database.php b/src/Database.php
@@ -18,6 +18,10 @@
 namespace MongoDB;
 
 use Iterator;
+use MongoDB\BSON\Document;
+use MongoDB\BSON\PackedArray;
+use MongoDB\Builder\BuilderEncoder;
+use MongoDB\Codec\Encoder;
 use MongoDB\Driver\ClientEncryption;
 use MongoDB\Driver\Cursor;
 use MongoDB\Driver\Exception\RuntimeException as DriverRuntimeException;
@@ -45,6 +49,7 @@
 use MongoDB\Operation\ModifyCollection;
 use MongoDB\Operation\RenameCollection;
 use MongoDB\Operation\Watch;
+use stdClass;
 use Throwable;
 use Traversable;
 
@@ -61,6 +66,9 @@ class Database
 
     private const WIRE_VERSION_FOR_READ_CONCERN_WITH_WRITE_STAGE = 8;
 
+    /** @psalm-var Encoder<array|stdClass|Document|PackedArray, mixed> */
+    private readonly Encoder $builderEncoder;
+
     private ReadConcern $readConcern;
 
     private ReadPreference $readPreference;
@@ -77,6 +85,9 @@ class Database
      *
      * Supported options:
      *
+     *  * builderEncoder (MongoDB\Builder\Encoder): Encoder for query and
+     *    aggregation builders. If not given, the default encoder will be used.
+     *
      *  * readConcern (MongoDB\Driver\ReadConcern): The default read concern to
      *    use for database operations and selected collections. Defaults to the
      *    Manager's read concern.
@@ -102,6 +113,10 @@ public function __construct(private Manager $manager, private string $databaseNa
             throw new InvalidArgumentException('$databaseName is invalid: ' . $databaseName);
         }
 
+        if (isset($options['builderEncoder']) && ! $options['builderEncoder'] instanceof Encoder) {
+            throw InvalidArgumentException::invalidType('"builderEncoder" option', $options['builderEncoder'], Encoder::class);
+        }
+
         if (isset($options['readConcern']) && ! $options['readConcern'] instanceof ReadConcern) {
             throw InvalidArgumentException::invalidType('"readConcern" option', $options['readConcern'], ReadConcern::class);
         }
@@ -118,6 +133,7 @@ public function __construct(private Manager $manager, private string $databaseNa
             throw InvalidArgumentException::invalidType('"writeConcern" option', $options['writeConcern'], WriteConcern::class);
         }
 
+        $this->builderEncoder = $options['builderEncoder'] ?? new BuilderEncoder();
         $this->readConcern = $options['readConcern'] ?? $this->manager->getReadConcern();
         $this->readPreference = $options['readPreference'] ?? $this->manager->getReadPreference();
         $this->typeMap = $options['typeMap'] ?? self::DEFAULT_TYPE_MAP;
@@ -133,6 +149,7 @@ public function __construct(private Manager $manager, private string $databaseNa
     public function __debugInfo()
     {
         return [
+            'builderEncoder' => $this->builderEncoder,
             'databaseName' => $this->databaseName,
             'manager' => $this->manager,
             'readConcern' => $this->readConcern,
@@ -553,6 +570,7 @@ public function renameCollection(string $fromCollectionName, string $toCollectio
     public function selectCollection(string $collectionName, array $options = [])
     {
         $options += [
+            'builderEncoder' => $this->builderEncoder,
             'readConcern' => $this->readConcern,
             'readPreference' => $this->readPreference,
             'typeMap' => $this->typeMap,

diff --git a/tests/ClientTest.php b/tests/ClientTest.php
@@ -3,6 +3,7 @@
 namespace MongoDB\Tests;
 
 use MongoDB\Client;
+use MongoDB\Codec\Encoder;
 use MongoDB\Driver\ClientEncryption;
 use MongoDB\Driver\Exception\InvalidArgumentException as DriverInvalidArgumentException;
 use MongoDB\Driver\ReadConcern;
@@ -45,6 +46,10 @@ public function provideInvalidConstructorDriverOptions()
     {
         $options = [];
 
+        foreach ($this->getInvalidObjectValues() as $value) {
+            $options[][] = ['builderEncoder' => $value];
+        }
+
         foreach ($this->getInvalidArrayValues(true) as $value) {
             $options[][] = ['typeMap' => $value];
         }
@@ -85,13 +90,15 @@ public function testSelectCollectionInheritsOptions(): void
         ];
 
         $driverOptions = [
+            'builderEncoder' => $builderEncoder = $this->createMock(Encoder::class),
             'typeMap' => ['root' => 'array'],
         ];
 
         $client = new Client(static::getUri(), $uriOptions, $driverOptions);
         $collection = $client->selectCollection($this->getDatabaseName(), $this->getCollectionName());
         $debug = $collection->__debugInfo();
 
+        $this->assertSame($builderEncoder, $debug['builderEncoder']);
         $this->assertInstanceOf(ReadConcern::class, $debug['readConcern']);
         $this->assertSame(ReadConcern::LOCAL, $debug['readConcern']->getLevel());
         $this->assertInstanceOf(ReadPreference::class, $debug['readPreference']);
@@ -105,6 +112,7 @@ public function testSelectCollectionInheritsOptions(): void
     public function testSelectCollectionPassesOptions(): void
     {
         $collectionOptions = [
+            'builderEncoder' => $builderEncoder = $this->createMock(Encoder::class),
             'readConcern' => new ReadConcern(ReadConcern::LOCAL),
             'readPreference' => new ReadPreference(ReadPreference::SECONDARY_PREFERRED),
             'typeMap' => ['root' => 'array'],
@@ -115,6 +123,7 @@ public function testSelectCollectionPassesOptions(): void
         $collection = $client->selectCollection($this->getDatabaseName(), $this->getCollectionName(), $collectionOptions);
         $debug = $collection->__debugInfo();
 
+        $this->assertSame($builderEncoder, $debug['builderEncoder']);
         $this->assertInstanceOf(ReadConcern::class, $debug['readConcern']);
         $this->assertSame(ReadConcern::LOCAL, $debug['readConcern']->getLevel());
         $this->assertInstanceOf(ReadPreference::class, $debug['readPreference']);
@@ -129,11 +138,19 @@ public function testGetSelectsDatabaseAndInheritsOptions(): void
     {
         $uriOptions = ['w' => WriteConcern::MAJORITY];
 
-        $client = new Client(static::getUri(), $uriOptions);
+        $driverOptions = [
+            'builderEncoder' => $builderEncoder = $this->createMock(Encoder::class),
+            'typeMap' => ['root' => 'array'],
+        ];
+
+        $client = new Client(static::getUri(), $uriOptions, $driverOptions);
         $database = $client->{$this->getDatabaseName()};
         $debug = $database->__debugInfo();
 
+        $this->assertSame($builderEncoder, $debug['builderEncoder']);
         $this->assertSame($this->getDatabaseName(), $debug['databaseName']);
+        $this->assertIsArray($debug['typeMap']);
+        $this->assertSame(['root' => 'array'], $debug['typeMap']);
         $this->assertInstanceOf(WriteConcern::class, $debug['writeConcern']);
         $this->assertSame(WriteConcern::MAJORITY, $debug['writeConcern']->getW());
     }
@@ -147,13 +164,15 @@ public function testSelectDatabaseInheritsOptions(): void
         ];
 
         $driverOptions = [
+            'builderEncoder' => $builderEncoder = $this->createMock(Encoder::class),
             'typeMap' => ['root' => 'array'],
         ];
 
         $client = new Client(static::getUri(), $uriOptions, $driverOptions);
         $database = $client->selectDatabase($this->getDatabaseName());
         $debug = $database->__debugInfo();
 
+        $this->assertSame($builderEncoder, $debug['builderEncoder']);
         $this->assertInstanceOf(ReadConcern::class, $debug['readConcern']);
         $this->assertSame(ReadConcern::LOCAL, $debug['readConcern']->getLevel());
         $this->assertInstanceOf(ReadPreference::class, $debug['readPreference']);
@@ -167,6 +186,7 @@ public function testSelectDatabaseInheritsOptions(): void
     public function testSelectDatabasePassesOptions(): void
     {
         $databaseOptions = [
+            'builderEncoder' => $builderEncoder = $this->createMock(Encoder::class),
             'readConcern' => new ReadConcern(ReadConcern::LOCAL),
             'readPreference' => new ReadPreference(ReadPreference::SECONDARY_PREFERRED),
             'typeMap' => ['root' => 'array'],