Is there a PHPCS standard targeting PHP docblocks?

Question

Is there a PHPCS coding standard that would check that proper annotations (@param, @return, @throws, etc.) are present in a docblock, including the proper spacing between them?

Answer 1

Try running the following command and see if it produces what you want:

phpcs /path/to/code --standard=Squiz --sniffs=Squiz.Commenting.FunctionComment,Squiz.Commenting.FunctionCommentThrowTag,Squiz.Commenting.ClassComment,Squiz.Commenting.FileComment,Squiz.Commenting.VariableComment

If it does, you could create your own standard that just includes those sniffs, and anything else you want to check. You do this by creating a ruleset.xml file and using that as your standard.

For example, you could create a file called mystandard.xml and include the following content:

<?xml version="1.0"?>
<ruleset name="MyStandard">
  <description>My custom coding standard.</description>
  <rule ref="Squiz.Commenting.FunctionComment" />
  <rule ref="Squiz.Commenting.FunctionCommentThrowTag" />
  <rule ref="Squiz.Commenting.ClassComment" />
  <rule ref="Squiz.Commenting.FileComment" />
  <rule ref="Squiz.Commenting.VariableComment" />
</ruleset>

Then you can run this command instead:

phpcs /path/to/code --standard=/path/to/mystandard.xml

There are other things you can do in a ruleset.xml file. See the docs here: https://github.com/squizlabs/PHP_CodeSniffer/wiki/Annotated-Ruleset

Answer 2

In 2017 you have now more options:

• one of the best sniffs to check docblocks is TypeHintDeclarationSniff from SlevomatCodingStandard, works great with PHP 7, PHP 7.1, drop unused docs etc.
• also you can make use of another tool - PHP-CS-Fixer, there you can find more fixers, that will help you with docblock, just search "doc"

Answer 3

Disclaimer: I'm author of Rector.

In 2019 you can use static analysis to complete @var types or type declarations for you.

class SomeClass
{
    private $value;

    public setValue(string $string)
    {
        // here we know the string type is assigned
        $this->value = $value;
    }    
}

Knowing that, Rector autocomplete the var type:

class SomeClass
{
    /**
     * @var string
     */
    private $value;

    public setValue(string $string)
    {
        $this->value = $value;
    }    
}

Similar approach works for return type, PHP 7.4 types and type declarations from parent interfaces and classes. All supported by Rector.

Read more in How to Complete Type Declarations without Docblocks with Rector