Skip to content

About

Health-audit CLI for Symfony 6/7/8 and Laravel 10/11/12/13. AST + runtime + PHPStan, Lighthouse-style scored HTML report.

Topics

Resources

Security policy

Stars

1 star

Watchers

0 watching

Forks

Latest commit

Β 

History

24 Commits

Folders and files

Repository files navigation

php-doctor

Health-check & quality audit CLI for Symfony 6/7/8 and Laravel 10/11/12/13 projects. Inspired by react.doctor β€” gives your PHP project a Lighthouse-style scored report you actually want to read.

CI Compatibility License: MIT PHP 8.3+ PHPStan level 6 Release: v0.1.0

php-doctor scans a PHP project, cross-references its AST with the framework's runtime introspection (bin/console debug:*, php artisan route:list, composer audit), optionally consumes PHPStan's output, and emits a scored health report in Console / JSON / HTML / SARIF.

It is not another linter. It is an orchestrator that aggregates static analysis, framework-aware checks, and dependency security into a single number you can ship to CI or display in a browser.


Why php-doctor

Tool Scope What it tells you
PHPStan / Larastan Type-safety static analysis "This call will crash"
Rector Automated refactoring "Apply this transform"
Symfony Insight SaaS quality scoring "Pay us monthly"
php-doctor Project health audit "Your project scores 72/100 β€” here's why"

php-doctor is closest in spirit to Lighthouse for the web: a single command, an opinionated scored report, with drill-down explanations. It does not compete with PHPStan β€” it uses PHPStan when available and folds its findings into a Type safety category.


Quick start

# Install via PHAR (recommended)
curl -L -o php-doctor.phar https://github.com/dev-toolings/php-doctor/releases/latest/download/php-doctor.phar
chmod +x php-doctor.phar

# Scan any Symfony / Laravel / generic PHP project
./php-doctor.phar scan /path/to/project

# Generate the Lighthouse-style HTML report
./php-doctor.phar scan /path/to/project --format=html --output=report.html

# Use it in CI β€” exit non-zero below threshold
./php-doctor.phar scan . --ci --min-score=70

Features

🩺 Framework-aware analysis

Detects Symfony 6.4 / 7.x / 8.x and Laravel 10 / 11 / 12 / 13 automatically from composer.json, then runs the right pack of rules.

🌐 Runtime introspection (the moat)

Goes beyond AST by parsing what your framework actually exposes at runtime:

  • Symfony: debug:router, debug:container, debug:event-dispatcher, debug:config (all via --format=json).
  • Laravel: route:list --json, about --json, migrate:status (text parser), php -r config dump.
  • Composer: composer audit --format=json for CVE detection.

πŸ“Š Lighthouse-style scoring

Every finding has a severity weight; categories are scored 0–100 and aggregated into a global score. Reports include a SVG dial, per-category cards, and per-finding drill-down.

πŸ”Œ PHPStan integration (optional but seamless)

If vendor/bin/phpstan exists in the audited project, it is invoked, its JSON output is parsed, and each message becomes a finding under the Type safety category. Absent β†’ category is N/A (does not penalize the score).

πŸ€– CI-ready

Native flags --ci, --min-score=N, --fail-on=<severity>. Reports in JSON v1 (stable schema) and SARIF 2.1.0 (works out of the box with GitHub Code Scanning).

πŸ“¦ Single-binary distribution

Built with Box into a ~2.5 MB PHAR. No global Composer install, no version conflicts with the audited project.


Supported framework matrix

Framework Versions Detection signal Runtime introspection
Symfony 6.4 LTS Β· 7.x Β· 8.x symfony/framework-bundle in composer.json bin/console debug:* --format=json
Laravel 10 Β· 11 Β· 12 Β· 13 laravel/framework in composer.json php artisan route:list --json, about --json, migrate:status text parser
Generic PHP n/a neither of the above composer audit --format=json only

Detection is version-agnostic β€” any constraint matching the package name is supported. The matrix is enforced by:


Usage

# Default human-readable console output with ANSI colors
php bin/php-doctor scan /path/to/project

# Machine-readable JSON (stable v1 schema)
php bin/php-doctor scan /path/to/project --format=json
php bin/php-doctor scan /path/to/project --format=json --output=report.json

# Self-contained Lighthouse-style HTML
php bin/php-doctor scan /path/to/project --format=html --output=report.html

# SARIF 2.1.0 β€” direct upload to GitHub Code Scanning
php bin/php-doctor scan /path/to/project --format=sarif --output=results.sarif

# CI mode β€” exit 1 if global score < 70
php bin/php-doctor scan /path/to/project --ci --min-score=70

# CI mode β€” exit 1 on any high-or-above finding
php bin/php-doctor scan /path/to/project --ci --fail-on=high

# Inventory rules
php bin/php-doctor list-rules

Built-in rules (MVP)

