PHPackages nsrosenqvist/phpdoc-validator - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Validation & Sanitization](/categories/validation) 4. / 5. nsrosenqvist/phpdoc-validator ActiveLibrary[Validation & Sanitization](/categories/validation) nsrosenqvist/phpdoc-validator ============================= Validates PHPDoc @param and @return tags against method signatures 1.2.0(2mo ago)01.1k↓33.8%MITPHPPHP ^8.2 Since Jan 22Pushed 2mo agoCompare [ Source](https://github.com/nsrosenqvist/phpdoc-validator)[ Packagist](https://packagist.org/packages/nsrosenqvist/phpdoc-validator)[ RSS](/packages/nsrosenqvist-phpdoc-validator/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (1)Dependencies (14)Versions (10)Used By (0) PHPDoc Validator ================ [](#phpdoc-validator) Validates PHPDoc `@param` and `@return` tags against method signatures using AST parsing. Features -------- [](#features) - **Type compatibility checking** — Understands PHPDoc-specific types like `list`, `class-string`, `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 ------------ [](#installation) ``` composer require --dev nsrosenqvist/phpdoc-validator ``` Usage ----- [](#usage) ### Basic 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 [](#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 [](#options) OptionShortDescription`--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](#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 [](#exit-codes) CodeMeaning0No issues found1Issues were found2An error occurredWhat It Checks -------------- [](#what-it-checks) By default, PHPDoc Validator reports: 1. **Extra @param tags** — Documentation for parameters that don't exist in the method signature 2. **Type mismatches** — Documented types that don't match the signature types (both `@param` and `@return`) 3. **Return type mismatches** — `@return` types that don't match the method's return type signature With `--missing`, it also reports: 4. **Missing @param tags** — Parameters in the signature that lack documentation 5. **Missing @return tags** — Methods with return types that lack `@return` documentation Additionally, it always checks for: 6. **Parameter order** — `@param` tags that don't match the order of parameters in the signature Auto-fixing ----------- [](#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 [](#what-can-be-fixed) Issue`--fix``--fix --missing`Parameter order✓✓Missing `@param`✓Missing `@return`✓Type mismatchesExtra paramsType mismatches and extra params cannot be auto-fixed because the PHPDoc often contains more specific type information than the native PHP signature. Type Compatibility ------------------ [](#type-compatibility) The validator understands that certain PHPDoc types are compatible with PHP native types: PHP TypeCompatible PHPDoc Types`array``list`, `non-empty-array`, `array``string``class-string`, `numeric-string`, `callable-string``int``positive-int`, `negative-int`, `non-negative-int``callable``Closure`, `callable-string``iterable``iterable`Example Output -------------- [](#example-output) ### Pretty Format [](#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 [](#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 [](#checkstyle-format) ``` ``` Caching ------- [](#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 [](#cache-modes) ModeDescription`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 -------------- [](#ci-integration) ### GitHub Actions [](#github-actions) ``` - name: Validate PHPDoc run: vendor/bin/phpdoc-validator src/ --format=github ``` ### GitLab CI [](#gitlab-ci) ``` phpdoc: script: - vendor/bin/phpdoc-validator src/ --format=checkstyle > phpdoc-report.xml artifacts: reports: codequality: phpdoc-report.xml ``` ### Jenkins / Generic CI [](#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 ----------- [](#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 ------- [](#license) MIT License. See [LICENSE](LICENSE) for details. ### Health Score 44 — FairBetter than 92% of packages Maintenance86 Actively maintained with recent releases Popularity20 Limited adoption so far Community6 Small or concentrated contributor base Maturity52 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~6 days Recently: every ~11 days Total 9 Last Release 69d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/bc4837ce5eb1f32142e8aefef1d53e10ae638fcff864e1c7c67c1e5b2b496e85?d=identicon)[nsrosenqvist](/maintainers/nsrosenqvist) --- Top Contributors [![nsrosenqvist](https://avatars.githubusercontent.com/u/1303475?v=4)](https://github.com/nsrosenqvist "nsrosenqvist (12 commits)") --- Tags phpdocPHPStanvalidatorstatic analysisdocumentationpsalm ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StylePHP CS Fixer Type Coverage Yes ### Embed Badge ![Health badge](/badges/nsrosenqvist-phpdoc-validator/health.svg) ``` [![Health](https://phpackages.com/badges/nsrosenqvist-phpdoc-validator/health.svg)](https://phpackages.com/packages/nsrosenqvist-phpdoc-validator) ``` ### Alternatives [vimeo/psalm A static analysis tool for finding errors in PHP applications 5.8k77.5M6.7k](/packages/vimeo-psalm)[behat/behat Scenario-oriented BDD framework for PHP 4.0k96.8M2.0k](/packages/behat-behat)[phpdocumentor/phpdocumentor Documentation Generator for PHP 4.4k3.1M878](/packages/phpdocumentor-phpdocumentor)[nelmio/api-doc-bundle Generates documentation for your REST API from attributes 2.3k63.6M233](/packages/nelmio-api-doc-bundle)[maglnet/composer-require-checker CLI tool to analyze composer dependencies and verify that no unknown symbols are used in the sources of a package 99810.9M671](/packages/maglnet-composer-require-checker)[phpdocumentor/reflection Reflection library to do Static Analysis for PHP Projects 12521.4M109](/packages/phpdocumentor-reflection) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)