Phpquality Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require amoifr/phpquality-bundle
   

   Register the bundle in config/bundles.php:

   PhpQuality\PhpQualityBundle::class => ['all' => true],
   

2. First Analysis:

   php bin/console phpquality:analyze --source=src/ --type=laravel
   

   • Replace src/ with your project's source directory.
   • Use --type=laravel (or another framework type) for framework-specific rules.

3. View Reports:

   • HTML reports are generated in var/reports/ by default.
   • Open var/reports/index.html in a browser for an interactive dashboard.

First Use Case: Pre-Commit Hook

Add this to your .git/hooks/pre-commit (or use a tool like husky):

#!/bin/sh
php bin/console phpquality:analyze --source=src/ --type=laravel --no-html --fail-on-violation

• Fails the commit if new violations are introduced (excluding baseline violations).

Implementation Patterns

Daily Workflow

1. Run Analysis:

   php bin/console phpquality:analyze --source=src/ --type=laravel --report-html=reports/
   

   • Use --type=laravel for Laravel-specific layer rules (e.g., ServiceProvider → Wiring layer).

2. Review Violations:

   • Focus on the "Analysis" → "Violations" tab in the HTML report.
   • Prioritize:
     • Architecture violations (layer dependency rules).
     • SOLID violations (e.g., solid.dip for concrete dependencies).
     • Complexity spikes (CCN > 10 or MI < 65).

3. Fix Iteratively:

   • Use @phpquality-ignore annotations for temporary suppressions:

     /**
      * @phpquality-ignore solid.dip -- Legacy dependency
      */
     class LegacyService {}
     

   • Refactor classes with high LCOM (e.g., split into smaller classes).

4. Baseline Management:

   • Generate a baseline for your team’s codebase:

     php bin/console phpquality:analyze --source=src/ --generate-baseline=phpquality.baseline.json
     

   • Commit phpquality.baseline.json to track accepted violations.
   • Run future analyses with:

     php bin/console phpquality:analyze --source=src/ --baseline=phpquality.baseline.json
     

Integration Tips

1. CI Pipeline:

   • Fail builds on new violations (excluding baseline):

     # GitHub Actions example
     - name: Run PhpQuality
       run: php bin/console phpquality:analyze --source=src/ --baseline=phpquality.baseline.json --fail-on-violation
     

2. Custom Rules:

   • Extend phpquality.json to override defaults:

     {
       "layers": {
         "rules": [
           { "match": "App\\Services\\**", "layer": "Application" }
         ]
       },
       "ignore": {
         "violations": ["solid.dip:App\\Legacy\\*"]
       }
     }
     

3. Test Coverage:

   • Integrate with PHPUnit’s Clover output:

     ./vendor/bin/phpunit --coverage-clover=coverage.xml
     php bin/console phpquality:analyze --source=src/ --coverage=coverage.xml
     

4. Dockerized Analysis:

   • Use the Docker image for consistency across environments:

     docker run --rm -v $(pwd):/project amoifr13/phpquality --source=/project/src --type=laravel --report-html=/project/reports
     

5. Layer-Specific Focus:

   • Target specific layers for deep dives:

     php bin/console phpquality:analyze --source=src/ --type=laravel --layers=Domain,Infrastructure
     

Gotchas and Tips

Pitfalls

1. False Positives in Framework Projects:

   • Laravel’s ServiceProvider is auto-categorized as Wiring (exempt from layer violations).
   • Eloquent models are excluded from DIP calculations by default.
   • Fix: Verify --type=laravel is used; adjust phpquality.json if needed.

2. Baseline Drift:

   • Frequent baseline updates can hide real issues.
   • Tip: Review baseline changes in PRs and document why violations are accepted.

3. Performance:

   • Git blame (--git-blame) is slow on large repos.
   • Tip: Run it nightly via CI, not pre-commit.

4. Complexity Thresholds:

   • Default thresholds (e.g., CCN > 10) may be too strict for legacy code.
   • Tip: Use --generate-baseline to calibrate thresholds to your codebase.

5. Docker Volume Mounts:

   • Forgetting to mount reports directory in Docker:

     # Missing: -v $(pwd)/reports:/reports
     docker run --rm -v $(pwd):/project amoifr13/phpquality --source=/project/src
     

   • Fix: Always include volume mounts for reports.

Debugging

1. Silent Failures:

   • Add --verbose to debug:

     php bin/console phpquality:analyze --source=src/ --verbose
     

2. Layer Misclassification:

   • Check phpquality.json or use --list-types to verify your framework’s preset.

3. Coverage Mismatches:

   • Ensure PHPUnit’s Clover file path is correct and matches the analysis source directory.

4. JSON vs. HTML Reports:

   • JSON reports (--json=report.json) are useful for programmatic access but lack visualization.
   • Tip: Use both for CI (JSON) and local review (HTML).

Extension Points

1. Custom Metrics:

   • Extend PhpQuality\Analyzer\Result\MetricCollection to add project-specific metrics.

2. Report Templates:

   • Override Twig templates in templates/report/ to customize the HTML layout.

3. CLI Commands:

   • Subclass PhpQuality\Command\AnalyzeCommand to add custom analysis logic.

4. Project Types:

   • Add a new framework preset by extending PhpQuality\Analyzer\ProjectType\ProjectTypeInterface.

5. Violation Handlers:

   • Implement PhpQuality\Analyzer\ViolationHandlerInterface to customize violation processing (e.g., slack notifications).

Pro Tips

• Pair with PHPStan/Psalm: Combine with static analyzers for a layered quality check:

  ./vendor/bin/phpstan analyse --level=max
  php bin/console phpquality:analyze --source=src/
  

• Track Metrics Over Time: Use the JSON output to log metrics in a database and visualize trends (e.g., MI score per sprint).

• Onboarding New Devs: Point them to the "Documentation" tab in the HTML report to explain metrics like CCN and LCOM.

• Exclude Tests: Add tests to --exclude to avoid analyzing them:

  php bin/console phpquality:analyze --source=src/ --exclude=tests/
  

• Architecture Score Targets: Aim for an Architecture Score > 70 (B rating) for maintainable projects. Use the dependency graph to identify circular dependencies.