PHPC-1716 Allow configuring server API version in manager (#1204)

* Introduce MongoDB\Driver\ServerApi

* Accept serverApi driver option

* Introduce create_test_manager factory to create manager

A centralised entry point is required to inject the API_VERSION env variable later.

* Add build variant to test with requireApiVersion=true

* Fix wrong configuration for auth variable

This changed when migrating from our own scripts to drivers-evergreen-tools and was not updated properly, causing all tests to run with auth disabled.

* Declare ZEND_PARSE_PARAMETERS_NONE macro

This macro is missing on PHP < 7.3

* Remove duplicated API param storage

* Add missing semicolons

* Add ZEND_PARSE_PARAMETERS_NON_EX macro

* Extract error handling functionality to separate macros

* Throw if internal mongoc_server_api_t is already initialised

* Use imported namespaces in tools file

* Fix type info for reflection

* Use American English spelling

* Only use typed serialize signature on PHP 8+

* Update PHONGO_PARSE_PARAMETERS_NONE macro for PHP < 7.3

* Remove usage of ZEND_STRL within zend_hash_str_add

This causes compile failures on PHP < 7.3 that I have yet to understand.

* Fix errors in new PHONGO_PARSE_PARAMETERS macros

Author: alcaeus

.evergreen/config.yml

@@ -386,7 +386,7 @@ functions:
         working_dir: "src"
         script: |
           ${PREPARE_SHELL}
-          TESTS=${TESTS} SSL=${SSL} MONGODB_URI="${MONGODB_URI}${APPEND_URI}" sh ${PROJECT_DIRECTORY}/.evergreen/run-tests.sh
+          API_VERSION=${API_VERSION} TESTS=${TESTS} SSL=${SSL} MONGODB_URI="${MONGODB_URI}${APPEND_URI}" sh ${PROJECT_DIRECTORY}/.evergreen/run-tests.sh
 
   "cleanup":
     - command: shell.exec
@@ -585,6 +585,19 @@ tasks:
           vars:
             TESTS: "tests/atlas.phpt"
 
+    - name: "test-requireApiVersion"
+      tags: ["versioned_api"]
+      commands:
+        - func: "compile driver"
+        - func: "bootstrap mongo-orchestration"
+          vars:
+            TOPOLOGY: "server"
+            AUTH: "auth"
+            REQUIRE_API_VERSION: "yes"
+        - func: "run tests"
+          vars:
+            API_VERSION: "1"
+
     - name: "ocsp-test_1-rsa-delegate"
       tags: ["ocsp"]
       commands:
@@ -1180,3 +1193,9 @@ buildvariants:
   display_name: "OCSP tests - ${versions}"
   tasks:
     - name: ".ocsp"
+
+- matrix_name: "test-requireApiVersion"
+  matrix_spec: { "os-php7": "debian92-test", "php-versions": "7.3", "versions": "latest" }
+  display_name: "Versioned API - ${versions}"
+  tasks:
+    - name: "test-requireApiVersion"

.evergreen/run-tests.sh

@@ -11,6 +11,7 @@ AUTH=${AUTH:-noauth}
 SSL=${SSL:-nossl}
 MONGODB_URI=${MONGODB_URI:-}
 TESTS=${TESTS:-}
+API_VERSION=${API_VERSION:-}
 
 OS=$(uname -s | tr '[:upper:]' '[:lower:]')
 [ -z "$MARCH" ] && MARCH=$(uname -m | tr '[:upper:]' '[:lower:]')
@@ -26,7 +27,7 @@ echo "Running $AUTH tests, connecting to $MONGODB_URI"
 # Run the tests, and store the results in a junit result file
 case "$OS" in
    *)
-      TEST_PHP_JUNIT="${PROJECT_DIRECTORY}/test-results.xml" TEST_PHP_ARGS="-q -x --show-diff -g FAIL,XFAIL,BORK,WARN,LEAK,SKIP" make test TESTS=$TESTS
+      API_VERSION="${API_VERSION}" TEST_PHP_JUNIT="${PROJECT_DIRECTORY}/test-results.xml" TEST_PHP_ARGS="-q -x --show-diff -g FAIL,XFAIL,BORK,WARN,LEAK,SKIP" make test TESTS=$TESTS
       ;;
 esac
 

config.m4

@@ -143,6 +143,7 @@ if test "$PHP_MONGODB" != "no"; then
     src/MongoDB/ReadConcern.c \
     src/MongoDB/ReadPreference.c \
     src/MongoDB/Server.c \
