Generate C enums from internal enums, introduce Z_PARAM_ENUM()

[arnaud-lb]

Update gen_stubs.php to generate C enums from internal enums. Enum values can be compared to the result of zend_enum_fetch_case_id(zend_object*).

The generated enums are added to separate files named {$extensionName}_decl.h (one for each extension declaring some enums), so that it's possible to include these from anywhere. _arginfo.h files would generate warnings if we tried to include them in a compilation unit that doesn't call the register_{$class} functions, for instance.

Introduce Z_PARAM_ENUM() (similarly to #20898).

cc @TimWolla

UPGRADING.INTERNALS:

diff --git a/UPGRADING.INTERNALS b/UPGRADING.INTERNALS
index f23a610b849..0f591575a97 100644
--- a/UPGRADING.INTERNALS
+++ b/UPGRADING.INTERNALS
@@ -56,11 +56,20 @@ PHP 8.6 INTERNALS UPGRADE NOTES
     node.
   . The zend_exception_save() and zend_exception_restore() functions were
     removed.
+  . The php_math_round_mode_from_enum() function now takes a
+    zend_enum_RoundingMode parameter.
+  . Added Z_PARAM_ENUM().
+  . Added zend_enum_fetch_case_id().
 
 ========================
 2. Build system changes
 ========================
 
+  . build/gen_stub.php may now generate a _decl.h file in addition to
+    the _arginfo.h file, if the stub declares enums and is annotated with
+    @generate-c-enums. For each enum, the file will contain a C enum. Enum values
+    can be compared to the result of zend_enum_fetch_case_id(zend_object*).
+
 ========================
 3. Module changes
 ========================

[TimWolla]

Some first comments. Will take another look once rebased after the merge of #20915.

[TimWolla]

This assert is redundant with the one in zend_enum_obj_from_obj(). I also don't see how it could help with codegen.

[arnaud-lb]

I though about this when adding this assert, but if we consider functions as opaque APIs, we don't know that zend_enum_obj_from_obj() has redundant asserts.

[TimWolla]

That is fair, but in this case it is probably reasonable to expect zend_enum_obj_from_obj() to do the verification (if necessary), since that's the purpose of the function, especially since a failed assert is always a programmer error.

[TimWolla]

No particularly strong feelings either way, though.

[iluuu1994]

Nice approach. How will ADTs be handled? #define Z_PARAM_ENUM_EX(dest, obj, _ce) comes to mind. That should probably work.

[arnaud-lb]

@iluuu1994 yes this should work. Alternatively it's possible to use Z_PARAM_OBJ_OF_CLASS() + zend_enum_fetch_case_id().