PHP Classes

PHP Doctor: Scan PHP to find missing or wrong PHPDoc comments

Recommend this page to a friend!
     
  Info   Example   View files Files   Install with Composer Install with Composer   Download Download   Reputation   Support forum   Blog    
Ratings Unique User Downloads Download Rankings
Not enough user ratingsTotal: 65 All time: 10,389 This week: 560Up
Version License PHP version Categories
phpdoctor 1.0MIT/X Consortium ...7Tools, Testing, PHP 7
Description 

Author

This package can scan PHP to find missing or wrong PHPDoc comments.

It can scan a given string with PHP code or a PHP script file or all PHP script files in a given directory.

The package returns all the documentation errors that it finds in the scanned code.

Innovation Award
PHP Programming Innovation award nominee
November 2020
Number 2
Having good documentation is important for any project as it helps remembering all relevant aspects of how to use the programming components that are well documented.

A common practice among PHP developers is to use PHPDoc comments to store attributes about the different sections of a component like classes, functions, variables.

On a complex project it is hard to have all relevant components well documented.

This package simplifies the process of producing complete documentation of projects with multiple components, as it can scan code files to find which components are missing documentation in PHPDoc format, or even find mistakes in existing PHPDoc comments.

Manuel Lemos
Picture of Lars Moelleken
  Performance   Level  
Name: Lars Moelleken <contact>
Classes: 25 packages by
Country: Germany Germany
Age: 36
All time rank: 62140 in Germany Germany
Week rank: 214 Up11 in Germany Germany Up
Innovation award
Innovation award
Nominee: 11x

Winner: 1x

Example

<?php

/** @noinspection InvertedIfElseConstructsInspection */
/** @noinspection TransitiveDependenciesUsageInspection */

declare(strict_types=1);

namespace
voku\PHPDoctor;

use
Symfony\Component\Console\Application;

(static function () {
   
error_reporting(E_ALL);
   
ini_set('display_errors', 'stderr');
   
gc_disable(); // performance boost

   
\define('__PHPDOCTOR_RUNNING__', true);

   
/** @noinspection UsingInclusionOnceReturnValueInspection */
    /** @noinspection UsingInclusionReturnValueInspection */
   
$devOrPharLoader = require_once __DIR__ . '/../vendor/autoload.php';
   
$devOrPharLoader->unregister();

   
$autoloaderInWorkingDirectory = getcwd() . '/vendor/autoload.php';
   
$autoloaderProjectPaths = [];
    if (
is_file($autoloaderInWorkingDirectory)) {
       
$autoloaderProjectPaths[] = \dirname($autoloaderInWorkingDirectory, 2);

       
/** @noinspection PhpIncludeInspection */
       
require_once $autoloaderInWorkingDirectory;
    }

   
$autoloadProjectAutoloaderFile = static function (string $file) use (&$autoloaderProjectPaths): void {
       
$path = \dirname(__DIR__) . $file;
        if (!\
extension_loaded('phar')) {
            if (
is_file($path)) {
               
$autoloaderProjectPaths[] = \dirname($path, 2);

               
/** @noinspection PhpIncludeInspection */
               
require_once $path;
            }
        } else {
           
$pharPath = \Phar::running(false);
            if (
$pharPath === '') {
                if (\
is_file($path)) {
                   
$autoloaderProjectPaths[] = \dirname($path, 2);

                   
/** @noinspection PhpIncludeInspection */
                   
require_once $path;
                }
            } else {
               
$path = \dirname($pharPath) . $file;
                if (\
is_file($path)) {
                   
$autoloaderProjectPaths[] = \dirname($path, 2);

                   
/** @noinspection PhpIncludeInspection */
                   
require_once $path;
                }
            }
        }
    };

   
$autoloadProjectAutoloaderFile('/../../autoload.php');

   
$devOrPharLoader->register(true);

   
$reversedAutoloaderProjectPaths = array_reverse($autoloaderProjectPaths);

   
$app = new Application('PHPDoctor');

   
/** @noinspection UnusedFunctionResultInspection */
   
$app->add(new \voku\PHPDoctor\CliCommand\PhpDoctorCommand($reversedAutoloaderProjectPaths));

   
/** @noinspection PhpUnhandledExceptionInspection */
   
$app->run();
})();


Details

Build Status Codacy Badge Latest Stable Version License Donate to this project using Paypal Donate to this project using Patreon

? *PHPDoc*tor

Check PHP files or directories for missing types.

If you already use PHPStan for your type checks but sometimes someone in the team still commit non typed code, then PHPDoctor is for you.

Install via "phar" (recommended)

https://github.com/voku/PHPDoctor/releases

Install via "composer require"

composer require-dev voku/phpdoctor

Quick Start

Usage:
  analyse [options] [--] <path...>

Arguments:
  path                                                                                   The path to analyse

Options:
      --autoload-file[=AUTOLOAD-FILE]                                                    The path to your autoloader. [default: ""]
      --access[=ACCESS]                                                                  Check for "public|protected|private" methods. [default: "public|protected|private"]
      --skip-ambiguous-types-as-error[=SKIP-AMBIGUOUS-TYPES-AS-ERROR]                    Skip check for ambiguous types. (false or true) [default: "false"]
      --skip-deprecated-functions[=SKIP-DEPRECATED-FUNCTIONS]                            Skip check for deprecated functions / methods. (false or true) [default: "false"]
      --skip-functions-with-leading-underscore[=SKIP-FUNCTIONS-WITH-LEADING-UNDERSCORE]  Skip check for functions / methods with leading underscore. (false or true) [default: "false"]
      --skip-parse-errors[=SKIP-PARSE-ERRORS]                                            Skip parse errors in the output. (false or true) [default: "true"]
      --path-exclude-regex[=PATH-EXCLUDE-REGEX]                                          Skip some paths via regex e.g. "#/vendor/|/other/.*/path/#i" [default: "#/vendor/|/tests/#i"]

Demo

Parse a string:

$code = '
<?php declare(strict_types = 1);   
     
class HelloWorld
{
    /
     * @param mixed $date
     */ 
    public function sayHello($date): void
    {
        echo \'Hello, \' . $date->format(\'j. n. Y\');
    }
}';

$phpdocErrors = PhpCodeChecker::checkFromString($code);

// [8]: missing parameter type for HelloWorld->sayHello() | parameter:date']

Ignore errors

You can use `<phpdoctor-ignore-this-line/>` in @param or @return phpdocs to ignore the errors directly in your code.

/
 * @param mixed $lall <p>this is mixed but it is ok, because ...</p> <phpdoctor-ignore-this-line/>
 *
 * @return array <phpdoctor-ignore-this-line/>
 */
function foo_ignore($lall) {
    return $lall;
}

Building the PHAR file

phive install --force-accept-unsigned humbug/box
php tools/box compile --debug

Support

For support and donations please visit Github | Issues | PayPal | Patreon.

For status updates and release announcements please visit Releases | Twitter | Patreon.

For professional support please contact me.

Thanks

  • Thanks to GitHub (Microsoft) for hosting the code and a good infrastructure including Issues-Managment, etc.
  • Thanks to IntelliJ as they make the best IDEs for PHP and they gave me an open source license for PhpStorm!
  • Thanks to Travis CI for being the most awesome, easiest continous integration tool out there!
  • Thanks to StyleCI for the simple but powerfull code style check.
  • Thanks to PHPStan && Psalm for really great Static analysis tools and for discover bugs in the code!

  Files folder image Files (41)  
File Role Description
Files folder image.github (4 files)
Files folder image.phive (1 file)
Files folder imagebin (2 files)
Files folder imagesrc (1 directory)
Files folder imagetests (15 files)
Accessible without login Plain text file .editorconfig Data Auxiliary data
Accessible without login Plain text file .php_cs Example Example script
Accessible without login Plain text file .scrutinizer.yml Data Auxiliary data
Accessible without login Plain text file .styleci.yml Data Auxiliary data
Accessible without login Plain text file .travis.yml Data Auxiliary data
Accessible without login Plain text file box.json.dist Data Auxiliary data
Accessible without login Plain text file CHANGELOG.md Data Auxiliary data
Accessible without login Plain text file circle.yml Data Auxiliary data
Accessible without login Plain text file composer.json Data Auxiliary data
Accessible without login Plain text file LICENSE Lic. License text
Accessible without login Plain text file phpstan.neon Data Auxiliary data
Accessible without login Plain text file phpunit.xml Data Auxiliary data
Accessible without login Plain text file psalm.xml Data Auxiliary data
Accessible without login Plain text file README.md Doc. Documentation

  Files folder image Files (41)  /  .github  
File Role Description
  Accessible without login Plain text file CONTRIBUTING.md Data Auxiliary data
  Accessible without login Plain text file FUNDING.yml Data Auxiliary data
  Accessible without login Plain text file ISSUE_TEMPLATE.md Data Auxiliary data
  Accessible without login Plain text file PULL_REQUEST_TEMPLATE.md Data Auxiliary data

  Files folder image Files (41)  /  .phive  
File Role Description
  Accessible without login Plain text file phars.xml Data Auxiliary data

  Files folder image Files (41)  /  bin  
File Role Description
  Accessible without login Plain text file phpdoctor Data Auxiliary data
  Accessible without login Plain text file phpdoctor.php Example Example script

  Files folder image Files (41)  /  src  
File Role Description
Files folder imagevoku (1 directory)

  Files folder image Files (41)  /  src  /  voku  
File Role Description
Files folder imagePHPDoctor (2 directories)

  Files folder image Files (41)  /  src  /  voku  /  PHPDoctor  
File Role Description
Files folder imageCliCommand (1 file)
Files folder imagePhpDocCheck (4 files)

  Files folder image Files (41)  /  src  /  voku  /  PHPDoctor  /  CliCommand  
File Role Description
  Plain text file PhpDoctorCommand.php Class Class source

  Files folder image Files (41)  /  src  /  voku  /  PHPDoctor  /  PhpDocCheck  
File Role Description
  Plain text file CheckClasses.php Class Class source
  Plain text file CheckFunctions.php Class Class source
  Plain text file CheckPhpDocType.php Class Class source
  Plain text file PhpCodeChecker.php Class Class source

  Files folder image Files (41)  /  tests  
File Role Description
  Accessible without login Plain text file bootstrap.php Aux. Auxiliary script
  Plain text file CheckerTest.php Class Class source
  Plain text file Dummy.php Class Class source
  Plain text file Dummy2.php Class Class source
  Plain text file Dummy3.php Class Class source
  Plain text file Dummy4.php Class Class source
  Plain text file Dummy5.php Class Class source
  Plain text file Dummy6.php Class Class source
  Plain text file Dummy7.php Class Class source
  Plain text file Dummy8.php Class Class source
  Plain text file Dummy9.php Class Class source
  Plain text file DummyInterface.php Class Class source
  Plain text file DummyInterface2.php Class Class source
  Plain text file DummyInterface3.php Class Class source
  Plain text file DummyTrait.php Class Class source

The PHP Classes site has supported package installation using the Composer tool since 2013, as you may verify by reading this instructions page.
Install with Composer Install with Composer
 Version Control Unique User Downloads Download Rankings  
 100%
Total:65
This week:0
All time:10,389
This week:560Up