ID Category Severity Frameworks
common.security.hardcoded-secrets Security Critical All
common.hygiene.env-desync Hygiene Medium All
common.dependencies.composer-audit Dependencies High (variable per advisory) All
symfony.security.missing-is-granted Security High Symfony
symfony.architecture.orphan-route Architecture Low Symfony
laravel.perf.eloquent-n-plus-one Performance High Laravel
laravel.security.mass-assignment Security High Laravel
laravel.architecture.blade-business-logic Architecture Medium Laravel
phpstan.* (1 per identifier) Type safety Mapped from PHPStan severity Any (when PHPStan installed)

Use cases

As a PR check

# .github/workflows/quality.yml
- run: ./php-doctor.phar scan . --ci --min-score=80

As a SARIF feed for GitHub Code Scanning

- run: ./php-doctor.phar scan . --format=sarif --output=results.sarif
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif

As a local pre-commit gate

./php-doctor.phar scan . --ci --fail-on=critical

As a quarterly architecture audit

./php-doctor.phar scan . --format=html --output=audit-q1.html

FAQ

Is this a replacement for PHPStan / Larastan?

No. PHPStan/Larastan answer "will my code crash?". php-doctor answers "is my project healthy?". They run together β€” php-doctor invokes PHPStan if installed and aggregates its findings into the Type safety category.

How is the score computed?

Each finding has a severity weight (Critical=20, High=10, Medium=5, Low=2, Info=0). For each category: score = clamp(100 - 0.5 Γ— Ξ£ weights, 0, 100). Global score = arithmetic mean across the 6 categories. Categories with zero findings stay at 100. PHPStan absent β†’ Type safety is N/A (excluded from the mean).

Does it execute my application code?

No. php-doctor only invokes the framework's official introspection commands (bin/console debug:*, php artisan route:list). The single exception is the Laravel config workaround (php -r that boots the app), required because config:show --json does not exist in any Laravel 10–13. That command runs in the project root with the project's own .env β€” never against production.

Can I add custom rules?

The MVP ships rules in-tree (no plugin loader). A plugin system is on the roadmap once the core stabilizes. For now, fork or open a PR.

Does it work on Windows?

Untested. The PHAR should run anywhere PHP runs, but the runtime collectors shell out to bin/console and php artisan β€” paths and quoting are POSIX-first. Reports of Windows runs welcome.

How fast is it?

On the embedded symfony-min test fixture: 357 ms Β± 7 ms (hyperfine). On a 500-file real project: target < 10 s, not yet measured publicly.


Known limitations

  • EloquentNPlusOne is heuristic (AST-based). False positives possible when the eager loading is not on the same expression as the foreach.
  • Laravel config introspection uses a php -r workaround that boots the app β€” needs a usable .env.
  • MissingIsGranted assumes PSR-4 (App\Controller\… β†’ src/Controller/…). Controllers in non-standard locations are silently skipped.
  • Type safety is N/A (not 0) when PHPStan is absent β€” the audited project must composer require --dev phpstan/phpstan and composer install.
  • Symfony 8 / Laravel 13 matrix entries are forward-looking β€” the CI matrix gracefully skips entries whose skeleton is not yet released on Packagist.

Architecture (high-level)

ScanCommand
   β”œβ”€β”€ ProjectDetector     β†’ FrameworkContext (Symfony | Laravel | Generic)
   β”œβ”€β”€ AST pipeline         β†’ ParserPool Β· FileWalker Β· AstSnapshot Β· NameResolver
   β”œβ”€β”€ Runtime pipeline     β†’ ProcessExecutor Β· 12 collectors Β· SnapshotBuilder
   β”œβ”€β”€ PhpStanRunner        β†’ consumes vendor/bin/phpstan output (if present)
   β”œβ”€β”€ RuleRegistry         β†’ 8 in-tree rules + PhpStan aggregator
   └── Reporter             β†’ Console Β· JSON Β· HTML Β· SARIF

Full blueprint: docs/plans/PLAN-php-doctor-mvp.md.


Contributing

git clone https://github.com/dev-toolings/php-doctor.git
cd php-doctor
composer install

composer test                  # 170 tests
composer build                 # PHAR β†’ build/php-doctor.phar
vendor/bin/phpstan analyse     # level 6, 0 errors required

Conventions :

  • PHP 8.3 minimum, strict types everywhere, final readonly by default.
  • Each new rule = 1 file in src/Rules/.../*.php + 1 test file with at least 1 positive and 1 negative case.
  • No new framework-aware rule without updating the supported matrix and the compat workflow.

Credits & license

MIT β€” see LICENSE. Β© 2026 Kevin (MakFly).


Tags: php Β· symfony Β· laravel Β· static analysis Β· code quality Β· health check Β· audit Β· phpstan Β· lighthouse Β· sarif Β· cli tool Β· php-cli Β· symfony-bundle Β· laravel-package Β· ast Β· composer-audit

About

Health-audit CLI for Symfony 6/7/8 and Laravel 10/11/12/13. AST + runtime + PHPStan, Lighthouse-style scored HTML report.

Topics

Resources

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages