PHPC-1462: Support hint for update commands

Author: jmikola

src/MongoDB/BulkWrite.c

@@ -237,6 +237,36 @@ static bool php_phongo_bulkwrite_opts_append_document(bson_t* opts, const char*
 		}                                                                                      \
 	}
 
+/* Initialize the "hint" option. Returns true on success; otherwise, false is
+ * returned and an exception is thrown.
+ *
+ * The "hint" option must be a string or document. Check for both types and
+ * merge into BSON options accordingly. */
+static bool php_phongo_bulkwrite_opt_hint(bson_t* boptions, zval* zoptions TSRMLS_DC) /* {{{ */
+{
+	/* The "hint" option (or "$hint" modifier) must be a string or document.
+	 * Check for both types and merge into BSON options accordingly. */
+	if (zoptions && php_array_existsc(zoptions, "hint")) {
+		zend_uchar type = Z_TYPE_P(php_array_fetchc(zoptions, "hint"));
+
+		if (type == IS_STRING) {
+			zval* value = php_array_fetchc(zoptions, "hint");
+
+			if (!bson_append_utf8(boptions, "hint", 4, Z_STRVAL_P(value), Z_STRLEN_P(value))) {
+				phongo_throw_exception(PHONGO_ERROR_INVALID_ARGUMENT TSRMLS_CC, "Error appending \"hint\" option");
+				return false;
+			}
+		} else if (type == IS_OBJECT || type == IS_ARRAY) {
+			PHONGO_BULKWRITE_OPT_DOCUMENT("hint");
+		} else {
+			phongo_throw_exception(PHONGO_ERROR_INVALID_ARGUMENT TSRMLS_CC, "Expected \"hint\" option to be string, array, or object, %s given", zend_get_type_by_const(type));
+			return false;
+		}
+	}
+
+	return true;
+} /* }}} */
+
 /* Applies options (including defaults) for an update operation. */
 static bool php_phongo_bulkwrite_update_apply_options(bson_t* boptions, zval* zoptions TSRMLS_DC) /* {{{ */
 {
@@ -252,6 +282,10 @@ static bool php_phongo_bulkwrite_update_apply_options(bson_t* boptions, zval* zo
 	PHONGO_BULKWRITE_OPT_ARRAY("arrayFilters");
 	PHONGO_BULKWRITE_OPT_DOCUMENT("collation");
 
+	if (!php_phongo_bulkwrite_opt_hint(boptions, zoptions TSRMLS_CC)) {
+		return false;
+	}
+
 	return true;
 } /* }}} */
 

tests/bulk/bulkwrite-update-004.phpt

@@ -0,0 +1,55 @@
+--TEST--
+MongoDB\Driver\BulkWrite::update() with hint option
+--SKIPIF--
+<?php require __DIR__ . "/../utils/basic-skipif.inc"; ?>
+<?php skip_if_not_live(); ?>
+<?php skip_if_server_version('<', '4.2'); ?>
+<?php skip_if_not_clean(); ?>
+--FILE--
+<?php
+require_once __DIR__ . "/../utils/basic.inc";
+
+class CommandLogger implements MongoDB\Driver\Monitoring\CommandSubscriber
+{
+    public function commandStarted(MongoDB\Driver\Monitoring\CommandStartedEvent $event)
+    {
+        if ($event->getCommandName() !== 'update') {
+            return;
+        }
+
+        printf("update included hint: %s\n", json_encode($event->getCommand()->updates[0]->hint));
+    }
+
+    public function commandSucceeded(MongoDB\Driver\Monitoring\CommandSucceededEvent $event)
+    {
+    }
+
+    public function commandFailed(MongoDB\Driver\Monitoring\CommandFailedEvent $event)
+    {
+    }
+}
+
+$manager = new MongoDB\Driver\Manager(URI);
+
+$bulk = new MongoDB\Driver\BulkWrite();
+$bulk->insert(['x' => 1]);
+$bulk->insert(['x' => 2]);
+$manager->executeBulkWrite(NS, $bulk);
+
+MongoDB\Driver\Monitoring\addSubscriber(new CommandLogger);
+
+$bulk = new MongoDB\Driver\BulkWrite;
+$bulk->update(['_id' => 1], ['$set' => ['x' => 11]], ['hint' => '_id_']);
+$manager->executeBulkWrite(NS, $bulk);
+
+$bulk = new MongoDB\Driver\BulkWrite;
+$bulk->update(['_id' => 2], ['$set' => ['x' => 22]], ['hint' => ['_id' => 1]]);
+$manager->executeBulkWrite(NS, $bulk);
+
+?>
+===DONE===
+<?php exit(0); ?>
+--EXPECTF--
+update included hint: "_id_"
+update included hint: {"_id":1}
+===DONE===

tests/bulk/bulkwrite-update_error-003.phpt

@@ -25,6 +25,10 @@ echo throws(function() use ($bulk) {
 
 echo throws(function() use ($bulk) {
     $bulk->update(['x' => 1], ['$set' => ['y' => 1]], ['arrayFilters' => ['foo' => 'bar']]);
+}, 'MongoDB\Driver\Exception\InvalidArgumentException'), "\n\n";
+
+echo throws(function() use ($bulk) {
+    $bulk->update(['x' => 1], ['$set' => ['y' => 1]], ['hint' => 1]);
 }, 'MongoDB\Driver\Exception\InvalidArgumentException'), "\n";
 
 ?>
@@ -45,4 +49,7 @@ Expected "arrayFilters" option to be array or object, int%S given
 
 OK: Got MongoDB\Driver\Exception\InvalidArgumentException
 "arrayFilters" option has invalid keys for a BSON array
+
+OK: Got MongoDB\Driver\Exception\InvalidArgumentException
+Expected "hint" option to be string, array, or object, int%S given
 ===DONE===

tests/bulk/bulkwrite-update_error-008.phpt

@@ -0,0 +1,26 @@
+--TEST--
+MongoDB\Driver\BulkWrite::update() hint option requires MongoDB 4.2
+--SKIPIF--
+<?php require __DIR__ . "/../utils/basic-skipif.inc"; ?>
+<?php skip_if_not_live(); ?>
+<?php skip_if_server_version('>=', '4.2'); ?>
+--FILE--
+<?php
+require_once __DIR__ . "/../utils/basic.inc";
+
+$manager = new MongoDB\Driver\Manager(URI);
+
+$bulk = new MongoDB\Driver\BulkWrite;
+$bulk->update(['_id' => 1], ['$set' => ['x' => 11]], ['hint' => '_id_']);
+
+echo throws(function() use ($manager, $bulk) {
+    $manager->executeBulkWrite(NS, $bulk);
+}, 'MongoDB\Driver\Exception\BulkWriteException'), "\n";
+
+?>
+===DONE===
+<?php exit(0); ?>
+--EXPECT--
+OK: Got MongoDB\Driver\Exception\BulkWriteException
+Bulk write failed due to previous MongoDB\Driver\Exception\RuntimeException: The selected server does not support hint for update
+===DONE===