From 35381c375f05db1d54ab98b2e2d5373261c36d54 Mon Sep 17 00:00:00 2001 From: Jeremy Mikola Date: Mon, 25 Mar 2024 12:19:48 -0400 Subject: [PATCH] PHPLIB-1322: Document codec option for classes and operations (#1264) 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 --- docs/includes/extracts-bucket-option.yaml | 8 ++++++++ docs/includes/extracts-collection-option.yaml | 8 ++++++++ docs/includes/extracts-common-option.yaml | 5 +++++ docs/reference/method/MongoDBClient-selectCollection.txt | 7 +++++++ docs/reference/method/MongoDBClient-watch.txt | 6 ++++++ docs/reference/method/MongoDBCollection-aggregate.txt | 6 ++++++ docs/reference/method/MongoDBCollection-bulkWrite.txt | 9 +++++++++ docs/reference/method/MongoDBCollection-find.txt | 6 ++++++ docs/reference/method/MongoDBCollection-findOne.txt | 6 ++++++ .../method/MongoDBCollection-findOneAndReplace.txt | 6 ++++++ docs/reference/method/MongoDBCollection-insertMany.txt | 6 ++++++ docs/reference/method/MongoDBCollection-insertOne.txt | 6 ++++++ .../method/MongoDBCollection-listSearchIndexes.txt | 6 ++++++ docs/reference/method/MongoDBCollection-replaceOne.txt | 6 ++++++ docs/reference/method/MongoDBCollection-watch.txt | 6 ++++++ docs/reference/method/MongoDBCollection-withOptions.txt | 7 +++++++ docs/reference/method/MongoDBCollection__construct.txt | 7 +++++++ docs/reference/method/MongoDBDatabase-aggregate.txt | 6 ++++++ .../method/MongoDBDatabase-selectCollection.txt | 7 +++++++ .../method/MongoDBDatabase-selectGridFSBucket.txt | 7 +++++++ docs/reference/method/MongoDBDatabase-watch.txt | 6 ++++++ docs/reference/method/MongoDBGridFSBucket-find.txt | 6 ++++++ docs/reference/method/MongoDBGridFSBucket-findOne.txt | 6 ++++++ docs/reference/method/MongoDBGridFSBucket__construct.txt | 7 +++++++ src/GridFS/Bucket.php | 5 +++++ 25 files changed, 161 insertions(+) diff --git a/docs/includes/extracts-bucket-option.yaml b/docs/includes/extracts-bucket-option.yaml index 0492ae9f0..a3eb915fd 100644 --- 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 ` 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 index 94d9b9b04..838a009f5 100644 --- 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 ` 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 index 65940b1c4..39cab3553 100644 --- 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 ` to use for encoding or decoding documents. + This option is mutually exclusive with the ``typeMap`` option. +--- ref: common-option-collation content: | :manual:`Collation ` allows users to specify diff --git a/docs/reference/method/MongoDBClient-selectCollection.txt b/docs/reference/method/MongoDBClient-selectCollection.txt index e7e58e865..c1984500e 100644 --- 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 ` to use for collection + operations. + + .. versionadded:: 1.17 + * - readConcern - :php:`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 index 1cee5f01c..336f38cc2 100644 --- 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 index 4566b92b6..acbbee088 100644 --- 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 ` and :ref:`$out ` 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 index f76d6ca68..db4bfb8f3 100644 --- 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 index 25cca0091..d6e5a74d7 100644 --- 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 index d00c58667..269d81ebb 100644 --- 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 index 48f6df291..c0a4cef1a 100644 --- 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 index 37f7d82f6..bcaec509a 100644 --- 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 index 7a638bdcc..d4b0d0de7 100644 --- 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 index cc0f840a8..73b586530 100644 --- 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 index f9bfb1b85..7a5444a1d 100644 --- 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 index 0722b6d76..083e129b4 100644 --- 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 index d942b8ccb..8123904b5 100644 --- 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 ` to use for collection + operations. Defaults to the original collection's codec. + + .. versionadded:: 1.17 + * - readConcern - :php:`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 index c4d2524fc..a74804472 100644 --- 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 ` to use for collection + operations. + + .. versionadded:: 1.17 + * - readConcern - :php:`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 index 665463154..8c0225863 100644 --- 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 ` and :ref:`$out ` 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 index 854298e09..b88179cde 100644 --- 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 ` to use for collection + operations. + + .. versionadded:: 1.17 + * - readConcern - :php:`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 index 9cebd3fcf..a931ba4ce 100644 --- 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 ` 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 index 396e5cfde..d8c53763b 100644 --- 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 index bfd570896..85344f7a3 100644 --- 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 index 89877e3a7..7bcc68604 100644 --- 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 index 766e8650d..b051361f6 100644 --- 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 ` 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 index 9b04e12f7..af7b71c00 100644 --- 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);