PHPLIB-748: Support 'let' option for multiple CRUD commands (#910)

* Updating all necessary classes with new 'let' option support.
* Adding actual tests from specifications for "let" option by syncing unified spec tests with mongodb/specifications@1028c34
* Updating tests skips as some features are not yet implemented.
* Updating driver version requirements.
* Updating Mongo docs.

Co-authored-by: Jeremy Mikola <[email protected]>

Author: aleksandr-rudo

.evergreen/config.yml

@@ -591,14 +591,20 @@ axes:
   - id: driver-versions
     display_name: Driver Version
     values:
+      # TODO: Update to "1.14.0" once PHPC 1.14.0 is released
       - id: "oldest-supported"
-        display_name: "1.13.0"
+        # display_name: "1.14.0"
+        display_name: "1.14-dev (master)"
         variables:
-          EXTENSION_VERSION: "1.13.0"
+          # EXTENSION_VERSION: "1.14.0"
+          EXTENSION_BRANCH: "master"
+      # TODO: Update to "1.14.x"/"stable" once PHPC 1.14.0 is released
       - id: "latest-stable"
-        display_name: "1.13.x"
+        # display_name: "1.14.x"
+        display_name: "1.14-dev (master)"
         variables:
-          EXTENSION_VERSION: "stable"
+          # EXTENSION_VERSION: "stable"
+          EXTENSION_BRANCH: "master"
       - id: "latest-dev"
         display_name: "1.14-dev (master)"
         variables:

.github/workflows/coding-standards.yml

@@ -20,7 +20,7 @@ jobs:
         php-version:
           - "7.4"
         driver-version:
-          - "stable"
+          - "mongodb/mongo-php-driver@master"
 
     steps:
       - name: "Checkout"

.github/workflows/tests.yml

@@ -27,24 +27,24 @@ jobs:
         mongodb-version:
           - "4.4"
         driver-version:
-          - "stable"
+          - "mongodb/mongo-php-driver@master"
         topology:
           - "server"
         include:
           - os: "ubuntu-20.04"
             php-version: "8.0"
             mongodb-version: "5.0"
-            driver-version: "stable"
+            driver-version: "mongodb/mongo-php-driver@master"
             topology: "server"
           - os: "ubuntu-20.04"
             php-version: "8.0"
             mongodb-version: "4.4"
-            driver-version: "stable"
+            driver-version: "mongodb/mongo-php-driver@master"
             topology: "replica_set"
           - os: "ubuntu-20.04"
             php-version: "8.0"
             mongodb-version: "4.4"
-            driver-version: "stable"
+            driver-version: "mongodb/mongo-php-driver@master"
             topology: "sharded_cluster"
 
     steps:

composer.json

@@ -12,7 +12,7 @@
         "php": "^7.2 || ^8.0",
         "ext-hash": "*",
         "ext-json": "*",
-        "ext-mongodb": "^1.13.0",
+        "ext-mongodb": "^1.14.0",
         "jean85/pretty-package-versions": "^1.2 || ^2.0.1",
         "symfony/polyfill-php80": "^1.19"
     },

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

@@ -29,7 +29,7 @@ post: |
   .. versionadded:: 1.3
 ---
 source:
-  file: apiargs-aggregate-option.yaml
+  file: apiargs-common-option.yaml
   ref: let
 post: |
   .. versionadded:: 1.9

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: let
+post: |
+  .. versionadded:: 1.13
+---
 arg_name: option
 name: ordered
 type: boolean

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

@@ -11,6 +11,12 @@ post: |
 
   .. versionadded:: 1.7
 ---
+source:
+  file: apiargs-common-option.yaml
+  ref: let
+post: |
+  .. versionadded:: 1.13
+---
 source:
   file: apiargs-common-option.yaml
   ref: session

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

@@ -11,6 +11,12 @@ post: |
 
   .. versionadded:: 1.7
 ---
+source:
+  file: apiargs-common-option.yaml
+  ref: let
+post: |
+  .. versionadded:: 1.13
+---
 source:
   file: apiargs-common-option.yaml
   ref: session

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

@@ -257,4 +257,10 @@ description: |
 interface: phpmethod
 operation: ~
 optional: true
+---
+source:
+  file: apiargs-common-option.yaml
+  ref: let
+post: |
+  .. versionadded:: 1.13
 ...

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

