PHPC-1709: Add typing information to arginfo (#1337)

* Add missing macros for declaring arguments

* Add macros to define disabled constructor and __wakeup

* Define arginfo via stubs for BSON classes

* Declare tentative return types in interfaces

* Add correct return type for __set_state methods

* Generate class entries for BSON classes

* Declare Binary class constants in stub file

* Use stubs in exception classes

* Add stubs for monitoring classes

* Fix wrong JsonSerializable class in BSON stubs

* Disable declaration-after-statement

This is necessary to let the generated arginfo files compile

* Use stubs for driver classes

* Fix deprecation messages in tests

* Add missing macro

* Fix tests relying on value injection

* Parse parameters in disabled constructor/wakup function

* Add note about arginfo files to contribution docs

* Add GitHub action to check generated arginfo files

* PHPC-2115: Use DateTimeInterface in UTCDateTime constructor signature

* Don't install mongodb extension in GitHub actions workflows

* Change indentation in stub files

* Use individual #if conditions for each stub method

* Make disabled constructor/wakeup methods static

* Fix bulkWrite parameter name

* Use %d to match property count in tests

* Ensure all classes with disabled serialisation declare __wakeup

Author: alcaeus

.github/workflows/arginfo-files.yml

@@ -0,0 +1,44 @@
+name: "Check generated arginfo files"
+
+on:
+  pull_request:
+    branches:
+      - "v*.*"
+      - "master"
+      - "feature/*"
+  push:
+    branches:
+      - "v*.*"
+      - "master"
+      - "feature/*"
+
+jobs:
+  check-arginfo:
+    name: "Check generated arginfo files"
+    runs-on: "ubuntu-20.04"
+
+    strategy:
+      matrix:
+        php-version:
+          - "8.2"
+
+    steps:
+      - name: "Checkout"
+        uses: "actions/checkout@v2"
+        with:
+          submodules: true
+
+      - name: "Install PHP"
+        uses: "shivammathur/setup-php@v2"
+        with:
+          php-version: "${{ matrix.php-version }}"
+          tools: "phpize"
+
+      - name: "Run phpize"
+        run: phpize
+
+      - name: "Rebuild arginfo files from stubs"
+        run: "php ./build/gen_stub.php"
+
+      - name: "Check arginfo file diff"
+        run: git add . -N && git diff --exit-code

.github/workflows/clang-format.yml

@@ -32,7 +32,6 @@ jobs:
         uses: "shivammathur/setup-php@v2"
         with:
           php-version: "${{ matrix.php-version }}"
-          extensions: ":mongodb"
           tools: "phpize"
 
       - name: "Configure driver"

.github/workflows/tests.yml

@@ -65,7 +65,6 @@ jobs:
         uses: "shivammathur/setup-php@v2"
         with:
           php-version: "${{ matrix.php-version }}"
-          extensions: ":mongodb"
           tools: "phpize"
 
       - name: "Configure driver"

.gitignore

@@ -41,6 +41,7 @@ mongocryptd.pid
 *.out
 *.mem
 *.php
+!*.stub.php
 tests/*/*.sh
 tests/*/*/*/*.sh
 tests/*/*/*/*/*.sh

CONTRIBUTING.md

@@ -21,6 +21,13 @@ phpize > /dev/null && \
 make clean > /dev/null && make all > /dev/null && make install
 ```
 
+## Generating arginfo from stub files
+
+Arginfo structures are generated from stub files using the `gen_stub.php`
+file. Note that this requires `phpize` to be run for PHP 8.2 to make use
+of all features. After changing a stub file, run `./build/gen_stub.php`
+to regenerate the corresponding arginfo files and commit the results.
+
 ## Testing
 
 The extension's test use the PHPT format from PHP internals. This format is

config.m4

@@ -66,7 +66,6 @@ if test "$PHP_MONGODB" != "no"; then
     AX_CHECK_COMPILE_FLAG(-Wenum-compare,                   _MAINTAINER_CFLAGS="$_MAINTAINER_CFLAGS -Wenum-compare"                 ,, -Werror)
     AX_CHECK_COMPILE_FLAG(-Wempty-body,                     _MAINTAINER_CFLAGS="$_MAINTAINER_CFLAGS -Wempty-body"                   ,, -Werror)
     AX_CHECK_COMPILE_FLAG(-Wparentheses,                    _MAINTAINER_CFLAGS="$_MAINTAINER_CFLAGS -Wparentheses"                  ,, -Werror)
-    AX_CHECK_COMPILE_FLAG(-Wdeclaration-after-statement,    _MAINTAINER_CFLAGS="$_MAINTAINER_CFLAGS -Wdeclaration-after-statement"  ,, -Werror)
     AX_CHECK_COMPILE_FLAG(-Wmaybe-uninitialized,            _MAINTAINER_CFLAGS="$_MAINTAINER_CFLAGS -Wmaybe-uninitialized"          ,, -Werror)
     AX_CHECK_COMPILE_FLAG(-Wimplicit-fallthrough,           _MAINTAINER_CFLAGS="$_MAINTAINER_CFLAGS -Wimplicit-fallthrough"         ,, -Werror)
     AX_CHECK_COMPILE_FLAG(-Werror,                          _MAINTAINER_CFLAGS="$_MAINTAINER_CFLAGS -Werror"                        ,, -Werror)

php_phongo.c

@@ -44,7 +44,6 @@ ZEND_TSRMLS_CACHE_DEFINE();
 static int32_t phongo_num_threads = 0;
 
 /* Declare zend_class_entry dependencies, which are initialized in MINIT */
-zend_class_entry* php_phongo_date_immutable_ce;
 zend_class_entry* php_phongo_json_serializable_ce;
 
 /* {{{ phongo_std_object_handlers */
@@ -181,17 +180,12 @@ PHP_MINIT_FUNCTION(mongodb) /* {{{ */
 	phongo_std_object_handlers.get_gc = php_phongo_std_get_gc;
 
 	/* Initialize zend_class_entry dependencies.
-	 *
-	 * Although DateTimeImmutable was introduced in PHP 5.5.0,
-	 * php_date_get_immutable_ce() is not available in PHP versions before
-	 * 5.5.24 and 5.6.8.
 	 *
 	 * Although JsonSerializable was introduced in PHP 5.4.0,
 	 * php_json_serializable_ce is not exported in PHP versions before 5.4.26
 	 * and 5.5.10. For later PHP versions, looking up the class manually also
 	 * helps with distros that disable LTDL_LAZY for dlopen() (e.g. Fedora).
 	 */
-	php_phongo_date_immutable_ce    = php_phongo_fetch_internal_class(ZEND_STRL("datetimeimmutable"));
 	php_phongo_json_serializable_ce = php_phongo_fetch_internal_class(ZEND_STRL("jsonserializable"));
 
 	if (php_phongo_json_serializable_ce == NULL) {

php_phongo.h

@@ -109,6 +109,20 @@ zend_object_handlers* phongo_get_std_object_handlers(void);
 		(intern)->created_by_pid = (int) getpid(); \
 	} while (0)
 
+#define PHONGO_DISABLED_CONSTRUCTOR(classname)                                         \
+	static PHP_METHOD(classname, __construct)                                          \
+	{                                                                                  \
+		PHONGO_PARSE_PARAMETERS_NONE();                                                \
+		phongo_throw_exception(PHONGO_ERROR_RUNTIME, "Accessing private constructor"); \
+	}
+
+#define PHONGO_DISABLED_WAKEUP(classname)                                                             \
+	static PHP_METHOD(classname, __wakeup)                                                            \
+	{                                                                                                 \
+		PHONGO_PARSE_PARAMETERS_NONE();                                                               \
+		phongo_throw_exception(PHONGO_ERROR_RUNTIME, "MongoDB\\Driver objects cannot be serialized"); \
+	}
+
 /* Shared function entries for disabling constructors and unserialize() */
 PHP_FUNCTION(MongoDB_disabled___construct);
 PHP_FUNCTION(MongoDB_disabled___wakeup);

scripts/clang-format.sh

@@ -3,12 +3,12 @@
 CLANG_ARGS="-Werror"
 
 if test x"$1" = xchanged; then
-  FILES1=`git ls-files | grep -v "src/contrib" | grep '\.[ch]$'`
-  FILES2=`git ls-files --others --exclude-standard | grep -v "src/contrib" | grep '\.[ch]$'`
+  FILES1=`git ls-files | grep -v "src/contrib" | grep -v "_arginfo.h" | grep '\.[ch]$'`
+  FILES2=`git ls-files --others --exclude-standard | grep -v "src/contrib" | grep -v "_arginfo.h" | grep '\.[ch]$'`
   FILES="$FILES1 $FILES2"
 else
-	FILES1=`git ls-files | grep -v "src/contrib" | grep '\.[ch]$'`
-	FILES2=`git ls-files --others --exclude-standard | grep -v "src/contrib" | grep '\.[ch]$'`
+	FILES1=`git ls-files | grep -v "src/contrib" | grep -v "_arginfo.h" | grep '\.[ch]$'`
+	FILES2=`git ls-files --others --exclude-standard | grep -v "src/contrib" | grep -v "_arginfo.h" | grep '\.[ch]$'`
 	FILES="$FILES1 $FILES2"
 fi
 

src/BSON/Binary.c

@@ -22,6 +22,7 @@
 
 #include "php_phongo.h"
 #include "phongo_error.h"
+#include "Binary_arginfo.h"
 
 #define PHONGO_BINARY_UUID_SIZE 16
 
@@ -92,7 +93,7 @@ static HashTable* php_phongo_binary_get_properties_hash(phongo_compat_object_han
 
 /* {{{ proto void MongoDB\BSON\Binary::__construct(string $data, int $type)
    Construct a new BSON binary type */
-static PHP_METHOD(Binary, __construct)
+static PHP_METHOD(MongoDB_BSON_Binary, __construct)
 {
 	php_phongo_binary_t* intern;
 	char*                data;
@@ -111,7 +112,7 @@ static PHP_METHOD(Binary, __construct)
 
 /* {{{ proto MongoDB\BSON\Binary MongoDB\BSON\Binary::__set_state(array $properties)
 */
-static PHP_METHOD(Binary, __set_state)
+static PHP_METHOD(MongoDB_BSON_Binary, __set_state)
 {
 	php_phongo_binary_t* intern;
 	HashTable*           props;
@@ -131,7 +132,7 @@ static PHP_METHOD(Binary, __set_state)
 
 /* {{{ proto string MongoDB\BSON\Binary::__toString()
    Return the Binary's data string. */
-static PHP_METHOD(Binary, __toString)
+static PHP_METHOD(MongoDB_BSON_Binary, __toString)
 {
 	php_phongo_binary_t* intern;
 
@@ -144,7 +145,7 @@ static PHP_METHOD(Binary, __toString)
 
 /* {{{ proto string MongoDB\BSON\Binary::getData()
 */
-static PHP_METHOD(Binary, getData)
+static PHP_METHOD(MongoDB_BSON_Binary, getData)
 {
 	php_phongo_binary_t* intern;
 
@@ -157,7 +158,7 @@ static PHP_METHOD(Binary, getData)
 
 /* {{{ proto integer MongoDB\BSON\Binary::getType()
 */
-static PHP_METHOD(Binary, getType)
+static PHP_METHOD(MongoDB_BSON_Binary, getType)
 {
 	php_phongo_binary_t* intern;
 
@@ -170,7 +171,7 @@ static PHP_METHOD(Binary, getType)
 
 /* {{{ proto array MongoDB\BSON\Binary::jsonSerialize()
 */
-static PHP_METHOD(Binary, jsonSerialize)
+static PHP_METHOD(MongoDB_BSON_Binary, jsonSerialize)
 {
 	php_phongo_binary_t* intern;
 	char                 type[3];
@@ -194,7 +195,7 @@ static PHP_METHOD(Binary, jsonSerialize)
 
 /* {{{ proto string MongoDB\BSON\Binary::serialize()
 */
-static PHP_METHOD(Binary, serialize)
+static PHP_METHOD(MongoDB_BSON_Binary, serialize)
 {
 	php_phongo_binary_t* intern;
 	zval                 retval;
@@ -222,7 +223,7 @@ static PHP_METHOD(Binary, serialize)
 
 /* {{{ proto void MongoDB\BSON\Binary::unserialize(string $serialized)
 */
-static PHP_METHOD(Binary, unserialize)
+static PHP_METHOD(MongoDB_BSON_Binary, unserialize)
 {
 	php_phongo_binary_t*   intern;
 	char*                  serialized;
@@ -252,7 +253,7 @@ static PHP_METHOD(Binary, unserialize)
 
 /* {{{ proto array MongoDB\Driver\Binary::__serialize()
 */
-static PHP_METHOD(Binary, __serialize)
+static PHP_METHOD(MongoDB_BSON_Binary, __serialize)
 {
 	PHONGO_PARSE_PARAMETERS_NONE();
 
@@ -261,7 +262,7 @@ static PHP_METHOD(Binary, __serialize)
 
 /* {{{ proto void MongoDB\Driver\Binary::__unserialize(array $data)
 */
-static PHP_METHOD(Binary, __unserialize)
+static PHP_METHOD(MongoDB_BSON_Binary, __unserialize)
 {
 	zval* data;
 
@@ -272,50 +273,6 @@ static PHP_METHOD(Binary, __unserialize)
 	php_phongo_binary_init_from_hash(Z_BINARY_OBJ_P(getThis()), Z_ARRVAL_P(data));
 } /* }}} */
 
-/* {{{ MongoDB\BSON\Binary function entries */
-/* clang-format off */
-ZEND_BEGIN_ARG_INFO_EX(ai_Binary___construct, 0, 0, 2)
-	ZEND_ARG_INFO(0, data)
-	ZEND_ARG_INFO(0, type)
-ZEND_END_ARG_INFO()
-
-ZEND_BEGIN_ARG_INFO_EX(ai_Binary___set_state, 0, 0, 1)
-	ZEND_ARG_ARRAY_INFO(0, properties, 0)
-ZEND_END_ARG_INFO()
-
-ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(ai_Binary___toString, 0, 0, IS_STRING, 0)
-ZEND_END_ARG_INFO()
-
-ZEND_BEGIN_ARG_INFO_EX(ai_Binary___unserialize, 0, 0, 1)
-	ZEND_ARG_ARRAY_INFO(0, data, 0)
-ZEND_END_ARG_INFO()
-
-ZEND_BEGIN_ARG_WITH_TENTATIVE_RETURN_TYPE_INFO_EX(ai_Binary_jsonSerialize, 0, 0, IS_ARRAY, 0)
-ZEND_END_ARG_INFO()
-
-ZEND_BEGIN_ARG_INFO_EX(ai_Binary_unserialize, 0, 0, 1)
-	ZEND_ARG_INFO(0, serialized)
-ZEND_END_ARG_INFO()
-
-ZEND_BEGIN_ARG_INFO_EX(ai_Binary_void, 0, 0, 0)
-ZEND_END_ARG_INFO()
-
-static zend_function_entry php_phongo_binary_me[] = {
-	PHP_ME(Binary, __construct, ai_Binary___construct, ZEND_ACC_PUBLIC | ZEND_ACC_FINAL)
-	PHP_ME(Binary, __serialize, ai_Binary_void, ZEND_ACC_PUBLIC | ZEND_ACC_FINAL)
-	PHP_ME(Binary, __set_state, ai_Binary___set_state, ZEND_ACC_PUBLIC | ZEND_ACC_STATIC)
-	PHP_ME(Binary, __toString, ai_Binary___toString, ZEND_ACC_PUBLIC | ZEND_ACC_FINAL)
-	PHP_ME(Binary, __unserialize, ai_Binary___unserialize, ZEND_ACC_PUBLIC | ZEND_ACC_FINAL)
-	PHP_ME(Binary, jsonSerialize, ai_Binary_jsonSerialize, ZEND_ACC_PUBLIC | ZEND_ACC_FINAL)
-	PHP_ME(Binary, serialize, ai_Binary_void, ZEND_ACC_PUBLIC | ZEND_ACC_FINAL)
-	PHP_ME(Binary, unserialize, ai_Binary_unserialize, ZEND_ACC_PUBLIC | ZEND_ACC_FINAL)
-	PHP_ME(Binary, getData, ai_Binary_void, ZEND_ACC_PUBLIC | ZEND_ACC_FINAL)
-	PHP_ME(Binary, getType, ai_Binary_void, ZEND_ACC_PUBLIC | ZEND_ACC_FINAL)
-	PHP_FE_END
-};
-/* clang-format on */
-/* }}} */
-
 /* {{{ MongoDB\BSON\Binary object handlers */
 static zend_object_handlers php_phongo_handler_binary;
 
@@ -400,17 +357,8 @@ static HashTable* php_phongo_binary_get_properties(phongo_compat_object_handler_
 
 void php_phongo_binary_init_ce(INIT_FUNC_ARGS) /* {{{ */
 {
-	zend_class_entry ce;
-
-	INIT_NS_CLASS_ENTRY(ce, "MongoDB\\BSON", "Binary", php_phongo_binary_me);
-	php_phongo_binary_ce                = zend_register_internal_class(&ce);
+	php_phongo_binary_ce                = register_class_MongoDB_BSON_Binary(php_phongo_binary_interface_ce, php_phongo_json_serializable_ce, php_phongo_type_ce, zend_ce_serializable);
 	php_phongo_binary_ce->create_object = php_phongo_binary_create_object;
-	PHONGO_CE_FINAL(php_phongo_binary_ce);
-
-	zend_class_implements(php_phongo_binary_ce, 1, php_phongo_binary_interface_ce);
-	zend_class_implements(php_phongo_binary_ce, 1, php_phongo_json_serializable_ce);
-	zend_class_implements(php_phongo_binary_ce, 1, php_phongo_type_ce);
-	zend_class_implements(php_phongo_binary_ce, 1, zend_ce_serializable);
 
 #if PHP_VERSION_ID >= 80000
 	zend_class_implements(php_phongo_binary_ce, 1, zend_ce_stringable);
@@ -423,14 +371,4 @@ void php_phongo_binary_init_ce(INIT_FUNC_ARGS) /* {{{ */
 	php_phongo_handler_binary.get_properties = php_phongo_binary_get_properties;
 	php_phongo_handler_binary.free_obj       = php_phongo_binary_free_object;
 	php_phongo_handler_binary.offset         = XtOffsetOf(php_phongo_binary_t, std);
-
-	zend_declare_class_constant_long(php_phongo_binary_ce, ZEND_STRL("TYPE_GENERIC"), BSON_SUBTYPE_BINARY);
-	zend_declare_class_constant_long(php_phongo_binary_ce, ZEND_STRL("TYPE_FUNCTION"), BSON_SUBTYPE_FUNCTION);
-	zend_declare_class_constant_long(php_phongo_binary_ce, ZEND_STRL("TYPE_OLD_BINARY"), BSON_SUBTYPE_BINARY_DEPRECATED);
-	zend_declare_class_constant_long(php_phongo_binary_ce, ZEND_STRL("TYPE_OLD_UUID"), BSON_SUBTYPE_UUID_DEPRECATED);
-	zend_declare_class_constant_long(php_phongo_binary_ce, ZEND_STRL("TYPE_UUID"), BSON_SUBTYPE_UUID);
-	zend_declare_class_constant_long(php_phongo_binary_ce, ZEND_STRL("TYPE_MD5"), BSON_SUBTYPE_MD5);
-	zend_declare_class_constant_long(php_phongo_binary_ce, ZEND_STRL("TYPE_ENCRYPTED"), BSON_SUBTYPE_ENCRYPTED);
-	zend_declare_class_constant_long(php_phongo_binary_ce, ZEND_STRL("TYPE_COLUMN"), BSON_SUBTYPE_COLUMN);
-	zend_declare_class_constant_long(php_phongo_binary_ce, ZEND_STRL("TYPE_USER_DEFINED"), BSON_SUBTYPE_USER);
 } /* }}} */