PHPLIB-749: Support comment option on command helpers

docs/includes/apiargs-MongoDBCollection-method-aggregate-option.yaml

@@ -11,7 +11,7 @@ source:
   ref: bypassDocumentValidation
 ---
 source:
-  file: apiargs-aggregate-option.yaml
+  file: apiargs-common-option.yaml
   ref: comment
 post: |
   .. versionadded:: 1.3

docs/includes/apiargs-MongoDBCollection-method-bulkWrite-option.yaml

@@ -2,6 +2,12 @@ source:
   file: apiargs-MongoDBCollection-common-option.yaml
   ref: bypassDocumentValidation
 ---
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+post: |
+  .. versionadded:: 1.13
+---
 source:
   file: apiargs-common-option.yaml
   ref: let

docs/includes/apiargs-MongoDBCollection-method-count-option.yaml

@@ -2,6 +2,12 @@ source:
   file: apiargs-MongoDBCollection-common-option.yaml
   ref: collation
 ---
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+post: |
+  .. versionadded:: 1.13
+---
 arg_name: option
 name: hint
 type: string|array|object

docs/includes/apiargs-MongoDBCollection-method-countDocuments-option.yaml

@@ -2,6 +2,12 @@ source:
   file: apiargs-MongoDBCollection-common-option.yaml
   ref: collation
 ---
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+post: |
+  .. versionadded:: 1.13
+---
 arg_name: option
 name: hint
 type: string|array|object

docs/includes/apiargs-MongoDBCollection-method-deleteMany-option.yaml

@@ -2,6 +2,12 @@ source:
   file: apiargs-MongoDBCollection-common-option.yaml
   ref: collation
 ---
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+post: |
+  .. versionadded:: 1.13
+---
 source:
   file: apiargs-common-option.yaml
   ref: hint

docs/includes/apiargs-MongoDBCollection-method-deleteOne-option.yaml

@@ -2,6 +2,12 @@ source:
   file: apiargs-MongoDBCollection-common-option.yaml
   ref: collation
 ---
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+post: |
+  .. versionadded:: 1.13
+---
 source:
   file: apiargs-common-option.yaml
   ref: hint

docs/includes/apiargs-MongoDBCollection-method-estimateDocumentCount-option.yaml

@@ -1,3 +1,9 @@
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+post: |
+  .. versionadded:: 1.13
+---
 source:
   file: apiargs-common-option.yaml
   ref: maxTimeMS

docs/includes/apiargs-MongoDBCollection-method-find-option.yaml

@@ -74,15 +74,11 @@ source:
   file: apiargs-MongoDBCollection-common-option.yaml
   ref: collation
 ---
-arg_name: option
-name: comment
-type: string
-description: |
-  A comment to attach to the query to help interpret and trace query
-  :dbcommand:`profile` data.
-interface: phpmethod
-operation: ~
-optional: true
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+post: |
+  .. versionadded:: 1.13
 ---
 arg_name: option
 name: cursorType

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

@@ -19,8 +19,10 @@ source:
   ref: collation
 ---
 source:
-  file: apiargs-MongoDBCollection-method-find-option.yaml
+  file: apiargs-common-option.yaml
   ref: comment
+post: |
+  .. versionadded:: 1.13
 ---
 source:
   file: apiargs-common-option.yaml

docs/includes/apiargs-MongoDBCollection-method-findOneAndDelete-option.yaml

@@ -10,6 +10,12 @@ source:
   file: apiargs-MongoDBCollection-common-option.yaml
   ref: collation
 ---
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+post: |
+  .. versionadded:: 1.13
+---
 source:
   file: apiargs-common-option.yaml
   ref: hint

docs/includes/apiargs-MongoDBCollection-method-findOneAndReplace-option.yaml

@@ -10,6 +10,12 @@ source:
   file: apiargs-MongoDBCollection-common-option.yaml
   ref: collation
 ---
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+post: |
+  .. versionadded:: 1.13
+---
 source:
   file: apiargs-common-option.yaml
   ref: hint

docs/includes/apiargs-MongoDBCollection-method-findOneAndUpdate-option.yaml

