Deprecated method from parent, overridden/replaced in current class: avoid deprecation rule violations

[mglaman]

This is a tricky one, and I'm not sure the best way to handle it. In Drupal we had a lot of random test assert helps carried over from our Simpltest pre-PHPUnit days. One of which was assertOptionSelected, which lived in a trait. It was marked as @deprecated and some projects have made their own updated version of the method to avoid rewriting a bunch of tests.

I understand why PHPStan still flags this as a deprecated call: PHPStan has no idea if this override has no side effects (ie: won't be executed in the future or whatever.)

It does so here: \PHPStan\Reflection\Php\PhpMethodReflection::isDeprecated

    public function isDeprecated() : \PHPStan\TrinaryLogic
    {
        return $this->reflection->isDeprecated()->or(\PHPStan\TrinaryLogic::createFromBoolean($this->isDeprecated));
    }

The $this->reflection is not deprecated due to overridden PHPDoc without @inheritdoc tag, but $this->isDeprecated is already true.

My thought was:

If the called method is deprecated, check if it exists in the current class. If it has been overridden and does not invoke its parent, consider as a replacement for the deprecated parent method. (This seems very messy.)

I didn't open an issue for https://github.com/phpstan/phpstan-deprecation-rules as it doesn't seem like a bug or something that could have a straight forward fix. I'm going to guess the best fix is to have code add // @phpstan-ignore-next-line until Drupal 10.0.0 is released and the deprecated code is officially killed off.

[ondrejmirtes]

So the problem is that @deprecated gets inherited implicitly. Some people liked the previous behaviour and some people like the new behaviour.

Related:

• Child function inheriting deprecated state? phpstan-deprecation-rules#70
• Detecting deprecated methods from an interface phpstan-deprecation-rules#48
• Detect deprecated methods from the interface as well. phpstan-src#792

I think we should introduce something like @not-deprecated to switch off the deprecation status in a child method.

[mglaman]

I was wondering about @not-deprecated, but I wasn't sure since it's creating a new arbitrary tag. I think it's better to be "greedy" in deprecation assumptions. But it would be nice to have a single "ignore this deprecation" versus at each call.

Would we want @not-deprecated to live in the deprecation rules package?

[ondrejmirtes]

@not-deprecated would have to be handled somewhere in here https://github.com/phpstan/phpstan-src/blob/beac2678a8d29484fb7a914197599d689850b7eb/src/PhpDoc/ResolvedPhpDocBlock.php#L715-L732 to break the inheritance chain.

That would inform phpstan-deprecation-rules and all other places that might ask about isDeprecated().

[ondrejmirtes]

And after that you could use @not-deprecated in the real PHPDocs, or in stub files.

[mglaman]

Thanks! I'll try to find time to dig into this