Allow `@phpstan-use` (and `@use`) in PHPdoc-block for classes

[nagmat84]

Feature request

PHPStan only recognizes annotations, if the annotation is inside a PHPdoc block (see PHPStan: PHPDocs Basics). But PHPdoc blocks are only allowed for structural elements of the PHP language as well as files, include and require statements (see phpDocumentor: What can be documented in your source code?).

However, if one uses a generic trait with a template parameter, one has to annotate the use-statement with the proper template parameter like this

/**
 * @template TDataType
 */
trait MyTrait {}

class MyClassA {}

class MyClassB {
  /** @phpstan-use MyTrait<MyClassA> */
  use MyTrait;
}

This is not 100% ideal as there are other tools (e.g. CS Fixer for PHP) which convert those wrongly placed PHPdoc comments into normal comments.

A solution would be to put this annotation into the PHPdoc block of the class (similar to @extends) like this

/**
 * @template TDataType
 */
trait MyTrait {}

class MyClassA {}

/**
 * @phpstan-use MyTrait<MyClassA>
 */
class MyClass {
  use MyTrait;
}

Did PHPStan help you today?

Currently, we are enabling PHPStan for Lychee as part of this PR https://github.com/LycheeOrg/Lychee/pull/1336. While we are struggling with a lot of false positives due to the used framework, it already helped us to discover a lot of bugs which were dormant in less frequently used features of Lychee.

[ondrejmirtes]

This is fairly easy to do. Places that read ResolvedPhpDocBlock::getUsesTags() need some modification. And instead of modifying UsedTraitsRule, I'd welcome an extra new rule.

[nagmat84]

Your comment sounds a little like you would like me to implement it. But I do not feel qualified at all. I can write a simple additional inspection rule using your guide, but as soon as it involves interaction with different components of PHPStan, I am lost.

[ondrejmirtes]

Do not feel obligated - it's a hint for everyone that feels like doing this :)

[nagmat84]

Why have you closed this issue?

[ondrejmirtes]

Sorry, that was by mistake.

[javaDeveloperKid]

Why have you closed this issue?

Ondrey likes to close issues faster that the speed of light.

[joelharkes]

any progress on this, i was trying to doctype my trait wondering why it wouldnt work as i thought it would be in the class block

[kiler129]

This will also break with generics inheritance: https://phpstan.org/r/953e9ea0-604f-4ce7-b64f-b3a9352b9845

The message reported will be Class FooClass uses generic trait FooTrait but does not specify its types: TTrait (added here mostly for googlers)

[baptistepillot]

I had the same wish today, so I implemented it. It is available in this version : https://github.com/baptistepillot/phpstan-src/tree/1.10.x What I've changed into phpstan source code : https://github.com/baptistepillot/phpstan-src/commit/ac779f04aa68345ab6deca33ff72d5074a0f2a67 The pull request for 1.10.x : https://github.com/phpstan/phpstan-src/pull/2638

[mxr576]

I have also bumped into this problem in Drupal, where DrupalCS (via PHPCS) does not allow docblock comments above trait use statement.

{
    "message": "Inline doc block comments are not allowed; use \"\/* Comment *\/\" or \"\/\/ Comment\" instead",
    "source": "Drupal.Commenting.InlineComment.DocBlock",
    "severity": 5,
    "fixable": false,
    "type": "ERROR",
    "line": 53,
    "column": 3
}

[mxr576]

@ondrejmirtes It seems to me that #2638 implements a different approach than what you have described in https://github.com/phpstan/phpstan/issues/7486#issuecomment-1158943404. Would you also accept the solution in #2638 or rather a new PR should be raised that would implemented your suggested approach?