This isn't sufficient, we also need @param-out stub like this: https://github.com/phpstan/phpstan-src/blob/85ee4f990329ec0ea2160184052b2bc9950a66af/stubs/core.stub#L72

Hm I don’t quite get functionMaps purpose then; should every function in there also be included in stubs files?

functionMap describes the types of parameters and return types. For by-ref parameters, it describes the expected type of argument for a function call.

@param-out describes the out-type of by-ref parameter, which can be different.

Also see: https://phpstan.org/user-guide/troubleshooting-types#internal-stubs

PHPStan needs to know precise parameter and return types of built-in PHP functions and those coming from loaded PHP extensions. There are four separate sources for that:

• PHPStan-maintained functionMap.php, and deltas for different PHP versions
• PHPStan stubs used to augment PHPDocs of built-in PHP classes and functions
• jetbrains/phpstorm-stubs
• Official PHP stubs extracted from php-src if you're on PHP 8 and later
• For custom PHP extensions that are not present in jetbrains/phpstorm-stubs, their PHP reflection data is used.

The way these are combined together to offer the full picture is a very complex logic and subject to frequent change as bugs are getting fixed and improvements made.

Hm in #8294 (reply in thread) I read that

When @param-out is not present and the parameter is by-ref, the out type is going to be same as the parameter type.

And I can see stream_socket_client’s by-ref parameters are typed in https://github.com/phpstan/php-8-stubs/blob/8b29105305d85fa440ae0bce1d4d83fcdf5b47ca/stubs/ext/standard/stream_socket_client.php

Is the fix still to update PHPStan stubs? I guess stream_socket_client wouldn’t be the only concerned function then?

That's the case for userland functions. Not for built-in ones.

I don't want to turn on that behaviour globally because there might be functions for which this isn't true.

Please just stick to contributing the stub as I originally suggested.