declare `@param-out` in stubs

[staabm]

Description

since phpstan 1.9 support for @param-out phpdoc was added. psalm supports it for a longer time.

it would be great if the php-src stub files could annotate the sources with @param-out when the types a parameter manipulated by referenced are known. that way the tools could consume the types, without the need to maintain such list in all tools redundantly.

one example is e.g.

php-src/ext/curl/curl.stub.php

Lines 3598 to 3603 in 02ed122

	/**
	* @param int $queued_messages
	* @return array<string, int|object>|false
	* @refcount 1
	*/
	function curl_multi_info_read(CurlMultiHandle $multi_handle, &$queued_messages = null): array|false {}

[staabm]

I had a look into the stub generator. I think I found the lines which are responsible for generating these types, but I could not find the place where the actual @param rendering happens.

any hints would be great.

[iluuu1994]

@kocsismate is probably the one to best answer that 🙂

[cmb69]

I don't think this information could be useful for php-src (at least for now), so gen_stub.php would not need to be adjusted. Still, it may make sense to add these docblock tags to the stub files.

[staabm]

I can't judge php-src usage. My primary motivation is getting the docblocks into the stubs, since these are read by phpstan

[cmb69]

@staabm, consider submitting a PR with the changes to *.stub.php only. :)

[kocsismate]

So far, we only added any info to stubs if php-src itself uses it. As we cannot make any use of param-out tags just yet, I think it's not the best idea to start to do so. However, I added in/out parameters to my task list not long ago. I'm not sure my knowledge is enough to take care of this feature, but I'd be happy if PHP could support it on the longer run. But until then, I'm not sure it's worth to maintain these annotations.

[staabm]

submitting a PR with the changes to *.stub.php only.

Ohh I see. I had the impression those files are generated and manual changes would be lost after a re-generation process.

I can submit those changes to the stubs, if we agree on it

[bwoebi]

@kocsismate Whils that's probably most puristic, I think, if anyone is wiling to add these extra annotations we just may add them. Ultimately function signatures in php-src change very rarely (i.e. we have defacto zero maintenance overhead in ensuring that these stay correct), it's mostly new functions being added (they're then just missing, but not wrong).

I think ideally, while php-src itself doesn't make use of these, maybe the docs could use them?

[cmb69]

I think ideally, while php-src itself doesn't make use of these, maybe the docs could use them?

Indeed, that might be possible and seems to be a good idea.

[kocsismate]

Whils that's probably most puristic, I think, if anyone is wiling to add these extra annotations we just may add them.

Nikita didn't like to add unused info into stubs #7431 (comment) Even though I agree with (or at least accepted) this direction, I could imagine making an exception with out params since we have long(er) term goals with them

I think ideally, while php-src itself doesn't make use of these, maybe the docs could use them?

Yeah, using these in docs would definitely make this info more useful to have!

[staabm]

PHPstan changed course and will take regular @param phpdocs into account, even for param-by-ref. See phpstan/phpstan-src@2f55c7c

I think this means we can close here as no longer necessary. Thanks anyone.