+    src/MongoDB/ServerApi.c \
     src/MongoDB/Session.c \
     src/MongoDB/WriteConcern.c \
     src/MongoDB/WriteConcernError.c \

config.w32

@@ -120,7 +120,7 @@ if (PHP_MONGODB != "no") {
   EXTENSION("mongodb", "php_phongo.c phongo_compat.c", null, PHP_MONGODB_CFLAGS);
   MONGODB_ADD_SOURCES("/src", "bson.c bson-encode.c");
   MONGODB_ADD_SOURCES("/src/BSON", "Binary.c BinaryInterface.c DBPointer.c Decimal128.c Decimal128Interface.c Int64.c Javascript.c JavascriptInterface.c MaxKey.c MaxKeyInterface.c MinKey.c MinKeyInterface.c ObjectId.c ObjectIdInterface.c Persistable.c Regex.c RegexInterface.c Serializable.c Symbol.c Timestamp.c TimestampInterface.c Type.c Undefined.c Unserializable.c UTCDateTime.c UTCDateTimeInterface.c functions.c");
-  MONGODB_ADD_SOURCES("/src/MongoDB", "BulkWrite.c ClientEncryption.c Command.c Cursor.c CursorId.c CursorInterface.c Manager.c Query.c ReadConcern.c ReadPreference.c Server.c Session.c WriteConcern.c WriteConcernError.c WriteError.c WriteResult.c");
+  MONGODB_ADD_SOURCES("/src/MongoDB", "BulkWrite.c ClientEncryption.c Command.c Cursor.c CursorId.c CursorInterface.c Manager.c Query.c ReadConcern.c ReadPreference.c Server.c ServerApi.c Session.c WriteConcern.c WriteConcernError.c WriteError.c WriteResult.c");
   MONGODB_ADD_SOURCES("/src/MongoDB/Exception", "AuthenticationException.c BulkWriteException.c CommandException.c ConnectionException.c ConnectionTimeoutException.c EncryptionException.c Exception.c ExecutionTimeoutException.c InvalidArgumentException.c LogicException.c RuntimeException.c ServerException.c SSLConnectionException.c UnexpectedValueException.c WriteException.c");
   MONGODB_ADD_SOURCES("/src/MongoDB/Monitoring", "CommandFailedEvent.c CommandStartedEvent.c CommandSubscriber.c CommandSucceededEvent.c Subscriber.c functions.c");
   MONGODB_ADD_SOURCES("/src/libmongoc/src/common", PHP_MONGODB_COMMON_SOURCES);

phongo_compat.h

@@ -169,6 +169,55 @@
 	} while (0)
 #endif /* PHP_VERSION_ID < 70300 */
 
+/* Compatibility macros to override error handling logic */
+#define PHONGO_PARSE_PARAMETERS_START(min_num_args, max_num_args)               \
+	do {                                                                        \
+		zend_error_handling error_handling;                                     \
+		zend_replace_error_handling(                                            \
+			EH_THROW,                                                           \
+			phongo_exception_from_phongo_domain(PHONGO_ERROR_INVALID_ARGUMENT), \
+			&error_handling);                                                   \
+	ZEND_PARSE_PARAMETERS_START(min_num_args, max_num_args)
+
+#define PHONGO_PARSE_PARAMETERS_END()                 \
+	ZEND_PARSE_PARAMETERS_END_EX(                     \
+		zend_restore_error_handling(&error_handling); \
+		return );                                     \
+	zend_restore_error_handling(&error_handling);     \
+	}                                                 \
+	while (0)
+
+#ifndef ZEND_PARSE_PARAMETERS_NONE
+#define PHONGO_PARSE_PARAMETERS_NONE()                                          \
+	do {                                                                        \
+		zend_error_handling error_handling;                                     \
+		zend_replace_error_handling(                                            \
+			EH_THROW,                                                           \
+			phongo_exception_from_phongo_domain(PHONGO_ERROR_INVALID_ARGUMENT), \
+			&error_handling);                                                   \
+		if (zend_parse_parameters_none() == FAILURE) {                          \
+			zend_restore_error_handling(&error_handling);                       \
+			return;                                                             \
+		}                                                                       \
+		zend_restore_error_handling(&error_handling);                           \
+	} while (0)
+#else
+#define PHONGO_PARSE_PARAMETERS_NONE()                                          \
+	do {                                                                        \
+		zend_error_handling error_handling;                                     \
+		zend_replace_error_handling(                                            \
+			EH_THROW,                                                           \
+			phongo_exception_from_phongo_domain(PHONGO_ERROR_INVALID_ARGUMENT), \
+			&error_handling);                                                   \
+		if (UNEXPECTED(ZEND_NUM_ARGS() != 0)) {                                 \
+			zend_wrong_parameters_none_error();                                 \
+			zend_restore_error_handling(&error_handling);                       \
+			return;                                                             \
+		}                                                                       \
+		zend_restore_error_handling(&error_handling);                           \
+	} while (0)
+#endif
+
 void      phongo_add_exception_prop(const char* prop, int prop_len, zval* value);
 zend_bool php_phongo_zend_hash_apply_protection_begin(HashTable* ht);
 zend_bool php_phongo_zend_hash_apply_protection_end(HashTable* ht);

php_phongo.c

@@ -2833,6 +2833,33 @@ static mongoc_client_t* php_phongo_find_persistent_client(const char* hash, size
 	return NULL;
 }
 
+static bool phongo_manager_set_serverapi_opts(php_phongo_manager_t* manager, zval* driverOptions) /* {{{ */
+{
+	zval*                   zServerApi;
+	php_phongo_serverapi_t* server_api;
+	bson_error_t            error = { 0 };
+
+	if (!driverOptions || !php_array_existsc(driverOptions, "serverApi")) {
+		return true;
+	}
+
+	zServerApi = php_array_fetch(driverOptions, "serverApi");
+
+	if (Z_TYPE_P(zServerApi) != IS_OBJECT || !instanceof_function(Z_OBJCE_P(zServerApi), php_phongo_serverapi_ce)) {
+		phongo_throw_exception(PHONGO_ERROR_INVALID_ARGUMENT, "Expected \"serverApi\" driver option to be %s, %s given", ZSTR_VAL(php_phongo_serverapi_ce->name), PHONGO_ZVAL_CLASS_OR_TYPE_NAME_P(zServerApi));
+		return false;
+	}
+
+	server_api = Z_SERVERAPI_OBJ_P(zServerApi);
+
+	if (!mongoc_client_set_server_api(manager->client, server_api->server_api, &error)) {
+		phongo_throw_exception_from_bson_error_t(&error);
+		return false;
+	}
+
+	return true;
+} /* }}} */
+
 #ifdef MONGOC_ENABLE_CLIENT_SIDE_ENCRYPTION
 static bool phongo_manager_set_auto_encryption_opts(php_phongo_manager_t* manager, zval* driverOptions) /* {{{ */
 {
@@ -3453,6 +3480,11 @@ void phongo_manager_init(php_phongo_manager_t* manager, const char* uri_string,
 		goto cleanup;
 	}
 
+	if (!phongo_manager_set_serverapi_opts(manager, driverOptions)) {
+		/* Exception should already have been thrown */
+		goto cleanup;
+	}
+
 	php_phongo_set_monitoring_callbacks(manager->client);
 
 	MONGOC_DEBUG("Created client with hash: %s", manager->client_hash);
@@ -3893,6 +3925,7 @@ PHP_MINIT_FUNCTION(mongodb)
 	php_phongo_readconcern_init_ce(INIT_FUNC_ARGS_PASSTHRU);
 	php_phongo_readpreference_init_ce(INIT_FUNC_ARGS_PASSTHRU);
 	php_phongo_server_init_ce(INIT_FUNC_ARGS_PASSTHRU);
+	php_phongo_serverapi_init_ce(INIT_FUNC_ARGS_PASSTHRU);
 	php_phongo_session_init_ce(INIT_FUNC_ARGS_PASSTHRU);
 	php_phongo_writeconcern_init_ce(INIT_FUNC_ARGS_PASSTHRU);
 	php_phongo_writeconcernerror_init_ce(INIT_FUNC_ARGS_PASSTHRU);

php_phongo_classes.h

@@ -63,6 +63,10 @@ static inline php_phongo_server_t* php_server_fetch_object(zend_object* obj)
 {
 	return (php_phongo_server_t*) ((char*) obj - XtOffsetOf(php_phongo_server_t, std));
 }
+static inline php_phongo_serverapi_t* php_serverapi_fetch_object(zend_object* obj)
+{
+	return (php_phongo_serverapi_t*) ((char*) obj - XtOffsetOf(php_phongo_serverapi_t, std));
+}
 static inline php_phongo_session_t* php_session_fetch_object(zend_object* obj)
 {
 	return (php_phongo_session_t*) ((char*) obj - XtOffsetOf(php_phongo_session_t, std));
@@ -157,6 +161,7 @@ static inline php_phongo_commandsucceededevent_t* php_commandsucceededevent_fetc
 #define Z_READCONCERN_OBJ_P(zv) (php_readconcern_fetch_object(Z_OBJ_P(zv)))
 #define Z_READPREFERENCE_OBJ_P(zv) (php_readpreference_fetch_object(Z_OBJ_P(zv)))
 #define Z_SERVER_OBJ_P(zv) (php_server_fetch_object(Z_OBJ_P(zv)))
+#define Z_SERVERAPI_OBJ_P(zv) (php_serverapi_fetch_object(Z_OBJ_P(zv)))
 #define Z_SESSION_OBJ_P(zv) (php_session_fetch_object(Z_OBJ_P(zv)))
 #define Z_BULKWRITE_OBJ_P(zv) (php_bulkwrite_fetch_object(Z_OBJ_P(zv)))
 #define Z_WRITECONCERN_OBJ_P(zv) (php_writeconcern_fetch_object(Z_OBJ_P(zv)))
@@ -189,6 +194,7 @@ static inline php_phongo_commandsucceededevent_t* php_commandsucceededevent_fetc
 #define Z_OBJ_READCONCERN(zo) (php_readconcern_fetch_object(zo))
 #define Z_OBJ_READPREFERENCE(zo) (php_readpreference_fetch_object(zo))
 #define Z_OBJ_SERVER(zo) (php_server_fetch_object(zo))
+#define Z_OBJ_SERVERAPI(zo) (php_serverapi_fetch_object(zo))
 #define Z_OBJ_SESSION(zo) (php_session_fetch_object(zo))
 #define Z_OBJ_BULKWRITE(zo) (php_bulkwrite_fetch_object(zo))
 #define Z_OBJ_WRITECONCERN(zo) (php_writeconcern_fetch_object(zo))
@@ -221,6 +227,7 @@ extern zend_class_entry* php_phongo_query_ce;
 extern zend_class_entry* php_phongo_readconcern_ce;
 extern zend_class_entry* php_phongo_readpreference_ce;
 extern zend_class_entry* php_phongo_server_ce;
+extern zend_class_entry* php_phongo_serverapi_ce;
 extern zend_class_entry* php_phongo_session_ce;
 extern zend_class_entry* php_phongo_bulkwrite_ce;
 extern zend_class_entry* php_phongo_writeconcern_ce;
@@ -318,6 +325,7 @@ extern void php_phongo_query_init_ce(INIT_FUNC_ARGS);
 extern void php_phongo_readconcern_init_ce(INIT_FUNC_ARGS);
 extern void php_phongo_readpreference_init_ce(INIT_FUNC_ARGS);
 extern void php_phongo_server_init_ce(INIT_FUNC_ARGS);
+extern void php_phongo_serverapi_init_ce(INIT_FUNC_ARGS);
 extern void php_phongo_session_init_ce(INIT_FUNC_ARGS);
 extern void php_phongo_writeconcern_init_ce(INIT_FUNC_ARGS);
 extern void php_phongo_writeconcernerror_init_ce(INIT_FUNC_ARGS);

php_phongo_structs.h

@@ -105,6 +105,12 @@ typedef struct {
 	zend_object std;
 } php_phongo_server_t;
 
+typedef struct {
+	mongoc_server_api_t* server_api;
+	HashTable*           properties;
+	zend_object          std;
+} php_phongo_serverapi_t;
+
 typedef struct {
 	mongoc_client_session_t* client_session;
 	zval                     manager;

scripts/convert-bson-corpus-tests.php

@@ -1,6 +1,6 @@
 <?php
 
-require_once __DIR__ . '/../tests/utils/tools.php';
+require_once __DIR__ . '/../tests/utils/basic.inc';
 
 $expectedFailures = [
     'Int64 type: -1' => 'PHP encodes integers as 32-bit if range allows',
@@ -288,7 +288,7 @@ function renderPhpt(array $params, array $expectedFailures, array $for64bitOnly)
 --FILE--
 <?php
 
-require_once __DIR__ . '/../utils/tools.php';
+require_once __DIR__ . '/../utils/basic.inc';
 
 %CODE%