PHPC-2206: Implement BSON\Value class (#1412)

* First implementation for MongoDB\BSON\Value

* Add is* methods to MongoDB\BSON\Value

* Extract functions to create BSON instances

* Add getters for all BSON types

* Apply code review feedback

* Rename BSON factory functions

* Return bool in BSON factories

* Clean up int64 compatibility macro includes

* Use macro to throw unexpected BSON type exceptions

* Extract int64 tests for BSON value

* Add error test for BSON value factory

* Implement debug output for BSON value instances

* Remove object comparison handler

* Implement tests for cloning BSON value instances

* Add tests for isInt and getInt

* Ensure stdbool.h is included for compat macros

* Refactor phongo_bson_value_to_zval

The new implementation no longer uses a bson_iter_t for simple values, but instantiates BSON objects directly. Arrays and documents are still passed to php_phongo_bson_to_zval_ex for convenience.

* Refactor phongo_zval_to_bson_value

* Return bson_value_t instances in BSON iterator

* Return bson_value_t instances in Document::get

* Return bson_value_t instances in PackedArray::get

* Return BSON type instances in bson_value_t

This includes a small change to return PHP objects for compatibility in ClientEncryption::decrypt and ClientEncryption::encrypt

* Remove obsolete php_phongo_bson_iter_to_zval function

* Use PHP values in debug output

* Comprehensively test all BSON types

* Implement serialisation of BSON Value instances

* Drop isInt and getInt methods from BSON value class

* Always return int64 instances in Value::getInt64

* Update serialisation and debug info for BSON classes

With the new logic, debug output will always show raw BSON data and PHP data for documents and packed arrays. Serialised data will only contain raw BSON data. This also changes Int64 serialisation to always serialise as Int64 instances, regardless of value or platform.

* Create Int64 instances directly

* Add comment explaining extra property in get_debug_info

* Clarify exception message when initialising Value instance

* Simplify invocations of get_properties_hash with string type

* Handle zval conversion error in get_properties_hash

* Add comment noting phongo_bson_value_to_zval will throw

* Fix zval capitalisation

* Handle bson value conversion error on serialisation

* Document exceptions when converting values to zval

* Clean up unused macros

* Add missing __set_state methods

* Test MongoDB\BSON\Value::__set_state()

* Skip __set_state test on PHP 7.2

* Change docblock to regular comment

* Use new BSON value conversion function when encrypting data

Since the encrypted data will always be a BSON binary object, there is no reason to use the legacy function to avoid receiving a Document or PackedArray instance.

Author: alcaeus

config.m4

@@ -147,6 +147,7 @@ if test "$PHP_MONGODB" != "no"; then
     src/BSON/Unserializable.c \
     src/BSON/UTCDateTime.c \
     src/BSON/UTCDateTimeInterface.c \
+    src/BSON/Value.c \
     src/BSON/functions.c \
     src/MongoDB/BulkWrite.c \
     src/MongoDB/ClientEncryption.c \

config.w32

@@ -121,7 +121,7 @@ if (PHP_MONGODB != "no") {
 
   EXTENSION("mongodb", "php_phongo.c", null, PHP_MONGODB_CFLAGS);
   MONGODB_ADD_SOURCES("/src", "phongo_apm.c phongo_bson.c phongo_bson_encode.c phongo_client.c phongo_compat.c phongo_error.c phongo_execute.c phongo_ini.c phongo_util.c");
-  MONGODB_ADD_SOURCES("/src/BSON", "Binary.c BinaryInterface.c Document.c Iterator.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 PackedArray.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/BSON", "Binary.c BinaryInterface.c Document.c Iterator.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 PackedArray.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 Value.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 ServerApi.c ServerDescription.c Session.c TopologyDescription.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 SDAMSubscriber.c Subscriber.c ServerChangedEvent.c ServerClosedEvent.c ServerHeartbeatFailedEvent.c ServerHeartbeatStartedEvent.c ServerHeartbeatSucceededEvent.c ServerOpeningEvent.c TopologyChangedEvent.c TopologyClosedEvent.c TopologyOpeningEvent.c functions.c");

php_phongo.c

@@ -207,6 +207,7 @@ PHP_MINIT_FUNCTION(mongodb) /* {{{ */
 	php_phongo_timestamp_interface_init_ce(INIT_FUNC_ARGS_PASSTHRU);
 	php_phongo_utcdatetime_interface_init_ce(INIT_FUNC_ARGS_PASSTHRU);
 
+	php_phongo_value_init_ce(INIT_FUNC_ARGS_PASSTHRU);
 	php_phongo_iterator_init_ce(INIT_FUNC_ARGS_PASSTHRU);
 	php_phongo_packedarray_init_ce(INIT_FUNC_ARGS_PASSTHRU);
 	php_phongo_document_init_ce(INIT_FUNC_ARGS_PASSTHRU);

src/BSON/Binary.c

@@ -354,3 +354,17 @@ void php_phongo_binary_init_ce(INIT_FUNC_ARGS)
 	php_phongo_handler_binary.free_obj       = php_phongo_binary_free_object;
 	php_phongo_handler_binary.offset         = XtOffsetOf(php_phongo_binary_t, std);
 }
+
+bool phongo_binary_new(zval* object, const char* data, size_t data_len, bson_subtype_t type)
+{
+	php_phongo_binary_t* intern;
+
+	object_init_ex(object, php_phongo_binary_ce);
+
+	intern           = Z_BINARY_OBJ_P(object);
+	intern->data     = estrndup(data, data_len);
+	intern->data_len = data_len;
+	intern->type     = (uint8_t) type;
+
+	return true;
+}

src/BSON/Binary.h

@@ -19,4 +19,6 @@
 
 #define PHONGO_BINARY_UUID_SIZE 16
 
+bool phongo_binary_new(zval* object, const char* data, size_t data_len, bson_subtype_t type);
+
 #endif /* PHONGO_BSON_BINARY_H */

src/BSON/DBPointer.c

@@ -109,6 +109,24 @@ static PHP_METHOD(MongoDB_BSON_DBPointer, __toString)
 	efree(retval);
 }
 
