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

[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.

[TimWolla]

The _decl files should be listed in .gitattributes as linguist-generated -diff.

[arnaud-lb]

Agreed. I've added **/*_decl.h, but this could accidentally match unrelated files. I'm hesitating to use another name that would be less likely to match unrelated files, such as {$ext}_arginfo_decl.h.

[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().

[Girgias]

Should the generated headername maybe be prefixed with php_ ?

[arnaud-lb]

The file name is generated from the stub file name. In this case the stub file is named random.stub.php, so we generate random_arginfo.h and random_decl.h. Some extensions have a stub file whose name is prefixed with php_, but most don't.

[TimWolla]

At this point I wonder if it makes sense to just unconditionally regenerate the stub files (but keep the hash as an easy way to generate “merge conflicts”, forcing users to regenerate the arginfo). Make's mtime tracking should already ensure that arginfo files are not needlessly regenerated.

see also #20891.

[TimWolla]

It was also non-obvious to me why the “stub hash” changed, despite the stubs not changing. Previously it was a straight-forward “stub hash”, now it's more of a “stub version” due to the _v2 suffix.

The change to the header to include the actual file name makes sense to me (but should ship independently, since it is so noisy having it in this PR).

[arnaud-lb]

Based on comments in #20994, I've decided to not unconditionally generate stub files, after all.

It was also non-obvious to me why the “stub hash” changed, despite the stubs not changing. Previously it was a straight-forward “stub hash”, now it's more of a “stub version” due to the _v2 suffix.

Forcing a hash change was necessary, otherwise the only thing a hash check tells us is whether the arginfo.h file is up to date, not whether decl.h is.