add flag-constants to stub files

[staabm]

Description

to support static analysis tools, it would be really helpful to have flag-constants like JSON_FORCE_OBJECT and their value-types declared within stub files.

this types are very valuable to e.g. phpstan and could be picked up and be used while analyzing source code

see e.g. https://www.php.net/manual/en/function.json-encode.php for more examples

[cmb69]

The constants are already declared in the stub files, but most of the values are just UNKNOWN, since often we are not in control of these values (e.g. basically all cURL constants), and most of the time, developers should be agnostic to the values anyway.

[staabm]

in the docs the value-types are contained, see e.g. https://www.php.net/manual/de/curl.constants.php

maybe it would make sense to generate this manual page from information in the stubs instead?

[cmb69]

in the docs the value-types are contained, see e.g. https://www.php.net/manual/de/curl.constants.php

I don't see any values there (besides in some user notes).

maybe it would make sense to generate this manual page from information in the stubs instead?

Yes, that'd make sense, but for now we're doing only the class and function/method documentation, and we're still not completely up-to-date wrt. bundled extensions, let alone PECL extensions.

[staabm]

I am talking about the value types like int etc.

I don't think we need the concrete values, right @ondrejmirtes ?

[ondrejmirtes]

No, just the constant names.

And they're not in the stubs currently. The only place I've seen constants were UNKNOWN as default parameter values. But here we're talking about all possible constants that can be passed as values.

What I'm looking forward with that is detecting with PHPStan when the user passed a constant into json_encode that's only supposed to be used with json_decode, and other errors like that.

[TimWolla]

And they're not in the stubs currently

The constants are available in the stubs with PHP 8.2: https://github.com/php/php-src/blob/PHP-8.2/ext/json/json.stub.php (master for some stubs that didn't make the cut before the feature freeze for 8.2).

[cmb69]

I am talking about the value types like int etc.

Ah, that would make sense (especially for UNKNOWN values), even if gen_stub.php would not make use of that (at least not right away).

What I'm looking forward with that is detecting with PHPStan when the user passed a constant into json_encode that's only supposed to be used with json_decode, and other errors like that.

I see your point, but I guess that might be somewhat hard to do (some constants are just for a single function, but often they are for a "group" of functions, and actually, one could use "arbitrary" constants which have a suitable value).

cc @kocsismate

[kocsismate]

In theory, this addition sounds good, and would be nice to add support for. However there are two counterarguments:

• as Christoph mentioned, it's difficult: I declared nearly 4600 constants in stubs, and we have a few dozens left undeclared, and this is an obnoxiously huge number. There are some functions indeed which accept a large number of constants, so listing a great deal of constants per function seems very cumbersome
• Nikita was usually very serious about not adding info which is not used by PHP itself: Add more specific array return type hints for ext/reflection #7431 (comment) TBH I wouldn't want to change this direction...

[iluuu1994]

This sounds like a WONTFIX atm. @kocsismate Could you close this issue if that's the case?