Generate C enums from internal enums, introduce Z_PARAM_ENUM() #20917

arnaud-lb · 2026-01-12T19:16:39Z

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 · 2026-01-12T21:46:04Z

Zend/zend_enum.h


+static zend_always_inline zend_long zend_enum_fetch_case_id(zend_object *zobj)
+{
+	ZEND_ASSERT(zobj->ce->ce_flags & ZEND_ACC_ENUM);


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

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.

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.

No particularly strong feelings either way, though.

TimWolla · 2026-01-12T21:48:38Z

ext/dom/php_dom_decl.h

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

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.

build/gen_stub.php

Zend/zend_enum.h

ext/pcntl/pcntl.c

iluuu1994 · 2026-01-13T13:14:28Z

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

arnaud-lb · 2026-01-13T13:56:47Z

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

ext/bcmath/bcmath.c

Girgias · 2026-01-13T18:45:09Z

ext/random/php_random.h

 # include "php.h"
 # include "php_random_csprng.h"
 # include "php_random_uint128.h"
+# include "random_decl.h"


Should the generated headername maybe be prefixed with php_ ?

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.

ext/reflection/php_reflection_decl.h

The compiler should now be able to tell us if we forget one case

build/gen_stub.php

TimWolla

Looked at everything, except ext/dom (cc @ndossche) and gen_stub.php.

Requesting changes due to the ext/uri bug I noticed. The others are primarily suggestions to clean this up as much as possible.

TimWolla · 2026-01-28T13:20:56Z

ext/uri/php_uri.c

 {
 	zend_object *that_object;
-	zend_object *comparison_mode = NULL;
+	zend_enum_Uri_UriComparisonMode comparison_mode = ZEND_ENUM_Uri_UriComparisonMode_IncludeFragment;


This is the wrong default:

php-src/ext/uri/php_uri.stub.php

Line 84 in 62c94b6

public function equals(\Uri\Rfc3986\Uri $uri, \Uri\UriComparisonMode $comparisonMode = \Uri\UriComparisonMode::ExcludeFragment): bool {}

I'm confused why this wasn't caught by tests, perhaps no test tests the default value, but only the explicit parameter.

Yes, during one of the last review round to the equals() tests (#20391 (review)), all the default value tests were removed IIRC. I noticed it at that time, but I would have never expected that they would catch a bug this fast.

Good catch!

ext/uri/php_uri.c

ext/pcntl/pcntl.c

ext/bcmath/bcmath.c

Zend/zend_enum.h

TimWolla · 2026-01-28T13:31:15Z

Zend/zend_enum.c

+zend_object *zend_enum_new(zval *result, zend_class_entry *ce, int case_id, zend_string *case_name, zval *backing_value_zv)
 {
-	zend_object *zobj = zend_objects_new(ce);
+	zend_enum_obj *intern = zend_object_alloc(sizeof(zend_enum_obj), ce);


Suggested change

zend_enum_obj *intern = zend_object_alloc(sizeof(zend_enum_obj), ce);

zend_enum_obj *intern = zend_object_alloc(sizeof(*intern), ce);

I also prefer this style, but from what I've seen there is no consensus on this. I've applied the suggestion anyway.

…to PHP_ROUND_*

github-actions bot added Category: Build System Category: Engine Extension: dom Extension: pcntl Extension: reflection Extension: standard Extension: zend_test Extension: random ABI break Extension: uri Extension: bcmath labels Jan 12, 2026

TimWolla reviewed Jan 12, 2026

View reviewed changes

arnaud-lb force-pushed the enum-c-enum branch 2 times, most recently from 0b7ca66 to adfa289 Compare January 13, 2026 12:24

arnaud-lb marked this pull request as ready for review January 13, 2026 13:56

arnaud-lb requested review from DanielEScherzer, SakiTakamachi, bukka, devnexen, dstogov, kocsismate, ndossche and zeriyoshi as code owners January 13, 2026 13:56

TimWolla reviewed Jan 13, 2026

View reviewed changes

ext/bcmath/bcmath.c Outdated Show resolved Hide resolved

ext/bcmath/bcmath.c Show resolved Hide resolved

TimWolla self-requested a review January 13, 2026 16:14

Girgias reviewed Jan 13, 2026

View reviewed changes

DanielEScherzer reviewed Jan 13, 2026

View reviewed changes

ext/reflection/php_reflection_decl.h Outdated Show resolved Hide resolved

arnaud-lb requested a review from NattyNarwhal as a code owner January 14, 2026 10:44

arnaud-lb added 22 commits January 27, 2026 16:06

Store enum case id in ZEND_AST_CONST_ENUM_INIT

c2d5e59

Store enum case id in instance

30addd5

Expose enum case_id internally

156c340

Generate C enum for internal enums

5bd0b89

Port ext/random

ffd98fa

Z_PARAM_ENUM()

79fdec2

ext/dom

1bcd8ff

ext/pcntl

fd3c8bf

ext/reflection

ca6abed

ext/uri

988c778

ext/standard

7361cd0

ext/bcmath

bb9f446

Remove underscore

bd388af

Switch to int

f4cc6d6

Fix build

366a8fc

Mark generated files

d01df3c

Header guards

95a2fd3

WS

f1d17ea

Remove default case

4e1f5c6

The compiler should now be able to tell us if we forget one case

Include _decl.h from the extension main header

4d590e5

Switch over enum constants

64915dd

Check that decl files are up to date

40036ff

arnaud-lb force-pushed the enum-c-enum branch from 8614167 to 40036ff Compare January 27, 2026 15:10

ndossche reviewed Jan 27, 2026

View reviewed changes

build/gen_stub.php Show resolved Hide resolved

TimWolla requested changes Jan 28, 2026

View reviewed changes

arnaud-lb added 4 commits January 28, 2026 19:02

Do not incorporate version into hash

664bb2c

Fix wrong default

ec7858a

Code style

e424425

Refactor bcmatch to avoid the conversion from zend_enum_RoundingMode …

2bb15f6

…to PHP_ROUND_*

arnaud-lb force-pushed the enum-c-enum branch from 3f54e91 to 2bb15f6 Compare January 28, 2026 18:07

	zend_enum_obj *intern = zend_object_alloc(sizeof(zend_enum_obj), ce);
	zend_enum_obj intern = zend_object_alloc(sizeof(intern), ce);

Generate C enums from internal enums, introduce Z_PARAM_ENUM() #20917

Are you sure you want to change the base?

Generate C enums from internal enums, introduce Z_PARAM_ENUM() #20917

Conversation

arnaud-lb commented Jan 12, 2026

Uh oh!

TimWolla left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

iluuu1994 commented Jan 13, 2026

Uh oh!

arnaud-lb commented Jan 13, 2026

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

TimWolla left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants