PHPLIB-1322: Document codec option for classes and operations (#1264)

jmikola · web-flow · commit 35381c375f05 · 2024-03-25T12:19:48.000-04:00
The bucket-option-codec and collection-option-codec do not inherit common-option-codec since Snooty does not yet support "post" for appending to inherited content.

* Note why Bucket's codec option is not passed to CollectionWrapper
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,3 +1,11 @@
+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
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/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,6 +44,13 @@ 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.
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__construct.txt b/docs/reference/method/MongoDBGridFSBucket__construct.txt
@@ -55,6 +55,13 @@ 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.
diff --git a/src/GridFS/Bucket.php b/src/GridFS/Bucket.php
@@ -186,6 +186,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);
