Add @param-out support

[staabm]

requires phpstan/phpdoc-parser#150
refs phpstan/phpstan#6426 (comment)

closes phpstan/phpstan#7231
closes phpstan/phpstan#6871
closes phpstan/phpstan#6186
closes phpstan/phpstan#4372

see https://psalm.dev/docs/annotating_code/supported_annotations/#param-out-psalm-param-out

just put togehter the basic building blocks and tests:

•  wire ResolvedPhpDocBlock
•  wire ResolvedDocNodeResolver
•  validate param-out phpdoc tags and tests
• initial NodeScopeResolverTests
• implement param-out type specification

I had the idea of adding param-out-type specification of the expressions right before the return-type of FuntionLikes is handled - I have not yet an idea where this place is though and whether thats a good idea :)

would be great to get a hint, where/how the actual param-out logic should be implemented.

[ondrejmirtes]

In NodeScopeResolver there are places that are interested in PassedByReference - @param-out should be handled there.

Also - require your version of phpdoc-parser with the support added in composer.json, so that the pipeline can actually get green.

Also, you have to guard any call to new method on PhpDocNode with method_exists so that Rector can do its downgrading job. See: #1799 (comment)

[staabm]

thanks for the tips.

I tried testing the PR with the following code

<?php

use function PHPStan\Testing\assertType;

class X {
	/**
	 * @param-out string $s
	 */
	function addFoo(?string &$s): void
	{
		if ($s === null) {
			$s = "hello";
		}
		$s .= "foo";
	}
}

function foo1(?string $s) {
	assertType('string|null', $s);
	$x = new X();
	$x->addFoo($s);
	assertType('string', $s);
}

but I currently struggle with php-doc resolving. 2 problems arise:

• in NodeScopeResolver->getParameterOutTypes(..) the phpdoc /** @param-out string $s */ gets always resolved to an empty-block from these lines

  phpstan-src/src/Type/FileTypeMapper.php

  Lines 111 to 113 in 49cd131

  	if (!isset($this->inProcess[$fileName][$nameScopeKey])) { // wrong $fileName due to traits
  	return ResolvedPhpDocBlock::createEmpty();
  	}

• FunctionReflection does not yet contain a getDocComment method (like MethodReflection has)... it seems this is a missing part I need to implement with this PR?

[staabm]

I should write comments about my problems more often... sorry/thanks for rubberducking.. found the reason for doc-block resolving problem because I had mixed up caller and callee side of things - 48a2cf8.

I think the PR works now as expected for basic method examples. open todo is for regular functions. I would implement a getDocComment method on FunctionReflection now, to get it working... if we agree on this

[staabm]

for some reason the PR as is failling after rebase, because I am running into -> fixed by re-adding a recently added use-statement which got lost after manual merge conflict resolving

phpstan-src/src/Analyser/NodeScopeResolver.php

Lines 531 to 533 in f097ca9

	if (!$methodReflection instanceof ExtendedMethodReflection) {
	throw new ShouldNotHappenException();
	}

[ondrejmirtes]

You updated a lot irrelevant deps. You need to run just composer update phpstan/phpdoc-parser instead.

[ondrejmirtes]

And now you get relevant build errors finally 😊

[staabm]

I had a look into the psalm test-suite for some more advanced use-cases... I will push them as a followup after we got the basic support landed

[ondrejmirtes]

Also please test a scenario where @param-out on a method is inherited from a parent:

1. When the parameter names match.
2. When the parameters are renamed (but it should still be applied based on parameter order).
3. When the @param-out is overriden for the same parameter in the child class.

[ondrejmirtes]

FunctionReflection|ExtendedMethodReflection should already have a method for @param-out tags. But to be honest, it should probably be an information for a specific parameter on ParameterReflectionWithPhpDocs to be really clean. Something like public function getOutType(): ?Type.

[ondrejmirtes]

You shouldn't definitely parse PHPDoc here again. That's a job for PhpClassReflectionExtension, BetterReflectionProvider::getCustomFunction() and NativeFunctionReflectionProvider.

[ondrejmirtes]

This file shouldn't be commited.

[staabm]

fixed and rebased. thank you

[ondrejmirtes]

Thank you!

[staabm]

btw: I opened a new issue on php-src, to add/discuss @param-out directly into php-src-stubs

php/php-src#9897

[ondrejmirtes]

@staabm Could you describe and open another issue for flag constants added to the stubs too? Like all the valid constants for $flags on json_encode (https://www.php.net/manual/en/function.json-encode.php) could be there.

[staabm]

open another issue for flag constants added to the stubs too?

here we go: php/php-src#9900