+static PHP_METHOD(MongoDB_BSON_DBPointer, __set_state)
+{
+	php_phongo_dbpointer_t* intern;
+	HashTable*              props;
+	zval*                   array;
+
+	PHONGO_PARSE_PARAMETERS_START(1, 1)
+	Z_PARAM_ARRAY(array)
+	PHONGO_PARSE_PARAMETERS_END();
+
+	object_init_ex(return_value, php_phongo_dbpointer_ce);
+
+	intern = Z_DBPOINTER_OBJ_P(return_value);
+	props  = Z_ARRVAL_P(array);
+
+	php_phongo_dbpointer_init_from_hash(intern, props);
+}
+
 static PHP_METHOD(MongoDB_BSON_DBPointer, jsonSerialize)
 {
 	php_phongo_dbpointer_t* intern;
@@ -296,3 +314,17 @@ void php_phongo_dbpointer_init_ce(INIT_FUNC_ARGS)
 	php_phongo_handler_dbpointer.free_obj       = php_phongo_dbpointer_free_object;
 	php_phongo_handler_dbpointer.offset         = XtOffsetOf(php_phongo_dbpointer_t, std);
 }
+
+bool phongo_dbpointer_new(zval* object, const char* ref, size_t ref_len, const bson_oid_t* oid)
+{
+	php_phongo_dbpointer_t* intern;
+
+	object_init_ex(object, php_phongo_dbpointer_ce);
+
+	intern          = Z_DBPOINTER_OBJ_P(object);
+	intern->ref     = estrndup(ref, ref_len);
+	intern->ref_len = ref_len;
+	bson_oid_to_string(oid, intern->id);
+
+	return true;
+}

src/BSON/DBPointer.h

@@ -0,0 +1,22 @@
+/*
+ * Copyright 2023-present MongoDB, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef PHONGO_BSON_DBPOINTER_H
+#define PHONGO_BSON_DBPOINTER_H
+
+bool phongo_dbpointer_new(zval* object, const char* ref, size_t ref_len, const bson_oid_t* oid);
+
+#endif /* PHONGO_BSON_DBPOINTER_H */

src/BSON/DBPointer.stub.php

@@ -10,6 +10,8 @@ final class DBPointer implements \JsonSerializable, Type, \Serializable
 {
     final private function __construct() {}
 
+    final public static function __set_state(array $properties): DBPointer {}
+
     final public function __toString(): string {}
 
     final public function serialize(): string {}

src/BSON/DBPointer_arginfo.h

@@ -1,9 +1,13 @@
 /* This is a generated file, edit the .stub.php file instead.
- * Stub hash: 715bc228895c936eb673a93d58750c38fe83f210 */
+ * Stub hash: 2e26331e12fe64ef077d0d2b37433d291cb87943 */
 
 ZEND_BEGIN_ARG_INFO_EX(arginfo_class_MongoDB_BSON_DBPointer___construct, 0, 0, 0)
 ZEND_END_ARG_INFO()
 
+ZEND_BEGIN_ARG_WITH_RETURN_OBJ_INFO_EX(arginfo_class_MongoDB_BSON_DBPointer___set_state, 0, 1, MongoDB\\BSON\\DBPointer, 0)
+	ZEND_ARG_TYPE_INFO(0, properties, IS_ARRAY, 0)
+ZEND_END_ARG_INFO()
+
 ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_class_MongoDB_BSON_DBPointer___toString, 0, 0, IS_STRING, 0)
 ZEND_END_ARG_INFO()
 
@@ -32,6 +36,7 @@ ZEND_END_ARG_INFO()
 
 
 static ZEND_METHOD(MongoDB_BSON_DBPointer, __construct);
+static ZEND_METHOD(MongoDB_BSON_DBPointer, __set_state);
 static ZEND_METHOD(MongoDB_BSON_DBPointer, __toString);
 static ZEND_METHOD(MongoDB_BSON_DBPointer, serialize);
 static ZEND_METHOD(MongoDB_BSON_DBPointer, unserialize);
@@ -47,6 +52,7 @@ static ZEND_METHOD(MongoDB_BSON_DBPointer, jsonSerialize);
 
 static const zend_function_entry class_MongoDB_BSON_DBPointer_methods[] = {
 	ZEND_ME(MongoDB_BSON_DBPointer, __construct, arginfo_class_MongoDB_BSON_DBPointer___construct, ZEND_ACC_PRIVATE|ZEND_ACC_FINAL)
+	ZEND_ME(MongoDB_BSON_DBPointer, __set_state, arginfo_class_MongoDB_BSON_DBPointer___set_state, ZEND_ACC_PUBLIC|ZEND_ACC_STATIC|ZEND_ACC_FINAL)
 	ZEND_ME(MongoDB_BSON_DBPointer, __toString, arginfo_class_MongoDB_BSON_DBPointer___toString, ZEND_ACC_PUBLIC|ZEND_ACC_FINAL)
 	ZEND_ME(MongoDB_BSON_DBPointer, serialize, arginfo_class_MongoDB_BSON_DBPointer_serialize, ZEND_ACC_PUBLIC|ZEND_ACC_FINAL)
 	ZEND_ME(MongoDB_BSON_DBPointer, unserialize, arginfo_class_MongoDB_BSON_DBPointer_unserialize, ZEND_ACC_PUBLIC|ZEND_ACC_FINAL)

src/BSON/Decimal128.c

@@ -289,3 +289,16 @@ void php_phongo_decimal128_init_ce(INIT_FUNC_ARGS)
 	php_phongo_handler_decimal128.free_obj       = php_phongo_decimal128_free_object;
 	php_phongo_handler_decimal128.offset         = XtOffsetOf(php_phongo_decimal128_t, std);
 }
+
+bool phongo_decimal128_new(zval* object, const bson_decimal128_t* decimal)
+{
+	php_phongo_decimal128_t* intern;
+
+	object_init_ex(object, php_phongo_decimal128_ce);
+
+	intern = Z_DECIMAL128_OBJ_P(object);
+	memcpy(&intern->decimal, decimal, sizeof(bson_decimal128_t));
+	intern->initialized = true;
+
+	return true;
+}