@@ -75,4 +75,10 @@ source:
 source:
   file: apiargs-MongoDBCollection-method-find-option.yaml
   ref: modifiers
+---
+source:
+  file: apiargs-common-option.yaml
+  ref: let
+post: |
+  .. versionadded:: 1.13
 ...

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

@@ -19,6 +19,12 @@ post: |
 
   .. versionadded:: 1.7
 ---
+source:
+  file: apiargs-common-option.yaml
+  ref: let
+post: |
+  .. versionadded:: 1.13
+---
 source:
   file: apiargs-common-option.yaml
   ref: maxTimeMS

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

@@ -27,6 +27,12 @@ source:
   file: apiargs-MongoDBCollection-common-option.yaml
   ref: bypassDocumentValidation
 ---
+source:
+  file: apiargs-common-option.yaml
+  ref: let
+post: |
+  .. versionadded:: 1.13
+---
 arg_name: option
 name: returnDocument
 type: integer

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

@@ -33,6 +33,12 @@ source:
   file: apiargs-MongoDBCollection-common-option.yaml
   ref: bypassDocumentValidation
 ---
+source:
+  file: apiargs-common-option.yaml
+  ref: let
+post: |
+  .. versionadded:: 1.13
+---
 arg_name: option
 name: returnDocument
 type: integer

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

@@ -19,6 +19,12 @@ post: |
 
   .. versionadded:: 1.6
 ---
+source:
+  file: apiargs-common-option.yaml
+  ref: let
+post: |
+  .. versionadded:: 1.13
+---
 source:
   file: apiargs-common-option.yaml
   ref: session

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

@@ -25,6 +25,12 @@ post: |
 
   .. versionadded:: 1.6
 ---
+source:
+  file: apiargs-common-option.yaml
+  ref: let
+post: |
+  .. versionadded:: 1.13
+---
 source:
   file: apiargs-common-option.yaml
   ref: session

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

@@ -25,6 +25,12 @@ post: |
 
   .. versionadded:: 1.6
 ---
+source:
+  file: apiargs-common-option.yaml
+  ref: let
+post: |
+  .. versionadded:: 1.13
+---
 source:
   file: apiargs-common-option.yaml
   ref: session

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

@@ -23,7 +23,7 @@ source:
   ref: hint
 ---
 source:
-  file: apiargs-aggregate-option.yaml
+  file: apiargs-common-option.yaml
   ref: let
 post: |
   .. versionadded:: 1.9

docs/includes/apiargs-aggregate-option.yaml

@@ -45,18 +45,4 @@ description: |
 interface: phpmethod
 operation: ~
 optional: true
----
-arg_name: option
-name: let
-type: array|object
-description: |
-  Map of parameter names and values. Values must be constant or closed
-  expressions that do not reference document fields. Parameters can then be
-  accessed as variables in an aggregate expression context (e.g. ``$$var``).
-
-  This is not supported for server versions prior to 5.0 and will result in an
-  exception at execution time if used.
-interface: phpmethod
-operation: ~
-optional: true
 ...

docs/includes/apiargs-common-option.yaml

@@ -24,6 +24,20 @@ operation: ~
 optional: true
 ---
 arg_name: option
+name: let
+type: array|object
+description: |
+  Map of parameter names and values. Values must be constant or closed
+  expressions that do not reference document fields. Parameters can then be
+  accessed as variables in an aggregate expression context (e.g. ``$$var``).
+
+  This is not supported for server versions prior to 5.0 and will result in an
+  exception at execution time if used.
+interface: phpmethod
+operation: ~
+optional: true
+---
+arg_name: option
 name: maxTimeMS
 type: integer
 description: |

src/Operation/BulkWrite.php

@@ -107,6 +107,11 @@ class BulkWrite implements Executable
      *    performing the remaining writes. If false, when a write fails,
      *    continue with the remaining writes, if any. The default is true.
      *
+     *  * let (document): Map of parameter names and values. Values must be
+     *    constant or closed expressions that do not reference document fields.
+     *    Parameters can then be accessed as variables in an aggregate
+     *    expression context (e.g. "$$var").
+     *
      *  * session (MongoDB\Driver\Session): Client session.
      *
      *  * writeConcern (MongoDB\Driver\WriteConcern): Write concern.
