Where are the class/version information stored?

[thg2k]

PHPStan understands when classes made it into the language, so for example setting { parameter: phpVersion: 70400 } will detect class WeakMap as not existing. But I can't figure out where this information is stored in the source code/stubs. Any hint would be very appreciated!

[ondrejmirtes]

It's in jetbrains/phpstorm-stubs and https://github.com/phpstan/php-8-stubs

[thg2k]

Great, thank you! I tried tuning the @since phpdoc and it correctly affects the class detection.

But now i'm more confused than before. If all those information are acquired, then what is the role/purpose of the following?

1. jetbrains/phpstorm-stubs: As I understand, this is the "base" for loading all symbols according to the @since tag.
2. phpstan/php-8-stubs: Is this an extension of the above? Why is it needed? From a brief look, I have the feeling the first one already covers it all.
3. source stubs folder: Same as above?
4. source resources/functionMap[...]: Same as above? Isn't the signature already covered in the 1) 2) and 3) phpdoc annotations, including versioning information?
5. source resource/functionMetadata.php: This only contains hasSideEffect true/false, isn't this already covered by the #[Pure(true)] annotation in 1)?

Thank you again, i'm trying to get a better understanding of the internal mechanics to do some tuning, I will then later submit some PRs, if I succeed 😄

[ondrejmirtes]

Hi, it would be better if you told me what kind of improvements you have in mind, and I'll tell you if they make sense and whether they're possible or not :)

There's a bit about what you're asking in the documentation: https://phpstan.org/user-guide/troubleshooting-types#internal-stubs

Personally I'm annoyed by a few persistent bugs:

Some function signatures on PHP 8.2 aren't correct

#7760
#9793

I believe the sources we use already have it correct but it gets lost here in Php8SignatureMapProvider probably.

Functions that have multiple variants (like getenv) will choose/generate a wrong variant for named arguments call

#9823

We have the canonical signature used for these functions from php-8-stubs but it gets lost when multiple variants (multiple entries in functionMap.php) get combined in ParametersAcceptorSelector.

The solution: Introduce getNamedArgumentsVariant() in FunctionReflection and ExtendedMethodReflection interfaces. And use it in ParametersAcceptorSelector if named arguments occur.

[thg2k]

I checked those pointers, but it doesn't really answer my questions. I now know those 4 are the source of information but I don't exactly understand why. Shouldn't we be able to get rid of them and keep only the "one true source"?

As for the feature i'm working on, I'm trying to make phpstan correctly analyze a PHP 5.6 source code. I'd like it to spot functions and classes that did not exist before 7.x. I suppose you are not interested in this feature, but I bet some useful bugfix/refactoring opportunities might come out of this.

[ondrejmirtes]

Shouldn't be able to get rid of them and keep only the "one true source"

No :) Each source has something the other does not.

I'm trying to make phpstan correctly analyze a PHP 5.6 source code

That's totally fine. I'm not sure if these differences are in jetbrains/phpstorm-stubs but in theory it should be possible to achieve this feature by providing delta files in https://github.com/phpstan/phpstan-src/tree/1.11.x/resources.

functionMap.php is written from the point of view of PHP 7.3. The final signature map is achieved by combining this file and the delta files. The logic is in FunctionSignatureMapProvider::getSignatureMap.

You need to start by allowing a wider PHP version range in these places:

• https://github.com/phpstan/phpstan-src/blob/72242b32f3809f3a2073ae2406bd33f1a05cd9ca/conf/parametersSchema.neon#L121
• https://github.com/phpstan/phpstan-src/blob/72242b32f3809f3a2073ae2406bd33f1a05cd9ca/src/Php/PhpVersionFactory.php#L26

You can probably inspire yourself in competing OSS tools (the signature map format and the initial version comes from Phan):

• https://github.com/phan/phan/tree/v5/src/Phan/Language/Internal
• https://github.com/vimeo/psalm/tree/5.x/dictionaries

[thg2k]

I already figured all of that out :) You can take a look at the latest commit here: https://github.com/thg2k/phpstan-src/tree/1.10.x-thg1

The problem is exactly this:

No :) Each source has something the other does not.

That's exactly what I can't figure out. What do we achieve for example with the stubs folder that we can't achieve with phpstorm stubs or the php-8 stubs you maintain?

And what about the function signatures? Why are they needed? Besides funny cases where the signature is overloaded or changed over time, which is not well represented in the stub files, shouldn't be the same information already available?

[ondrejmirtes]

Some examples from the top of my head:

• phpstorm-stubs usually don't have advanced types like list or specific array shapes. functionMap.php is full of them because it's the easiest to contribute them to PHPStan.
• phpstorm-stubs needs to be used to analyse code that uses PHP extensions which are not loaded by the PHP runtime that's used to run PHPStan. For example developers don't have all extensions installed locally but that code is used on production servers which have those extensions. Because phpstorm-stubs involves "code", we can use it to build full reflection data. That's something that functionMap.php will not tell us (which class is extending from which parent...).
• php-8-stubs are extracted directly from php-src which added those "official" stubs in PHP 8.0. It also contains the differences between PHP versions. It's very beneficial because we know each parameter name correctly without the need to update these in functionMap.php. We also get support for function signature changes in each PHP version for free without the need to update our own functionMap.php and the delta files.
• functionMap.php contains entries for functions that aren't in phpstorm-stubs nor php-8-stubs.