README

Validates PHPDoc @param and @return tags against method signatures using AST parsing.

Features

Type compatibility checking — Understands PHPDoc-specific types like list<T>, class-string<T>, positive-int
Result caching — Dramatically speeds up incremental runs.
Multiple output formats — Pretty CLI output, JSON for tooling, GitHub Actions annotations, Checkstyle XML
CI-friendly — Exit codes for easy integration into build pipelines
Flexible scanning — Scan directories or individual files with glob-based exclusions

Installation

composer require --dev nsrosenqvist/phpdoc-validator

Usage

Basic Usage

# Scan the src/ directory
vendor/bin/phpdoc-validator src/

# Scan multiple paths
vendor/bin/phpdoc-validator src/ lib/ app/

# Scan with exclusions
vendor/bin/phpdoc-validator src/ --exclude="*Test.php" --exclude="*/fixtures/*"

Output Formats

# Pretty output (default)
vendor/bin/phpdoc-validator src/ --format=pretty

# JSON for tooling
vendor/bin/phpdoc-validator src/ --format=json

# GitHub Actions annotations
vendor/bin/phpdoc-validator src/ --format=github

# Checkstyle XML (for CI tools like Jenkins, GitLab CI, etc.)
vendor/bin/phpdoc-validator src/ --format=checkstyle

Options

Option	Short	Description
`--format`	`-f`	Output format: `pretty`, `json`, `github`, `checkstyle`
`--no-color`		Disable colored output
`--exclude`	`-e`	Patterns to exclude (can be used multiple times)
`--missing`	`-m`	Also report missing `@param` and `@return` documentation
`--fix`		Automatically fix issues (see Auto-fixing)
`--no-cache`		Disable result caching
`--clear-cache`		Clear the cache before running validation
`--cache-file`		Path to the cache file (default: `.phpdoc-validator.cache`)
`--cache-mode`		Cache invalidation mode: `hash` (default) or `mtime`

Exit Codes

Code	Meaning
0	No issues found
1	Issues were found
2	An error occurred

What It Checks

By default, PHPDoc Validator reports:

Extra @param tags — Documentation for parameters that don't exist in the method signature
Type mismatches — Documented types that don't match the signature types (both @param and @return)
Return type mismatches — @return types that don't match the method's return type signature

With --missing, it also reports:

Missing @param tags — Parameters in the signature that lack documentation
Missing @return tags — Methods with return types that lack @return documentation

Additionally, it always checks for:

Parameter order — @param tags that don't match the order of parameters in the signature

Auto-fixing

PHPDoc Validator can automatically fix certain issues:

# Fix param order issues
vendor/bin/phpdoc-validator src/ --fix

# Also add missing @param and @return tags
vendor/bin/phpdoc-validator src/ --fix --missing

What Can Be Fixed

Issue	`--fix`	`--fix --missing`
Parameter order	✓	✓
Missing `@param`		✓
Missing `@return`		✓
Type mismatches
Extra params

Type mismatches and extra params cannot be auto-fixed because the PHPDoc often contains more specific type information than the native PHP signature.

Type Compatibility

The validator understands that certain PHPDoc types are compatible with PHP native types:

PHP Type	Compatible PHPDoc Types
`array`	`list<T>`, `non-empty-array<T>`, `array<K, V>`
`string`	`class-string<T>`, `numeric-string`, `callable-string`
`int`	`positive-int`, `negative-int`, `non-negative-int`
`callable`	`Closure`, `callable-string`
`iterable`	`iterable<T>`

Example Output

Pretty Format

PHPDoc Parameter Validation Report
============================================

src/UserService.php:42
   Method: UserService::createUser()
   [X]  Extra @param $role not in method signature
   [!]  Type mismatch for $email: signature has 'string', doc has 'int'

Summary:
  Files scanned: 15
  Files with issues: 1
  Total issues: 2

GitHub Actions Format

::error file=src/UserService.php,line=42,title=Extra @param::Extra @param $role not in method signature
::error file=src/UserService.php,line=42,title=Type mismatch::Type mismatch for $email: signature has 'string', doc has 'int'

Checkstyle Format

<?xml version="1.0" encoding="UTF-8"?>
<checkstyle version="4.3">
  <file name="src/UserService.php">
    <error line="42" severity="error" message="Extra @param $role not in method signature" source="phpdoc-validator.extra_param"/>
    <error line="42" severity="error" message="Type mismatch for $email: signature has 'string', doc has 'int'" source="phpdoc-validator.type_mismatch"/>
  </file>
</checkstyle>

Caching

PHPDoc Validator caches validation results to dramatically speed up incremental runs. On subsequent runs, only files that have changed since the last validation are re-parsed.

# First run: validates all files and creates cache
vendor/bin/phpdoc-validator src/

# Second run: uses cache, only validates changed files
vendor/bin/phpdoc-validator src/

# Disable caching
vendor/bin/phpdoc-validator src/ --no-cache

# Clear cache before running
vendor/bin/phpdoc-validator src/ --clear-cache

Cache Modes

Mode	Description
`hash`	Uses SHA-256 content hash (default, most reliable)
`mtime`	Uses file modification time (faster but can miss changes after git operations)

The cache is stored in .phpdoc-validator.cache by default. Add this file to your .gitignore.

The cache automatically invalidates when:

The validator version changes
The PHP version changes
The --missing flag setting changes

CI Integration

GitHub Actions

- name: Validate PHPDoc
  run: vendor/bin/phpdoc-validator src/ --format=github

GitLab CI

phpdoc:
  script:
    - vendor/bin/phpdoc-validator src/ --format=checkstyle > phpdoc-report.xml
  artifacts:
    reports:
      codequality: phpdoc-report.xml

Jenkins / Generic CI

vendor/bin/phpdoc-validator src/ --format=checkstyle > phpdoc-report.xml

The Checkstyle XML format is supported by most CI platforms and code quality tools.

Development

# Install dependencies
composer install

# Run tests
composer test

# Run static analysis
composer analyze

# Fix code style
composer format

# Run all checks
composer check

License

MIT License. See LICENSE for details.

nsrosenqvist / phpdoc-validator

Maintainers

Package info

Statistics

Security