Phpqa Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer global require edgedesign/phpqa
   

   Or add to project:

   composer require --dev edgedesign/phpqa
   

2. First Run (analyze entire project):

   phpqa
   

   Outputs default analysis (PSR1/PSR2, PHPStan, PHPMD, etc.) with combined results.

3. Quick Check (focused on critical issues):

   phpqa --severity=critical
   

Where to Look First

• Default Config: ~/.phpqa.php (global) or .phpqa.php (project-specific).
• Tool Configs: Located in ~/.phpqa/tools/ (e.g., phpstan.neon, phpmd.xml).
• CLI Help:

  phpqa --help
  

First Use Case

Run a pre-commit hook to block critical issues:

phpqa --severity=critical --format=json --output=phpqa-results.json

Then integrate with Git hooks (e.g., pre-commit) to fail if phpqa-results.json contains errors.

Implementation Patterns

Workflows

1. Project-Wide Analysis

   phpqa --exclude=tests,vendor --format=github
   

   • Use --exclude to skip non-code directories (e.g., vendor, tests).
   • --format=github for PR-friendly output (works with GitHub Actions).

2. Per-Directory Analysis

   phpqa src/ --tools=phpstan,psalm
   

   • Target specific paths (e.g., src/, modules/).
   • Customize tools per directory (e.g., stricter PHPStan for src/).

3. CI/CD Integration

   # .github/workflows/phpqa.yml
   jobs:
     phpqa:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - run: composer install
         - run: phpqa --severity=critical --format=github
   

   • Fail the build on critical issues with --severity=critical.
   • Use --format=github for native GitHub annotations.

4. Custom Configs Create .phpqa.php in your project:

   return [
       'tools' => [
           'phpstan' => [
               'level' => 5,
               'configuration' => 'phpstan.neon',
           ],
           'psalm' => [
               'config' => 'psalm.xml',
           ],
       ],
       'exclude' => ['tests', 'vendor', 'node_modules'],
   ];
   

Integration Tips

• Symfony Projects: Exclude var/ and vendor/ by default:

  phpqa --exclude=var,vendor
  

• Monorepos: Analyze multiple apps in one command:

  phpqa app1/ app2/ --tools=phpstan,phpmd
  

• Parallelization: Use parallel-lint or pct alongside PHPQA for faster feedback.
• Caching: Leverage PHPStan/Psalm caches for repeated runs:

  phpqa --cache-results
  

Gotchas and Tips

Pitfalls

1. Tool Conflicts

   • PHPStan and Psalm may report overlapping issues. Use --tools=phpstan or --tools=psalm explicitly to avoid redundancy.
   • Fix: Configure .phpqa.php to prioritize one tool:

     'tools' => ['phpstan' => ['level' => 5], 'psalm' => ['enabled' => false]],
     

2. XSL Extension Missing

   • HTML reports require the xsl extension. Install it via:

     pecl install xsl
     

   • Alternative: Use --format=text or --format=json if HTML isn’t critical.

3. Slow Initial Runs

   • PHPStan/Psalm generate caches on first run. Speed up subsequent runs with:

     phpqa --cache-results
     

   • Tip: Pre-generate caches in CI to avoid slow first runs.

4. False Positives

   • Tools like PHPMD may flag legacy code. Suppress noise with:

     phpqa --severity=high,critical
     

   • Tip: Use --ignore-errors to skip known issues temporarily.

5. Config Overrides

   • Project-specific .phpqa.php overrides global ~/.phpqa.php. Test changes incrementally:

     phpqa --dry-run
     

Debugging

• Verbose Output:

  phpqa -vvv
  

  Reveals tool-specific logs (e.g., PHPStan’s error details).

• Tool-Specific Debugging:

  phpqa --tools=phpstan --debug
  

  Shows raw PHPStan output for troubleshooting.

• Check Config Validity:

  phpqa --validate-config
  

  Validates .phpqa.php syntax before running.

Extension Points

1. Custom Tools Extend PHPQA by adding new tools. Example for custom-tool:

   // ~/.phpqa/tools/custom-tool.php
   return [
       'command' => 'vendor/bin/custom-tool analyze {path}',
       'severity_map' => ['error' => 'critical', 'warning' => 'major'],
   ];
   

   Then run:

   phpqa --tools=custom-tool
   

2. Post-Analysis Scripts Use --output to generate machine-readable results, then process with a script:

   phpqa --format=json --output=results.json
   php process-results.php results.json
   

3. GitHub Actions Annotations Combine with phpqa to highlight issues in PRs:

   - run: |
       phpqa --format=github > phpqa-annotations
       cat phpqa-annotations >> $GITHUB_STEP_SUMMARY
   

4. Dynamic Excludes Use environment variables for dynamic paths:

   phpqa --exclude="tests,${CI_BUILD_DIR}/temp"