Improved "deprecated" support to work with internal classes and PHP version constraints

[kukulich]

The "deprecated" support is provided by the @deprecated annotation. There was already support for it, so I've just extend it.

There's just one disadvantage - the doccomment is not the same that is in the stubs but I don't think it's an issue for internal stubs.

---

There's another possible solution. The support can be provided by special BR Deprecated attribute that will be added in ReflectionSourceStubber or PhpStormSourceStubber.

Advantages:

• The doccomment will be untouched
• The attribute can be easily filtered in future getAttributes() methods so we can ignore it where we want.
• It allows to support even deprecated parameters: https://github.com/JetBrains/phpstorm-stubs/blob/master/Core/Core.php#L343

Waiting for ideas/thoughts :)

[Ocramius]

here's just one disadvantage - the doccomment is not the same that is in the stubs but I don't think it's an issue for internal stubs.

Not a big deal: internal stubs are not really in use by anyone so far, AFAIK.

If we need parity on internal methods too, we can improve/iterate on that

[kukulich]

@Ocramius Is it something I should fix here? I'm not able to find anything...

[asgrim]

Hm - would be nice if we can make this @psalm-pure if it is static, although I'm not sure if DocBlockFactory::createInstance is pure itself

[kukulich]

I can remove DocBlockFactory completely. It can be easy regexp I suppose...

[Ocramius]

We can mark it @psalm-pure and then use an inline suppression after inspection of DocblockFactory.

At first glance, DocblockFactory seems quite safe to use, when isolated this way: https://github.com/phpDocumentor/ReflectionDocBlock/blob/0005eb9eaecc2a3a00b8ee34c06643a316ebb228/src/DocBlockFactory.php

[kukulich]

So should I suppress everything?

ERROR: ImpureStaticProperty - src/Reflection/Deprecated/DeprecatedHelper.php:25:9 - Cannot use a static property in a mutation-free context (see https://psalm.dev/221)
        self::$docBlockFactory ??= DocBlockFactory::createInstance();


ERROR: ImpureMethodCall - src/Reflection/Deprecated/DeprecatedHelper.php:25:53 - Cannot call an impure method from a pure context (see https://psalm.dev/203)
        self::$docBlockFactory ??= DocBlockFactory::createInstance();


ERROR: ImpureStaticProperty - src/Reflection/Deprecated/DeprecatedHelper.php:27:21 - Cannot use a static property in a mutation-free context (see https://psalm.dev/221)
        $docBlock = self::$docBlockFactory->create($docComment);


ERROR: ImpureMethodCall - src/Reflection/Deprecated/DeprecatedHelper.php:27:45 - Cannot call a non-mutation-free method phpDocumentor\Reflection\DocBlockFactory::create from a pure context (see https://psalm.dev/203)
        $docBlock = self::$docBlockFactory->create($docComment);


ERROR: ImpureMethodCall - src/Reflection/Deprecated/DeprecatedHelper.php:29:27 - Cannot call a non-mutation-free method phpDocumentor\Reflection\DocBlock::hasTag from a pure context (see https://psalm.dev/203)
        return $docBlock->hasTag('deprecated');

[Ocramius]

I'd say so - all of this is literally in-memory operations on a string

[kukulich]

9221c32

[Ocramius]

Thanks @kukulich! 👍