Merge v1.17 into master (#1272)

jmikola · web-flow · commit f823cfd75356 · 2024-03-26T11:09:28.000-04:00
diff --git a/docs/includes/extracts-bucket-option.yaml b/docs/includes/extracts-bucket-option.yaml
@@ -1,3 +1,11 @@
+ref: bucket-option-codec
+content: |
+  The :doc:`codec </tutorial/codecs>` to use for encoding or decoding documents.
+  This option is mutually exclusive with the ``typeMap`` option.
+
+  Defaults to the bucket's codec. Inheritance for a default ``codec`` option
+  takes precedence over that of the ``typeMap`` option.
+---
 ref: bucket-option-readConcern
 source:
   ref: common-option-readConcern
diff --git a/docs/includes/extracts-collection-option.yaml b/docs/includes/extracts-collection-option.yaml
@@ -1,8 +1,19 @@
+ref: collection-option-codec
+content: |
+  The :doc:`codec </tutorial/codecs>` to use for encoding or decoding documents.
+  This option is mutually exclusive with the ``typeMap`` option.
+
+  Defaults to the collection's codec. Inheritance for a default ``codec`` option
+  takes precedence over that of the ``typeMap`` option.
+---
 ref: collection-option-collation
-source: 
-  ref: common-option-collation
-  file: extracts-common-option.yaml
-post: |
+content: |
+  :manual:`Collation </reference/collation>` allows users to specify
+  language-specific rules for string comparison, such as rules for lettercase
+  and accent marks. When specifying collation, the ``locale`` field is
+  mandatory; all other collation fields are optional. For descriptions of the
+  fields, see :manual:`Collation Document </reference/collation/#collation-document>`.
+
   If the collation is unspecified but the collection has a default collation,
   the operation uses the collation specified for the collection. If no
   collation is specified for the collection or for the operation, MongoDB uses
diff --git a/docs/includes/extracts-common-option.yaml b/docs/includes/extracts-common-option.yaml
@@ -1,3 +1,8 @@
+ref: common-option-codec
+content: |
+  The :doc:`codec </tutorial/codecs>` to use for encoding or decoding documents.
+  This option is mutually exclusive with the ``typeMap`` option.
+---
 ref: common-option-collation
 content: |
   :manual:`Collation </reference/collation>` allows users to specify
diff --git a/docs/includes/extracts-watch-option.yaml b/docs/includes/extracts-watch-option.yaml
@@ -61,7 +61,7 @@ content: |
 
      This is an option of the ``$changeStream`` pipeline stage.
 
-  .. versionadded: 1.13
+  .. versionadded:: 1.13
 ---
 ref: watch-option-maxAwaitTimeMS
 content: |
@@ -121,7 +121,7 @@ content: |
 
      This is an option of the ``$changeStream`` pipeline stage.
 
-  .. versionadded: 1.5
+  .. versionadded:: 1.5
 ---
 ref: watch-option-startAtOperationTime
 content: |
diff --git a/docs/reference/class/MongoDBCollection.txt b/docs/reference/class/MongoDBCollection.txt
@@ -144,4 +144,3 @@ Methods
 - :phpmethod:`MongoDB\Collection::updateSearchIndex()`
 - :phpmethod:`MongoDB\Collection::watch()`
 - :phpmethod:`MongoDB\Collection::withOptions()`
-
diff --git a/docs/reference/method/MongoDBClient-selectCollection.txt b/docs/reference/method/MongoDBClient-selectCollection.txt
@@ -45,6 +45,13 @@ Parameters
        - Type
        - Description
 
+     * - codec
+       - MongoDB\\Codec\\DocumentCodec
+       - The default :doc:`codec </tutorial/codecs>` to use for collection
+         operations.
+
+         .. versionadded:: 1.17
+
      * - readConcern
        - :php:`MongoDB\Driver\ReadConcern <class.mongodb-driver-readconcern>`
        - The default read concern to use for collection operations. Defaults to
diff --git a/docs/reference/method/MongoDBClient-watch.txt b/docs/reference/method/MongoDBClient-watch.txt
@@ -48,6 +48,12 @@ Parameters
        - integer
        - .. include:: /includes/extracts/watch-option-batchSize.rst
 
+     * - codec
+       - MongoDB\\Codec\\DocumentCodec
+       - .. include:: /includes/extracts/common-option-codec.rst
+
+         .. versionadded:: 1.17
+
      * - collation
        - array|object
        - .. include:: /includes/extracts/common-option-collation.rst
diff --git a/docs/reference/method/MongoDBCollection-aggregate.txt b/docs/reference/method/MongoDBCollection-aggregate.txt
@@ -70,6 +70,12 @@ Parameters
          This only applies when using the :ref:`$out <agg-out>` and
          :ref:`$out <agg-merge>` stages.
 
+     * - codec
+       - MongoDB\\Codec\\DocumentCodec
+       - .. include:: /includes/extracts/collection-option-codec.rst
+
+         .. versionadded:: 1.17
+
      * - collation
        - array|object
        - .. include:: /includes/extracts/collection-option-collation.rst
diff --git a/docs/reference/method/MongoDBCollection-bulkWrite.txt b/docs/reference/method/MongoDBCollection-bulkWrite.txt
@@ -70,6 +70,15 @@ Parameters
        - If ``true``, allows the write operation to circumvent document level
          validation. Defaults to ``false``.
 
+     * - codec
+       - MongoDB\\Codec\\DocumentCodec
+       - .. include:: /includes/extracts/collection-option-codec.rst
+
+         Bulk writes use the codec for ``insertOne`` and ``replaceOne``
+         operations.
+
+         .. versionadded:: 1.17
+
      * - comment
        - mixed
        - .. include:: /includes/extracts/common-option-comment.rst
diff --git a/docs/reference/method/MongoDBCollection-find.txt b/docs/reference/method/MongoDBCollection-find.txt
@@ -61,6 +61,12 @@ Parameters
          Unlike the previous wire protocol version, a batchSize of ``1`` for the
          :dbcommand:`find` command does not close the cursor.
 
+     * - codec
+       - MongoDB\\Codec\\DocumentCodec
+       - .. include:: /includes/extracts/collection-option-codec.rst
+
+         .. versionadded:: 1.17
+
      * - collation
        - array|object
        - .. include:: /includes/extracts/collection-option-collation.rst
diff --git a/docs/reference/method/MongoDBCollection-findOne.txt b/docs/reference/method/MongoDBCollection-findOne.txt
@@ -52,6 +52,12 @@ Parameters
          the :program:`mongos` if some shards are unavailable instead of
          throwing an error.
 
+     * - codec
+       - MongoDB\\Codec\\DocumentCodec
+       - .. include:: /includes/extracts/collection-option-codec.rst
+
+         .. versionadded:: 1.17
+
      * - collation
        - array|object
        - .. include:: /includes/extracts/collection-option-collation.rst
diff --git a/docs/reference/method/MongoDBCollection-findOneAndReplace.txt b/docs/reference/method/MongoDBCollection-findOneAndReplace.txt
@@ -50,6 +50,12 @@ Parameters
        - If ``true``, allows the write operation to circumvent document level
          validation. Defaults to ``false``.
 
+     * - codec
+       - MongoDB\\Codec\\DocumentCodec
+       - .. include:: /includes/extracts/collection-option-codec.rst
+
+         .. versionadded:: 1.17
+
      * - collation
        - array|object
        - .. include:: /includes/extracts/collection-option-collation.rst
diff --git a/docs/reference/method/MongoDBCollection-insertMany.txt b/docs/reference/method/MongoDBCollection-insertMany.txt
@@ -46,6 +46,12 @@ Parameters
        - If ``true``, allows the write operation to circumvent document level
          validation. Defaults to ``false``.
 
+     * - codec
+       - MongoDB\\Codec\\DocumentCodec
+       - .. include:: /includes/extracts/collection-option-codec.rst
+
+         .. versionadded:: 1.17
+
      * - comment
        - mixed
        - .. include:: /includes/extracts/common-option-comment.rst
diff --git a/docs/reference/method/MongoDBCollection-insertOne.txt b/docs/reference/method/MongoDBCollection-insertOne.txt
@@ -46,6 +46,12 @@ Parameters
        - If ``true``, allows the write operation to circumvent document level
          validation. Defaults to ``false``.
 
+     * - codec
+       - MongoDB\\Codec\\DocumentCodec
+       - .. include:: /includes/extracts/collection-option-codec.rst
+
+         .. versionadded:: 1.17
+
      * - comment
        - mixed
        - .. include:: /includes/extracts/common-option-comment.rst
diff --git a/docs/reference/method/MongoDBCollection-listSearchIndexes.txt b/docs/reference/method/MongoDBCollection-listSearchIndexes.txt
@@ -52,6 +52,12 @@ Parameters
          returning a cursor or failure from ``aggregate`` without doing
          significant server-side work.
 
+     * - codec
+       - MongoDB\\Codec\\DocumentCodec
+       - .. include:: /includes/extracts/collection-option-codec.rst
+
+         .. versionadded:: 1.17
+
      * - collation
        - array|object
        - .. include:: /includes/extracts/common-option-collation.rst
diff --git a/docs/reference/method/MongoDBCollection-replaceOne.txt b/docs/reference/method/MongoDBCollection-replaceOne.txt
@@ -52,6 +52,12 @@ Parameters
        - If ``true``, allows the write operation to circumvent document level
          validation. Defaults to ``false``.
 
+     * - codec
+       - MongoDB\\Codec\\DocumentCodec
+       - .. include:: /includes/extracts/collection-option-codec.rst
+
+         .. versionadded:: 1.17
+
      * - collation
        - array|object
        - .. include:: /includes/extracts/collection-option-collation.rst
diff --git a/docs/reference/method/MongoDBCollection-watch.txt b/docs/reference/method/MongoDBCollection-watch.txt
@@ -48,6 +48,12 @@ Parameters
        - integer
        - .. include:: /includes/extracts/watch-option-batchSize.rst
 
+     * - codec
+       - MongoDB\\Codec\\DocumentCodec
+       - .. include:: /includes/extracts/collection-option-codec.rst
+
+         .. versionadded:: 1.17
+
      * - collation
        - array|object
        - .. include:: /includes/extracts/common-option-collation.rst
diff --git a/docs/reference/method/MongoDBCollection-withOptions.txt b/docs/reference/method/MongoDBCollection-withOptions.txt
@@ -35,6 +35,13 @@ Parameters
        - Type
        - Description
 
+     * - codec
+       - MongoDB\\Codec\\DocumentCodec
+       - The default :doc:`codec </tutorial/codecs>` to use for collection
+         operations. Defaults to the original collection's codec.
+
+         .. versionadded:: 1.17
+
      * - readConcern
        - :php:`MongoDB\Driver\ReadConcern <class.mongodb-driver-readconcern>`
        - The default read concern to use for collection operations. Defaults to
diff --git a/docs/reference/method/MongoDBCollection__construct.txt b/docs/reference/method/MongoDBCollection__construct.txt
@@ -49,6 +49,13 @@ Definition
        - Type
        - Description
 
+     * - codec
+       - MongoDB\\Codec\\DocumentCodec
+       - The default :doc:`codec </tutorial/codecs>` to use for collection
+         operations.
+
+         .. versionadded:: 1.17
+
      * - readConcern
        - :php:`MongoDB\Driver\ReadConcern <class.mongodb-driver-readconcern>`
        - The default read concern to use for collection operations. Defaults to
diff --git a/docs/reference/method/MongoDBDatabase-aggregate.txt b/docs/reference/method/MongoDBDatabase-aggregate.txt
@@ -74,6 +74,12 @@ Parameters
          This only applies when using the :ref:`$out <agg-out>` and
          :ref:`$out <agg-merge>` stages.
 
+     * - codec
+       - MongoDB\\Codec\\DocumentCodec
+       - .. include:: /includes/extracts/common-option-codec.rst
+
+         .. versionadded:: 1.17
+
      * - collation
        - array|object
        - .. include:: /includes/extracts/common-option-collation.rst
diff --git a/docs/reference/method/MongoDBDatabase-selectCollection.txt b/docs/reference/method/MongoDBDatabase-selectCollection.txt
@@ -41,6 +41,13 @@ Parameters
        - Type
        - Description
 
+     * - codec
+       - MongoDB\\Codec\\DocumentCodec
+       - The default :doc:`codec </tutorial/codecs>` to use for collection
+         operations.
+
+         .. versionadded:: 1.17
+
      * - readConcern
        - :php:`MongoDB\Driver\ReadConcern <class.mongodb-driver-readconcern>`
        - The default read concern to use for collection operations. Defaults to
diff --git a/docs/reference/method/MongoDBDatabase-selectGridFSBucket.txt b/docs/reference/method/MongoDBDatabase-selectGridFSBucket.txt
@@ -44,13 +44,20 @@ Parameters
        - integer
        - The chunk size in bytes. Defaults to ``261120`` (i.e. 255 KiB).
 
+     * - codec
+       - MongoDB\\Codec\\DocumentCodec
+       - The default :doc:`codec </tutorial/codecs>` to use for bucket methods
+         that return a file document (e.g. :phpmethod:`MongoDB\GridFS\Bucket::find()`).
+
+         .. versionadded:: 1.17
+
      * - disableMD5
        - boolean
        - Whether to disable automatic MD5 generation when storing files.
 
          Defaults to ``false``. Only ``true`` will be supported in 2.0.
 
-         .. versionadded: 1.4
+         .. versionadded:: 1.4
 
      * - readConcern
        - :php:`MongoDB\Driver\ReadConcern <class.mongodb-driver-readconcern>`
diff --git a/docs/reference/method/MongoDBDatabase-watch.txt b/docs/reference/method/MongoDBDatabase-watch.txt
@@ -48,6 +48,12 @@ Parameters
        - integer
        - .. include:: /includes/extracts/watch-option-batchSize.rst
 
+     * - codec
+       - MongoDB\\Codec\\DocumentCodec
+       - .. include:: /includes/extracts/common-option-codec.rst
+
+         .. versionadded:: 1.17
+
      * - collation
        - array|object
        - .. include:: /includes/extracts/common-option-collation.rst
diff --git a/docs/reference/method/MongoDBGridFSBucket-find.txt b/docs/reference/method/MongoDBGridFSBucket-find.txt
@@ -61,6 +61,12 @@ Parameters
          Unlike the previous wire protocol version, a batchSize of ``1`` for the
          :dbcommand:`find` command does not close the cursor.
 
+     * - codec
+       - MongoDB\\Codec\\DocumentCodec
+       - .. include:: /includes/extracts/bucket-option-codec.rst
+
+         .. versionadded:: 1.17
+
      * - collation
        - array|object
        - .. include:: /includes/extracts/common-option-collation.rst
diff --git a/docs/reference/method/MongoDBGridFSBucket-findOne.txt b/docs/reference/method/MongoDBGridFSBucket-findOne.txt
@@ -53,6 +53,12 @@ Parameters
          the :program:`mongos` if some shards are unavailable instead of
          throwing an error.
 
+     * - codec
+       - MongoDB\\Codec\\DocumentCodec
+       - .. include:: /includes/extracts/bucket-option-codec.rst
+
+         .. versionadded:: 1.17
+
      * - collation
        - array|object
        - .. include:: /includes/extracts/common-option-collation.rst
diff --git a/docs/reference/method/MongoDBGridFSBucket-openUploadStream.txt b/docs/reference/method/MongoDBGridFSBucket-openUploadStream.txt
@@ -57,7 +57,7 @@ Parameters
 
          Defaults to ``false``. Only ``true`` will be supported in 2.0.
 
-         .. versionadded: 1.4
+         .. versionadded:: 1.4
 
      * - metadata
        - array|object
diff --git a/docs/reference/method/MongoDBGridFSBucket-uploadFromStream.txt b/docs/reference/method/MongoDBGridFSBucket-uploadFromStream.txt
@@ -61,7 +61,7 @@ Parameters
 
          Defaults to ``false``. Only ``true`` will be supported in 2.0.
 
-         .. versionadded: 1.4
+         .. versionadded:: 1.4
 
      * - metadata
        - array|object
diff --git a/docs/reference/method/MongoDBGridFSBucket__construct.txt b/docs/reference/method/MongoDBGridFSBucket__construct.txt
@@ -55,13 +55,20 @@ Parameters
        - integer
        - The chunk size in bytes. Defaults to ``261120`` (i.e. 255 KiB).
 
+     * - codec
+       - MongoDB\\Codec\\DocumentCodec
+       - The default :doc:`codec </tutorial/codecs>` to use for bucket methods
+         that return a file document (e.g. :phpmethod:`MongoDB\GridFS\Bucket::find()`).
+
+         .. versionadded:: 1.17
+
      * - disableMD5
        - boolean
        - Whether to disable automatic MD5 generation when storing files.
 
          Defaults to ``false``. Only ``true`` will be supported in 2.0.
 
-         .. versionadded: 1.4
+         .. versionadded:: 1.4
 
      * - readConcern
        - :php:`MongoDB\Driver\ReadConcern <class.mongodb-driver-readconcern>`
diff --git a/src/GridFS/Bucket.php b/src/GridFS/Bucket.php
@@ -196,6 +196,11 @@ public function __construct(Manager $manager, string $databaseName, array $optio
         $this->typeMap = $options['typeMap'] ?? self::DEFAULT_TYPE_MAP;
         $this->writeConcern = $options['writeConcern'] ?? $this->manager->getWriteConcern();
 
+        /* The codec option is intentionally omitted when constructing the files
+         * and chunks collections so as not to interfere with internal GridFS
+         * operations. Any codec will be manually applied when querying the
+         * files collection (i.e. find, findOne, and getFileDocumentForStream).
+         */
         $collectionOptions = array_intersect_key($options, ['readConcern' => 1, 'readPreference' => 1, 'typeMap' => 1, 'writeConcern' => 1]);
 
         $this->collectionWrapper = new CollectionWrapper($manager, $databaseName, $options['bucketName'], $collectionOptions);