@@ -16,6 +16,12 @@ source:
   file: apiargs-MongoDBCollection-common-option.yaml
   ref: collation
 ---
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+post: |
+  .. versionadded:: 1.13
+---
 source:
   file: apiargs-common-option.yaml
   ref: hint

docs/includes/apiargs-MongoDBCollection-method-insertMany-option.yaml

@@ -2,6 +2,12 @@ source:
   file: apiargs-MongoDBCollection-common-option.yaml
   ref: bypassDocumentValidation
 ---
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+post: |
+  .. versionadded:: 1.13
+---
 source:
   file: apiargs-MongoDBCollection-method-bulkWrite-option.yaml
   ref: ordered

docs/includes/apiargs-MongoDBCollection-method-insertOne-option.yaml

@@ -2,6 +2,12 @@ source:
   file: apiargs-MongoDBCollection-common-option.yaml
   ref: bypassDocumentValidation
 ---
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+post: |
+  .. versionadded:: 1.13
+---
 source:
   file: apiargs-common-option.yaml
   ref: session

docs/includes/apiargs-MongoDBCollection-method-replaceOne-option.yaml

@@ -10,6 +10,12 @@ source:
   file: apiargs-MongoDBCollection-common-option.yaml
   ref: collation
 ---
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+post: |
+  .. versionadded:: 1.13
+---
 source:
   file: apiargs-common-option.yaml
   ref: hint

docs/includes/apiargs-MongoDBCollection-method-updateMany-option.yaml

@@ -16,6 +16,12 @@ source:
   file: apiargs-MongoDBCollection-common-option.yaml
   ref: collation
 ---
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+post: |
+  .. versionadded:: 1.13
+---
 source:
   file: apiargs-common-option.yaml
   ref: hint

docs/includes/apiargs-MongoDBCollection-method-updateOne-option.yaml

@@ -16,6 +16,12 @@ source:
   file: apiargs-MongoDBCollection-common-option.yaml
   ref: collation
 ---
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+post: |
+  .. versionadded:: 1.13
+---
 source:
   file: apiargs-common-option.yaml
   ref: hint

docs/includes/apiargs-MongoDBCollection-method-watch-option.yaml

@@ -7,6 +7,12 @@ source:
   file: apiargs-common-option.yaml
   ref: collation
 ---
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+post: |
+  .. versionadded:: 1.13
+---
 source:
   file: apiargs-method-watch-option.yaml
   ref: fullDocument

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

@@ -11,7 +11,7 @@ source:
   ref: bypassDocumentValidation
 ---
 source:
-  file: apiargs-aggregate-option.yaml
+  file: apiargs-common-option.yaml
   ref: comment
 ---
 source:

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

@@ -7,6 +7,12 @@ source:
   file: apiargs-common-option.yaml
   ref: collation
 ---
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+post: |
+  .. versionadded:: 1.13
+---
 source:
   file: apiargs-method-watch-option.yaml
   ref: fullDocument

docs/includes/apiargs-aggregate-option.yaml

@@ -27,16 +27,6 @@ post: |
   :ref:`$out <agg-merge>` stages.
 ---
 arg_name: option
-name: comment
-type: string
-description: |
-  Users can specify an arbitrary string to help trace the operation through the
-  database profiler, currentOp, and logs.
-interface: phpmethod
-operation: ~
-optional: true
----
-arg_name: option
 name: explain
 type: boolean
 description: |

docs/includes/apiargs-common-option.yaml

@@ -13,6 +13,22 @@ operation: ~
 optional: true
 ---
 arg_name: option
+name: comment
+type: mixed
+description: |
+  Enables users to specify an arbitrary comment to help trace the operation through
+  the database profiler, currentOp and logs. The default is to not send a value.
+
+  The comment can be any valid BSON type for server versions 4.4 and above.
+  Server versions between 3.6 and 4.2 only support string as comment,
+  and providing a non-string type will result in a server-side error.
+  Older server versions do not support comment for aggregate command at all,
+  and providing one will result in a server-side error.
+interface: phpmethod
+operation: ~
+optional: true
+---
+arg_name: option
 name: hint
 type: string|array|object
 description: |

src/Operation/Aggregate.php

