PHPLIB-232, PHPLIB-238: Bucket typeMap option and findOne()

docs/includes/apiargs-MongoDBDatabase-method-selectGridFSBucket-option.yaml

@@ -31,6 +31,12 @@ replacement:
   resource: "bucket"
   parent: "database"
 ---
+source:
+  file: apiargs-common-option.yaml
+  ref: typeMap
+replacement:
+  parent: "database"
+---
 source:
   file: apiargs-common-option.yaml
   ref: writeConcern

docs/includes/apiargs-MongoDBGridFSBucket-method-construct-option.yaml

@@ -31,6 +31,10 @@ replacement:
   resource: "bucket"
   parent: "database"
 ---
+source:
+  file: apiargs-MongoDBClient-method-construct-driverOptions.yaml
+  ref: typeMap
+---
 source:
   file: apiargs-common-option.yaml
   ref: writeConcern

docs/includes/apiargs-MongoDBGridFSBucket-method-findOne-option.yaml

@@ -0,0 +1,42 @@
+source:
+  file: apiargs-MongoDBCollection-method-find-option.yaml
+  ref: projection
+---
+source:
+  file: apiargs-MongoDBCollection-method-find-option.yaml
+  ref: sort
+---
+source:
+  file: apiargs-MongoDBCollection-method-find-option.yaml
+  ref: skip
+---
+source:
+  file: apiargs-MongoDBCollection-common-option.yaml
+  ref: collation
+---
+source:
+  file: apiargs-MongoDBCollection-method-find-option.yaml
+  ref: comment
+---
+source:
+  file: apiargs-common-option.yaml
+  ref: maxTimeMS
+---
+source:
+  file: apiargs-MongoDBCollection-method-find-option.yaml
+  ref: readConcern
+---
+source:
+  file: apiargs-MongoDBGridFSBucket-method-find-option.yaml
+  ref: readPreference
+---
+source:
+  file: apiargs-MongoDBGridFSBucket-method-find-option.yaml
+  ref: typeMap
+post: |
+  This will be used for the returned result document.
+---
+source:
+  file: apiargs-MongoDBCollection-method-find-option.yaml
+  ref: modifiers
+...

docs/reference/class/MongoDBGridFSBucket.txt

@@ -40,6 +40,7 @@ Methods
    /reference/method/MongoDBGridFSBucket-downloadToStreamByName
    /reference/method/MongoDBGridFSBucket-drop
    /reference/method/MongoDBGridFSBucket-find
+   /reference/method/MongoDBGridFSBucket-findOne
    /reference/method/MongoDBGridFSBucket-getBucketName
    /reference/method/MongoDBGridFSBucket-getDatabaseName
    /reference/method/MongoDBGridFSBucket-getFileDocumentForStream

docs/reference/method/MongoDBCollection-findOne.txt

@@ -32,9 +32,9 @@ Definition
 Return Values
 -------------
 
-An array or object for the :term:`first document <natural order>` document that
-matched the query, or ``null`` if no document matched the query. The return type
-will depend on the ``typeMap`` option.
+An array or object for the :term:`first document <natural order>` that matched
+the query, or ``null`` if no document matched the query. The return type will
+depend on the ``typeMap`` option.
 
 Errors/Exceptions
 -----------------

docs/reference/method/MongoDBDatabase-selectGridFSBucket.txt

@@ -42,8 +42,8 @@ Errors/Exceptions
 Behavior
 --------
 
-The selected bucket inherits options such as read preference and write concern
-from the :phpclass:`Database <MongoDB\\Database>` object. Options may be
+The selected bucket inherits options such as read preference and type
+mapping from the :phpclass:`Database <MongoDB\\Database>` object. Options may be
 overridden via the ``$options`` parameter.
 
 Example

docs/reference/method/MongoDBGridFSBucket-find.txt

@@ -40,3 +40,4 @@ See Also
 --------
 
 - :phpmethod:`MongoDB\\Collection::find()`
+- :phpmethod:`MongoDB\\GridFS\\Bucket::findOne()`

docs/reference/method/MongoDBGridFSBucket-findOne.txt

@@ -0,0 +1,46 @@
+==================================
+MongoDB\\GridFS\\Bucket::findOne()
+==================================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Definition
+----------
+
+.. phpmethod:: MongoDB\\GridFS\\Bucket::findOne()
+
+   Finds a single document from the GridFS bucket's files collection matching
+   the query.
+
+   .. code-block:: php
+
+      function findOne($filter = [], array $options = []): array|object|null
+
+   This method has the following parameters:
+
+   .. include:: /includes/apiargs/MongoDBCollection-method-findOne-param.rst
+
+   The ``$options`` parameter supports the following options:
+
+   .. include:: /includes/apiargs/MongoDBGridFSBucket-method-findOne-option.rst
+
+Return Values
+-------------
+
+An array or object for the :term:`first document <natural order>` that matched
+the query, or ``null`` if no document matched the query. The return type will
+depend on the ``typeMap`` option.
+
+.. todo: add examples
+
+See Also
+--------
+
+- :phpmethod:`MongoDB\\Collection::findOne()`
+- :phpmethod:`MongoDB\\GridFS\\Bucket::find()`

