Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Mar 25, 2024
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
4b6f463
PHPLIB-1322: Document codec option for classes and operations
jmikola Mar 20, 2024
d6a22a0
Note why Bucket's codec option is not passed to CollectionWrapper
jmikola Mar 20, 2024
d1ecc09
Use present tense and active voice for bulkWrite docs
jmikola Mar 25, 2024
3bec6dd
Fix versionadded syntax
jmikola Mar 25, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions docs/includes/extracts-bucket-option.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,11 @@
ref: bucket-option-codec
content: |
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ccho-mongodb: I removed use of post here and for collection-option-codec. There is still an existing use of it in collection-option-collation, but I'll fix that in a separate PR against v1.16 and attribute it to DOCSP-37027.

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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This means if both the codec and the typeMap options are set in the bucket, we take the bucket. And if the codec is set to null in this method call, we use the typeMap from the Bucket?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This means if both the codec and the typeMap options are set in the bucket, we take the bucket codec.

Corrected what I assume is a typo.

And if the codec is set to null in this method call, we use the typeMap from the Bucket?

That is correct.

The PHPLIB docs have never discussed passing null for options. null values are typically ignored when we process options in Operation classes due to the use of isset().

If the codec option is null, the Bucket::find() and findOne() methods will still send it along to the CollectionWrapper since they use array_key_exists(); however, when it is ultimately received by the files collection's Collection::find() or findOne() method, the null value will be ignored based on the logic in Collection::inheritCodecOrTypeMap().

takes precedence over that of the ``typeMap`` option.
---
ref: bucket-option-readConcern
source:
ref: common-option-readConcern
Expand Down
8 changes: 8 additions & 0 deletions docs/includes/extracts-collection-option.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand Down
5 changes: 5 additions & 0 deletions docs/includes/extracts-common-option.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand Down
7 changes: 7 additions & 0 deletions docs/reference/method/MongoDBClient-selectCollection.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 6 additions & 0 deletions docs/reference/method/MongoDBClient-watch.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 6 additions & 0 deletions docs/reference/method/MongoDBCollection-aggregate.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
9 changes: 9 additions & 0 deletions docs/reference/method/MongoDBCollection-bulkWrite.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 6 additions & 0 deletions docs/reference/method/MongoDBCollection-find.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 6 additions & 0 deletions docs/reference/method/MongoDBCollection-findOne.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 6 additions & 0 deletions docs/reference/method/MongoDBCollection-findOneAndReplace.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 6 additions & 0 deletions docs/reference/method/MongoDBCollection-insertMany.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 6 additions & 0 deletions docs/reference/method/MongoDBCollection-insertOne.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 6 additions & 0 deletions docs/reference/method/MongoDBCollection-listSearchIndexes.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 6 additions & 0 deletions docs/reference/method/MongoDBCollection-replaceOne.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 6 additions & 0 deletions docs/reference/method/MongoDBCollection-watch.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
7 changes: 7 additions & 0 deletions docs/reference/method/MongoDBCollection-withOptions.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
7 changes: 7 additions & 0 deletions docs/reference/method/MongoDBCollection__construct.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 6 additions & 0 deletions docs/reference/method/MongoDBDatabase-aggregate.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
7 changes: 7 additions & 0 deletions docs/reference/method/MongoDBDatabase-selectCollection.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
7 changes: 7 additions & 0 deletions docs/reference/method/MongoDBDatabase-selectGridFSBucket.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
6 changes: 6 additions & 0 deletions docs/reference/method/MongoDBDatabase-watch.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 6 additions & 0 deletions docs/reference/method/MongoDBGridFSBucket-find.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 6 additions & 0 deletions docs/reference/method/MongoDBGridFSBucket-findOne.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
7 changes: 7 additions & 0 deletions docs/reference/method/MongoDBGridFSBucket__construct.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
5 changes: 5 additions & 0 deletions src/GridFS/Bucket.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down