@@ -86,8 +86,15 @@ class Aggregate implements Executable, Explainable
      *
      *  * collation (document): Collation specification.
      *
-     *  * comment (string): An arbitrary string to help trace the operation
-     *    through the database profiler, currentOp, and logs.
+     *  * comment (mixed): Enables users to specify an arbitrary comment to help trace
+     *    the operation through the database profiler, currentOp and logs. The
+     *    default is to not send a value.
+     *
+     *    The comment can be any valid BSON type for server versions 4.4 and above.
+     *    Server versions between 3.6 and 4.2 only support string as comment,
+     *    and providing a non-string type will result in a server-side error.
+     *    Older server versions do not support comment for aggregate command at all,
+     *    and providing one will result in a server-side error.
      *
      *  * explain (boolean): Specifies whether or not to return the information
      *    on the processing of the pipeline.
@@ -170,10 +177,6 @@ public function __construct($databaseName, $collectionName, array $pipeline, arr
             throw InvalidArgumentException::invalidType('"collation" option', $options['collation'], 'array or object');
         }
 
-        if (isset($options['comment']) && ! is_string($options['comment'])) {
-            throw InvalidArgumentException::invalidType('"comment" option', $options['comment'], 'string');
-        }
-
         if (isset($options['explain']) && ! is_bool($options['explain'])) {
             throw InvalidArgumentException::invalidType('"explain" option', $options['explain'], 'boolean');
         }

src/Operation/BulkWrite.php

@@ -103,6 +103,16 @@ class BulkWrite implements Executable
      *  * bypassDocumentValidation (boolean): If true, allows the write to
      *    circumvent document level validation. The default is false.
      *
+     *  * comment (mixed): Enables users to specify an arbitrary comment to help trace
+     *    the operation through the database profiler, currentOp and logs. The
+     *    default is to not send a value.
+     *
+     *    The comment can be any valid BSON type for server versions 4.4 and above.
+     *    Server versions between 3.6 and 4.2 only support string as comment,
+     *    and providing a non-string type will result in a server-side error.
+     *    Older server versions do not support comment for aggregate command at all,
+     *    and providing one will result in a server-side error.
+     *
      *  * ordered (boolean): If true, when an insert fails, return without
      *    performing the remaining writes. If false, when a write fails,
      *    continue with the remaining writes, if any. The default is true.
@@ -353,8 +363,10 @@ private function createBulkWriteOptions()
     {
         $options = ['ordered' => $this->options['ordered']];
 
-        if (isset($this->options['bypassDocumentValidation'])) {
-            $options['bypassDocumentValidation'] = $this->options['bypassDocumentValidation'];
+        foreach (['bypassDocumentValidation', 'comment'] as $option) {
+            if (isset($this->options[$option])) {
+                $options[$option] = $this->options[$option];
+            }
         }
 
         if (isset($this->options['let'])) {

src/Operation/Count.php

@@ -62,6 +62,16 @@ class Count implements Executable, Explainable
      *
      *  * collation (document): Collation specification.
      *
+     *  * comment (mixed): Enables users to specify an arbitrary comment to help trace
+     *    the operation through the database profiler, currentOp and logs. The
+     *    default is to not send a value.
+     *
+     *    The comment can be any valid BSON type for server versions 4.4 and above.
+     *    Server versions between 3.6 and 4.2 only support string as comment,
+     *    and providing a non-string type will result in a server-side error.
+     *    Older server versions do not support comment for aggregate command at all,
+     *    and providing one will result in a server-side error.
+     *
      *  * hint (string|document): The index to use. Specify either the index
      *    name as a string or the index key pattern as a document. If specified,
      *    then the query system will only consider plans using the hinted index.
@@ -195,7 +205,7 @@ private function createCommandDocument()
             $cmd['hint'] = is_array($this->options['hint']) ? (object) $this->options['hint'] : $this->options['hint'];
         }
 
-        foreach (['limit', 'maxTimeMS', 'skip'] as $option) {
+        foreach (['comment', 'limit', 'maxTimeMS', 'skip'] as $option) {
             if (isset($this->options[$option])) {
                 $cmd[$option] = $this->options[$option];
             }