Help understanding where hover docs come from, and how they are updated

[beeradmoore]

Describe the bug
While developing for php8.2 we were using the hover docs to see what parameters a function can take. In this case we were using open of the ZipArchive, which is a pecl package.

While running the code we got a deprecated warning,

E_DEPRECATED: ZipArchive::open(): Passing null to parameter #2 ($flags) of type int is deprecated

But looking at the hover docs this appeared fine.

Clicking through the hover docs to take me to the current docs it says otherwise,

public ZipArchive::open(string $filename, int $flags = 0): bool|int

Cmd+clicking on open took me to the stub where it got this information,

~/.vscode/extensions/bmewburn.vscode-intelephense-client-1.12.6/node_modules/intelephense/lib/stub/zip/zip.php

At the top of this file it says

Start of zip v.1.14.0

Does that v1.14.0 refer to the pecl zip package v1.14.0?

Looking at my local machine and my remote machine they are both using php8.2 with pecl zip package v1.21.1.

Is this expected behaviour? Is there a process to update those versions bundle with the extension, and by updating those this would impact people not the older versions still?

To Reproduce

$templateZip = new ZipArchive();
$localPath = 'some/zip/file.zip';
$flags = null;
$templateZip->open($localPath, $flags);

and then over on the open

Expected behavior
Docs related to the current packages/php installed locally, rather than those distributed within the package. Though I understand if that is not possible and it is distributed the way it is because of that.

Screenshots
Pictured above.

Platform and version
macOS 15.0.1
php8.2
Intelephense 1.12.6

EDIT: I just found where those node modules come from, and the notice that says it comes originally from JetBrains phpstorm-stubs.

[bmewburn]

The built-in stubs are derived from https://github.com/JetBrains/phpstorm-stubs . They are updated with each minor release from the upstream repo. The upstream repo appears to be updated quite regularly but there are inconsistencies which like this one. You can submit a PR upstream.

Docs related to the current packages/php installed locally

I don't think there are any docs distributed with php. Let me know if I have that wrong. There's stubs in the php src but from what I have seen they are just the symbol definitions with no text. There is the official php doc repo that is used to build the official php docs but it is not in a format (xml) that makes it easy to be consumed by intelephense. Also there is phpdoc templates, conditional returns, and various utility type syntax that has to be considered which adds richer type information which is not available in the official docs.

[beeradmoore]

Thanks for the info. I'll look into what we use and how far out of date things are and submit a PR.

I don't think there are any docs distributed with php. Let me know if I have that wrong.

php regularly surprises me with things it can do or hidden methods I never knew about. I would not be shocked if it had support for it, but if you have never heard of it (and no one has bought it up here) I assume it doesn't have it.

If there were an easy way for users to generate their own stubs docs directory (outside the scope of this project), would it be possible to have an option in the extension to load those stubs from an external directory first and then fall back to the built in ones when something is not found?