docs/reference/method/MongoDBGridFSBucket-getFileDocumentForStream.txt

@@ -19,7 +19,7 @@ Definition
 
    .. code-block:: php
 
-      function getFileDocumentForStream($stream): object
+      function getFileDocumentForStream($stream): array|object
 
    This method has the following parameters:
 
@@ -28,7 +28,8 @@ Definition
 Return Values
 -------------
 
-The metadata document associated with the GridFS stream.
+The metadata document associated with the GridFS stream. The return type will
+depend on the bucket's ``typeMap`` option.
 
 .. todo: add examples
 

docs/reference/method/MongoDBGridFSBucket-getFileIdForStream.txt

@@ -28,8 +28,8 @@ Definition
 Return Values
 -------------
 
-The ``_id`` field of the metadata document associated with the GridFS
-stream.
+The ``_id`` field of the metadata document associated with the GridFS stream.
+The return type will depend on the bucket's ``typeMap`` option.
 
 .. todo: add examples
 

src/Database.php

@@ -317,6 +317,7 @@ public function selectGridFSBucket(array $options = [])
         $options += [
             'readConcern' => $this->readConcern,
             'readPreference' => $this->readPreference,
+            'typeMap' => $this->typeMap,
             'writeConcern' => $this->writeConcern,
         ];
 

src/GridFS/Bucket.php

