dancryer/php-docblock-checker

A simple tool for checking that your PHP classes and methods use docblocks.

PHP DocBlock Checker

Check PHP files within a directory for appropriate use of Docblocks.

Installation

Composer:
composer require dancryer/php-docblock-checker

Usage

CMD:
call vendor/bin/phpdoccheck {params}

To validate changed files in the last git commit:

git diff --name-only HEAD HEAD^ | ./vendor/bin/phpdoccheck --from-stdin

If used within a travis context, this may be useful: git diff --name-only ${TRAVIS_COMMIT_RANGE:-"HEAD^"} | ./vendor/bin/phpdoccheck --from-stdin

Parameters

Parameters may be passed either from the command line, or via a config file (defaults to phpdoccheck.yml in the currrent working directory).

The config file location may be overriden by specifying the --config-file option

If a parameter is specified in both places, the command line will take priority.

Short	Long	Description
-h	--help	Display help message.
-x	--exclude=EXCLUDE	Files and directories (absolute or pattern) to exclude.
-d	--directory=DIRECTORY	Directory to scan. [default: "./"]
none	--cache-file=FILE	Use cache file to speed up processing.
none	--config-file=FILE	Use config file to specify options [default: "./phpdoccheck.yml"].
none	--from-stdin	Use list of files provided via stdin
none	--skip-classes	Don't check classes for docblocks.
none	--skip-methods	Don't check methods for docblocks.
none	--skip-signatures	Don't check docblocks against method signatures.
none	--only-signatures	Only check methods that have parameters or returns.
-j	--json	Output JSON instead of a log.
-l	--files-per-line=FILES-PER-LINE	Number of files per line in progress [default: 50]
-w	--fail-on-warnings	Consider the check failed if any warnings are produced.
-i	--info-only	Information-only mode, just show summary.
-q	--quiet	Do not output any message.
-V	--version	Display this application version.
none	--ansi	Force ANSI output.
none	--no-ansi	Disable ANSI output.
-n	--no-interaction	Do not ask any interactive question.
-v -vv -vvv	--verbose	Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug.

Each option is also available in the config file:

directory: src
files-per-line: 10
cache-file: .phpdoccheck
exclude:
  - foo/bar/baz.php
  - foo/*
options:
  - skip-classes
  - skip-methods
  - skip-signatures
  - only-signatures
  - fail-on-warnings
  - info-only
  - from-stdin
  - json

php-docblock-checker's Issues

Problem with self return type-hint documented as returning $this

This error:

WARNING  Gear4music\Search\Aggregations\AggregationStack::add_aggregations - @return $this  does not match method signature (self).

is incorrect. It's correct to set the docblock to return $this, but in this scenario the PHP7 method return type-hint would be self

PHP Notice: Array to string conversion in /vendor/dancryer/php-docblock-checker/src/Status/StatusType/Warning/ReturnMismatchWarning.php on line 76

PHP Notice: Array to string conversion in /vendor/dancryer/php-docblock-checker/src/Status/StatusType/Warning/ReturnMismatchWarning.php on line 76
PHP Stack trace:
PHP 1. {main}() /vendor/dancryer/php-docblock-checker/bin/phpdoccheck:0
PHP 2. Symfony\Component\Console\Application->run() /vendor/dancryer/php-docblock-checker/bin/phpdoccheck:45
PHP 3. Symfony\Component\Console\Application->doRun() /vendor/symfony/symfony/src/Symfony/Component/Console/Application.php:149
PHP 4. Symfony\Component\Console\Application->doRunCommand() /vendor/symfony/symfony/src/Symfony/Component/Console/Application.php:273
PHP 5. PhpDocBlockChecker\Command\CheckerCommand->run() /vendor/symfony/symfony/src/Symfony/Component/Console/Application.php:1009
PHP 6. PhpDocBlockChecker\Command\CheckerCommand->execute() /vendor/symfony/symfony/src/Symfony/Component/Console/Command/Command.php:255
PHP 7. PhpDocBlockChecker\Status\StatusType\Warning\ReturnMismatchWarning->getDecoratedMessage() /vendor/dancryer/php-docblock-checker/src/Command/CheckerCommand.php:230

Multiple return types not respected if one of those return types matches the method signature

Given a test with this code and docblock:

   /**
    * @param string $str_id
    * @return AggregationInterface|MockObject
    */
   private function create_aggregation(string $str_id): AggregationInterface {
      $obj_mock = $this->createMock(AggregationInterface::class);
      $obj_mock->method('get_id')->willReturn($str_id);

      return $obj_mock;
   }

The docblock checker says:

WARNING  \AggregationStackTest::create_aggregation - @return Array  does not match method signature (Gear4music\Search\Interfaces\AggregationInterface).

Incorrect error message when specifying array structure in docblock.

This error:

WARNING  Gear4music\Search\Aggregations\QualitativeAggregation::get_options - @return array<string,QualitativeAggregation>  does not match method signature (array).

Is incorrect. The return type is type-hinted as array, which matches the return type of the method. PHPStorm allows you to be specific in the docblock checker as to the structure of the array, which is why I've used array<string,QualitativeAggregation>