@@ -275,6 +280,10 @@ public function __construct($databaseName, $collectionName, array $operations, a
             throw InvalidArgumentException::invalidType('"writeConcern" option', $options['writeConcern'], WriteConcern::class);
         }
 
+        if (isset($options['let']) && ! is_array($options['let']) && ! is_object($options['let'])) {
+            throw InvalidArgumentException::invalidType('"let" option', $options['let'], 'array or object');
+        }
+
         if (isset($options['bypassDocumentValidation']) && ! $options['bypassDocumentValidation']) {
             unset($options['bypassDocumentValidation']);
         }
@@ -348,6 +357,10 @@ private function createBulkWriteOptions()
             $options['bypassDocumentValidation'] = $this->options['bypassDocumentValidation'];
         }
 
+        if (isset($this->options['let'])) {
+            $options['let'] = (object) $this->options['let'];
+        }
+
         return $options;
     }
 

src/Operation/Delete.php

@@ -75,6 +75,11 @@ class Delete implements Executable, Explainable
      *    This is not supported for server versions < 4.4 and will result in an
      *    exception at execution time if used.
      *
+     *  * let (document): Map of parameter names and values. Values must be
+     *    constant or closed expressions that do not reference document fields.
+     *    Parameters can then be accessed as variables in an aggregate
+     *    expression context (e.g. "$$var").
+     *
      *  * session (MongoDB\Driver\Session): Client session.
      *
      *  * writeConcern (MongoDB\Driver\WriteConcern): Write concern.
@@ -114,6 +119,10 @@ public function __construct($databaseName, $collectionName, $filter, $limit, arr
             throw InvalidArgumentException::invalidType('"writeConcern" option', $options['writeConcern'], WriteConcern::class);
         }
 
+        if (isset($options['let']) && ! is_array($options['let']) && ! is_object($options['let'])) {
+            throw InvalidArgumentException::invalidType('"let" option', $options['let'], 'array or object');
+        }
+
         if (isset($options['writeConcern']) && $options['writeConcern']->isDefault()) {
             unset($options['writeConcern']);
         }
@@ -150,7 +159,7 @@ public function execute(Server $server)
             throw UnsupportedException::writeConcernNotSupportedInTransaction();
         }
 
-        $bulk = new Bulk();
+        $bulk = new Bulk($this->createBulkWriteOptions());
         $bulk->delete($this->filter, $this->createDeleteOptions());
 
         $writeResult = $server->executeBulkWrite($this->databaseName . '.' . $this->collectionName, $bulk, $this->createExecuteOptions());
@@ -176,6 +185,22 @@ public function getCommandDocument(Server $server)
         return $cmd;
     }
 
+    /**
+     * Create options for constructing the bulk write.
+     *
+     * @see https://php.net/manual/en/mongodb-driver-bulkwrite.construct.php
+     */
+    private function createBulkWriteOptions(): array
+    {
+        $options = [];
+
+        if (isset($this->options['let'])) {
+            $options['let'] = (object) $this->options['let'];
+        }
+
+        return $options;
+    }
+
     /**
      * Create options for the delete command.
      *

src/Operation/DeleteMany.php

@@ -49,6 +49,11 @@ class DeleteMany implements Executable, Explainable
      *    This is not supported for server versions < 4.4 and will result in an
      *    exception at execution time if used.
      *
+     *  * let (document): Map of parameter names and values. Values must be
+     *    constant or closed expressions that do not reference document fields.
+     *    Parameters can then be accessed as variables in an aggregate
+     *    expression context (e.g. "$$var").
+     *
      *  * session (MongoDB\Driver\Session): Client session.
      *
      *  * writeConcern (MongoDB\Driver\WriteConcern): Write concern.

src/Operation/DeleteOne.php

@@ -49,6 +49,11 @@ class DeleteOne implements Executable, Explainable
      *    This is not supported for server versions < 4.4 and will result in an
      *    exception at execution time if used.
      *
+     *  * let (document): Map of parameter names and values. Values must be
+     *    constant or closed expressions that do not reference document fields.
+     *    Parameters can then be accessed as variables in an aggregate
+     *    expression context (e.g. "$$var").
+     *
      *  * session (MongoDB\Driver\Session): Client session.
      *
      *  * writeConcern (MongoDB\Driver\WriteConcern): Write concern.