Let @pure-unless-* tags take precedence over the class-level purity tags

[zonuexe]

Follow-up to #6666 (comment). In a class marked @phpstan-all-methods-pure, the class-level tag overrode a method's own @pure-unless-parameter-passed or @pure-unless-callable-is-impure and made the method unconditionally pure. PHPStan then missed a caller that passes $count or an impure callback:

/** @phpstan-all-methods-pure */
class Replacer
{
	/**
	 * @param-out int $count
	 * @pure-unless-parameter-passed $count
	 */
	public function replace(string $subject, int &$count = 0): string
	{
		$count = 1;

		return $subject;
	}
}

/** @phpstan-pure */
function caller(Replacer $r, string $s): string
{
	$c = 0;

	return $r->replace($s, $c); // not reported
}

It also reported Method Replacer::replace() is marked as pure but parameter $count is passed by reference. on the method itself.

Changes

• PhpDocsResolver and PhpClassReflectionExtension::createUserlandMethodReflection() apply @phpstan-all-methods-pure / @phpstan-all-methods-impure only to a method without a @pure-unless-* tag, written or inherited. @phpstan-pure already works this way: an inherited @phpstan-pure wins over the class-level tags.
• Both classes have turbo twins, so PhpDocsResolver.cpp and PhpClassReflectionExtension.cpp get the same condition, followed by a Bump expected turbo version commit. The php-class-reflection-family differential and a new walk-trace fixture cover the new cases.

Change to the #6666 test

AllMethodsImpureChild in method-signature-pure-unless-parameter-passed.php is a @phpstan-all-methods-impure class implementing an interface method marked @pure-unless-parameter-passed. MethodSignatureRule no longer reports it: the inherited tag now wins over the class-level one, the same as an inherited @phpstan-pure would. PHPStan checks its body against the inherited conditional purity instead and reports the echo there. The fixture now covers the other direction too, an impure override of a method declared in a @phpstan-all-methods-pure class, for both tags.

Verified locally

make tests with and without the extension, make phpstan, make cs, the strict build, smoke.php, signature-parity.php, side-by-side.php, walk-trace.php over the default corpus, and byte-identical --error-format=raw output with the extension loaded and not loaded over the Pure fixtures and the reproducers.

[staabm]

I am not sure about this one.

@pure-unless-callable-is-impure means its maybe pure (and maybe impure).
should it be allowed to override a "maybe pure", "maybe impure" method with "always pure" or "always impure"?

[zonuexe]

For line 62, this PR changes the message, not whether PHPStan reports the override. Before, the class-level @phpstan-all-methods-pure made the parent unconditionally pure, so this child got method.impure ("overrides pure method"). Now the parent keeps its @pure-unless-callable-is-impure, and the child gets method.impureOverridePureUnlessCallable, which #3482 added.

The tag states a conditional promise: the call is pure whenever the callback is pure. PHPStan keeps that apart from "maybe". A parent without any purity tag has isPure() maybe, and MethodSignatureRule lets any child override it. A parent with the tag promises callers a pure call for a pure callback. An always-impure child breaks that promise, so PHPStan reports it. An always-pure child keeps it for every callback, so PHPStan doesn't: each override branch in MethodSignatureRule requires the child's isPure() to be no. #6666's fixture has a PureChild for @pure-unless-parameter-passed without an expectation, and I'll add one to the callable fixture.

While checking this I found a hole in the always-pure case. A @phpstan-pure child inherits the parent's @pure-unless-callable-is-impure through ResolvedPhpDocBlock::merge(), so FunctionPurityCheck lets it call $cb() without an error, while callers treat the child as unconditionally pure: a pure function that calls $child->run($impureCallback) gets no error. That predates this PR; I'll fix it separately.

.

[VincentLanglet]

@pure-unless-callable-is-impure means its maybe pure (and maybe impure).
should it be allowed to override a "maybe pure", "maybe impure" method with "always pure" or "always impure"?

Might be worth to start with an issue @staabm @zonuexe about what we're planning to allow/forbid about phpdoc override ; wdyt ? Before this and #6669 PR

I feel like we should allow to override the phpdoc with a bigger-purity but never with a bigger impurity.
https://phpstan.org/r/948a3b08-566b-499c-bef0-1f7a7dc1f027

Maybe first we should report this, WDYT ?

[zonuexe]

I agree with that rule: an override may promise more purity, never less. For the allow/forbid list, I ran your example on 2.3.x with Foo1 and Foo2 implementing Base. The playground shows no errors for three reasons: the classes don't implement Base there, it runs a release without bleeding edge, and that release doesn't know @phpstan-pure-unless-parameter-passed.

• With bleeding edge (reportMethodPurityOverride), MethodSignatureRule reports Foo2::getPure() as method.impure and Foo2::getMaybeImpure() as method.impureOverridePureUnlessParameterPassed. Without bleeding edge it reports neither.
• Foo1 gets nothing from MethodSignatureRule. Every purity branch there requires the child's isPure() to be no, so PHPStan doesn't report a @pure-unless-* child that overrides a @phpstan-pure parent either: the child inherits @phpstan-pure and stays pure. That case belongs on the list.
• PHPStan treats a pure method with a by-ref parameter as an error: pureMethod.parameterByRef on a method with a body, and Check the purity declarations of methods without a body #6668 extends it to abstract and interface methods behind a bleeding-edge toggle, so Foo1::getMaybeImpure() gets it there.

#6667 and #6669 don't change which overrides MethodSignatureRule reports. They change how PHPStan resolves a method's own purity before that comparison: #6667 lets a @pure-unless-* tag win over the class-level @phpstan-all-methods-pure / -impure, and #6669 stops a child's own @phpstan-pure / @phpstan-impure from inheriting the parent's @pure-unless-* tags. Under your rule, the @phpstan-pure child in #6669 is allowed, and with the PR PHPStan checks its body against @phpstan-pure and reports the $cb() call. The @phpstan-impure child is the forbidden direction, and MethodSignatureRule reports it with bleeding edge.