Improve "@" Infos

Hello!

Can you improve to check "@" at docblocks?

Example: force methods to have "@return" or "@param" or "@throws" if internal code have "return" or "param" or "throw".

Issue with parsing function with variadic arguments

Class with this method:

   /**
    * @param InventoryPrices ...$arr_prices
    * @return void
    */
   private function setup_inventory(InventoryPrices ...$arr_prices) {
      // ...
   }

Output from docblock checker:

PHP Docblock Checker by Dan Cryer (https://www.dancryer.com)

W

Checked 1 files in 0.08 seconds.
1 Passed / 0 Errors / 1 Warnings / 0 Info


WARNING  \InventoryPricesThreadCacheTest::setup_inventory - @param $arr_prices missing.

Cannot use with newer versions of Symfony/Console

I'm using Laravel 5.7, which depends on Symfony/Console ^4.1. This makes it impossible to install php-docblock-checker, because php-docblock-checker requires Symfony/Console 3.4.*.

Would it be possible to upgrade the Symfony dependencies of this package?

anonymous function

Remove reporting for "anonymous function" (or add an option to disable the reporting).

At the moment anonymous function (in the example below its "array_filter") will be marked because of a missing doctype:

public function someMethode()
{
        ...
        return array_filter($values, function ($var) {
            return !empty($var);
        });
}

Support for 7.1's nullable types

Methods that use nullable parameters or return types:

    public function something(): ?SomeClass {
        //
    }

    public function otherthing(?string $value) {
        //
    }

will throw an error when trying to cast PhpParser\Node\NullableType to a string:

PHP Catchable fatal error:  Object of class PhpParser\Node\NullableType could not be converted to string in /var/www/project/vendor/block8/php-docblock-checker/PhpDocblockChecker/FileProcessor.php on line 108
PHP Stack trace:
PHP   1. {main}() /var/www/project/vendor/block8/php-docblock-checker/phpdoccheck:0
PHP   2. PhpDocblockChecker\CheckerApplication->run() /var/www/project/vendor/block8/php-docblock-checker/phpdoccheck:29
PHP   3. PhpDocblockChecker\CheckerApplication->doRun() /var/www/project/vendor/symfony/console/Application.php:129
PHP   4. PhpDocblockChecker\CheckerApplication->doRunCommand() /var/www/project/vendor/symfony/console/Application.php:225
PHP   5. PhpDocblockChecker\CheckerCommand->run() /var/www/project/vendor/symfony/console/Application.php:924
PHP   6. PhpDocblockChecker\CheckerCommand->execute() /var/www/project/vendor/symfony/console/Command/Command.php:252
PHP   7. PhpDocblockChecker\CheckerCommand->processFile() /var/www/project/vendor/block8/php-docblock-checker/PhpDocblockChecker/CheckerCommand.php:146
PHP   8. PhpDocblockChecker\FileProcessor->__construct() /var/www/project/vendor/block8/php-docblock-checker/PhpDocblockChecker/CheckerCommand.php:269
PHP   9. PhpDocblockChecker\FileProcessor->processStatements() /var/www/project/vendor/block8/php-docblock-checker/PhpDocblockChecker/FileProcessor.php:40
PHP  10. PhpDocblockChecker\FileProcessor->processStatements() /var/www/project/vendor/block8/php-docblock-checker/PhpDocblockChecker/FileProcessor.php:78

PHP Fatal error: Uncaught Error: Object of class PhpParser\Node\UnionType could not be converted to string in /vendor/php-censor/phpdoc-checker/src/FileProcessor.php:173

PHPDOCCHECK 
PHPDoc Checker
PHP Fatal error:  Uncaught Error: Object of class PhpParser\Node\UnionType could not be converted to string in /vendor/php-censor/phpdoc-checker/src/FileProcessor.php:173

was caused by:
public function getInstance(Class1|Class2 $item = null): self

and temporarily fixed by

• either removal of null:
  public function getInstance(Class1|Class2 $item): self

• either adding the null to types:
  public function factoryMethod(Class1|Class2|null $item = null): self

Acceptance Criteria:
PHPDoc Checker can read functions with union typed properties without the causing PHP error and output readable notice about deveoper's error. Something like:
Please add |null to $item in getInstance() to be able to set the value = null.

symfony/console 5.* support

Actual version of the package symfony/console for Laravel LTS version (8.*) is 5.*: https://github.com/laravel/laravel/blob/8.x/composer.json

But dancryer/php-docblock-checker depends version 4.*. Because of this, checker cannot be use with laravel 8.

What are you think about updating the package symfony/console version?

Documentation?

Any chance of some docs?

?string string|null is not parsed

try this code:

 /**
     * Some description
     * @param array  $res
     * @return string|null
     */
    public function sellVoucher(
        array $res
    ): ?string {
        
        if ($res && isset($res['certNumber']))  {
            return (string)$res['certNumber'];
        }

        return null;
    }

and get
WARNING @return string|null does not match method signature (Array).

but this annotation is ok and should be accepted