@@ -23,6 +23,11 @@ class Bucket
 {
     private static $defaultBucketName = 'fs';
     private static $defaultChunkSizeBytes = 261120;
+    private static $defaultTypeMap = [
+        'array' => 'MongoDB\Model\BSONArray',
+        'document' => 'MongoDB\Model\BSONDocument',
+        'root' => 'MongoDB\Model\BSONDocument',
+    ];
     private static $streamWrapperProtocol = 'gridfs';
 
     private $collectionWrapper;
@@ -32,6 +37,7 @@ class Bucket
     private $chunkSizeBytes;
     private $readConcern;
     private $readPreference;
+    private $typeMap;
     private $writeConcern;
 
     /**
@@ -49,6 +55,8 @@ class Bucket
      *
      *  * readPreference (MongoDB\Driver\ReadPreference): Read preference.
      *
+     *  * typeMap (array): Default type map for cursors and BSON documents.
+     *
      *  * writeConcern (MongoDB\Driver\WriteConcern): Write concern.
      *
      * @param Manager $manager      Manager instance from the driver
@@ -79,6 +87,10 @@ public function __construct(Manager $manager, $databaseName, array $options = []
             throw InvalidArgumentException::invalidType('"readPreference" option', $options['readPreference'], 'MongoDB\Driver\ReadPreference');
         }
 
+        if (isset($options['typeMap']) && ! is_array($options['typeMap'])) {
+            throw InvalidArgumentException::invalidType('"typeMap" option', $options['typeMap'], 'array');
+        }
+
         if (isset($options['writeConcern']) && ! $options['writeConcern'] instanceof WriteConcern) {
             throw InvalidArgumentException::invalidType('"writeConcern" option', $options['writeConcern'], 'MongoDB\Driver\WriteConcern');
         }
@@ -89,9 +101,10 @@ public function __construct(Manager $manager, $databaseName, array $options = []
         $this->chunkSizeBytes = $options['chunkSizeBytes'];
         $this->readConcern = isset($options['readConcern']) ? $options['readConcern'] : $this->manager->getReadConcern();
         $this->readPreference = isset($options['readPreference']) ? $options['readPreference'] : $this->manager->getReadPreference();
+        $this->typeMap = isset($options['typeMap']) ? $options['typeMap'] : self::$defaultTypeMap;
         $this->writeConcern = isset($options['writeConcern']) ? $options['writeConcern'] : $this->manager->getWriteConcern();
 
-        $collectionOptions = array_intersect_key($options, ['readConcern' => 1, 'readPreference' => 1, 'writeConcern' => 1]);
+        $collectionOptions = array_intersect_key($options, ['readConcern' => 1, 'readPreference' => 1, 'typeMap' => 1, 'writeConcern' => 1]);
 
         $this->collectionWrapper = new CollectionWrapper($manager, $databaseName, $options['bucketName'], $collectionOptions);
         $this->registerStreamWrapper();
@@ -112,6 +125,7 @@ public function __debugInfo()
             'chunkSizeBytes' => $this->chunkSizeBytes,
             'readConcern' => $this->readConcern,
             'readPreference' => $this->readPreference,
+            'typeMap' => $this->typeMap,
             'writeConcern' => $this->writeConcern,
         ];
     }
@@ -204,11 +218,25 @@ public function drop()
      * @param array        $options Additional options
      * @return Cursor
      */
-    public function find($filter, array $options = [])
+    public function find($filter = [], array $options = [])
     {
         return $this->collectionWrapper->findFiles($filter, $options);
     }
 
+    /**
+     * Finds a single document from the GridFS bucket's files collection
+     * matching the query.
+     *
+     * @see FindOne::__construct() for supported options
+     * @param array|object $filter  Query by which to filter documents
+     * @param array        $options Additional options
+     * @return array|object|null
+     */
+    public function findOne($filter = [], array $options = [])
+    {
+        return $this->collectionWrapper->findOneFile($filter, $options);
+    }
+
     /**
      * Return the bucket name.
      *
@@ -233,22 +261,15 @@ public function getDatabaseName()
      * Gets the file document of the GridFS file associated with a stream.
      *
      * @param resource $stream GridFS stream
-     * @return stdClass
+     * @return array|object
      * @throws InvalidArgumentException
      */
     public function getFileDocumentForStream($stream)
     {
-        if ( ! is_resource($stream) || get_resource_type($stream) != "stream") {
-            throw InvalidArgumentException::invalidType('$stream', $stream, 'resource');
-        }
+        $file = $this->getRawFileDocumentForStream($stream);
 
-        $metadata = stream_get_meta_data($stream);
-
-        if (!$metadata['wrapper_data'] instanceof StreamWrapper) {
-            throw InvalidArgumentException::invalidType('$stream wrapper data', $metadata['wrapper_data'], 'MongoDB\Driver\GridFS\StreamWrapper');
-        }
-
-        return $metadata['wrapper_data']->getFile();
+        // Filter the raw document through the specified type map
+        return \MongoDB\BSON\toPHP(\MongoDB\BSON\fromPHP($file), $this->typeMap);
     }
 
     /**
@@ -261,7 +282,13 @@ public function getFileDocumentForStream($stream)
      */
     public function getFileIdForStream($stream)
     {
-        $file = $this->getFileDocumentForStream($stream);
+        $file = $this->getRawFileDocumentForStream($stream);
+
+        /* Filter the raw document through the specified type map, but override
+         * the root type so we can reliably access the ID.
+         */
+        $typeMap = ['root' => 'stdClass'] + $this->typeMap;
+        $file = \MongoDB\BSON\toPHP(\MongoDB\BSON\fromPHP($file), $typeMap);
 
         if ( ! isset($file->_id) && ! property_exists($file, '_id')) {
             throw new CorruptFileException('file._id does not exist');
@@ -466,6 +493,31 @@ private function getFilesNamespace()
         return sprintf('%s.%s.files', $this->databaseName, $this->bucketName);
     }
 
+    /**
+     * Gets the file document of the GridFS file associated with a stream.
+     *
+     * This returns the raw document from the StreamWrapper, which does not
+     * respect the Bucket's type map.
+     *
+     * @param resource $stream GridFS stream
+     * @return stdClass
+     * @throws InvalidArgumentException
+     */
+    private function getRawFileDocumentForStream($stream)
+    {
+        if ( ! is_resource($stream) || get_resource_type($stream) != "stream") {
+            throw InvalidArgumentException::invalidType('$stream', $stream, 'resource');
+        }
+
+        $metadata = stream_get_meta_data($stream);
+
+        if (!$metadata['wrapper_data'] instanceof StreamWrapper) {
+            throw InvalidArgumentException::invalidType('$stream wrapper data', $metadata['wrapper_data'], 'MongoDB\Driver\GridFS\StreamWrapper');
+        }
+
+        return $metadata['wrapper_data']->getFile();
+    }
+
     /**
      * Opens a readable stream for the GridFS file.
      *

src/GridFS/CollectionWrapper.php

@@ -68,8 +68,8 @@ public function deleteFileAndChunksById($id)
      */
     public function dropCollections()
     {
-        $this->filesCollection->drop();
-        $this->chunksCollection->drop();
+        $this->filesCollection->drop(['typeMap' => []]);
+        $this->chunksCollection->drop(['typeMap' => []]);
     }
 
     /**
@@ -140,6 +140,18 @@ public function findFiles($filter, array $options = [])
         return $this->filesCollection->find($filter, $options);
     }
 
+    /**
+     * Finds a single document from the GridFS bucket's files collection.
+     *
+     * @param array|object $filter  Query by which to filter documents
+     * @param array        $options Additional options
+     * @return array|object|null
+     */
+    public function findOneFile($filter, array $options = [])
+    {
+        return $this->filesCollection->findOne($filter, $options);
+    }
+
     /**
      * Return the bucket name.
      *
@@ -284,6 +296,7 @@ private function isFilesCollectionEmpty()
         return null === $this->filesCollection->findOne([], [
             'readPreference' => new ReadPreference(ReadPreference::RP_PRIMARY),
             'projection' => ['_id' => 1],
+            'typeMap' => [],
         ]);
     }
 }