Phpquality Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Symfony Bundle vs. Laravel: The package is designed as a Symfony bundle, but Laravel projects can leverage it via Docker or CLI. The Laravel-specific preset (--type=laravel) reclassifies components (e.g., *Action → Application, ServiceProvider → Wiring) to align with Laravel’s architecture.
• Modularity: The tool’s layered architecture (AST parsing, analysis, reporting) allows integration without monolithic refactoring. Key components like ProjectAnalyzer and HtmlReportGenerator can be extended or replaced.
• Laravel Compatibility: The --type=laravel flag adapts analysis to Laravel’s conventions (e.g., excluding Eloquent/Carbon from DIP violations). However, custom logic (e.g., Facade dependencies) may require phpquality.json overrides.

Integration Feasibility

• Low-Coupling: The bundle injects analysis as a CLI command (phpquality:analyze), avoiding runtime overhead. Reports are generated post-deployment.
• Dependency Conflicts: Risk of version mismatches with nikic/php-parser (PHP 8.3+) or Symfony components. Test in a staging environment first.
• Laravel-Specific Gaps: No native Laravel service provider or Artisan command integration. Workarounds:
  • Use Docker for CI/CD.
  • Create a custom Artisan command wrapping the CLI tool.
  • Extend the bundle’s ProjectType to add Laravel-specific exclusions.

Technical Risk

Key Questions

1. Prioritization:
   • Should architecture violations (e.g., Domain → Infrastructure) block PRs, or are they triaged via baselines?
2. Toolchain Fit:
   • Does the team prefer CLI (Symfony bundle) or Docker for analysis? Docker simplifies Laravel integration.
3. Custom Metrics:
   • Are Laravel-specific metrics (e.g., Job queue complexity) needed beyond the default preset?
4. CI/CD Workflow:
   • Should reports be published as artifacts (e.g., GitHub Actions) or linked to PR comments?
5. Maintenance:
   • Who will update phpquality.json as Laravel evolves (e.g., new Facade patterns)?

Integration Approach

Stack Fit

• Laravel Compatibility:
  • Docker: Recommended for CI/CD (avoids PHP/Symfony dependencies). Example:

    # GitHub Actions
    - name: Run PhpQuality
      run: docker run --rm -v ${{ github.workspace }}:/project amoifr13/phpquality --source=/project/app --type=laravel --report-html=/tmp/reports
    

  • CLI: Requires PHP 8.3+ and Symfony components. Install via Composer:

    composer require amoifr/phpquality-bundle
    

    Then register the bundle in config/bundles.php (even if unused, for dependency injection).
• Artisan Integration:
  • Create a custom command:

    // app/Console/Commands/PhpQualityCommand.php
    class PhpQualityCommand extends Command {
        protected $signature = 'phpquality:run {--source=app : Source directory}';
        public function handle() {
            $source = $this->option('source');
            shell_exec("php bin/console phpquality:analyze --source=$source --type=laravel");
        }
    }
    

• Reporting:
  • HTML reports can be served via Laravel’s Storage facade or published to a /reports route.

Migration Path

1. Pilot Phase:
   • Run analysis on a single module (e.g., app/Http/Controllers) with --generate-baseline.
   • Validate false positives in phpquality.baseline.json.
2. Gradual Rollout:
   • Add --baseline to CI checks for new violations only.
   • Integrate Docker into CI pipelines (e.g., GitHub Actions, GitLab CI).
3. Full Adoption:
   • Extend phpquality.json for Laravel-specific rules (e.g., exclude App\Jobs\* from DIP).
   • Publish reports to Slack/Teams via webhooks or PR comments.

Compatibility

Sequencing

1. Pre-Analysis:
   • Configure phpquality.json to exclude Laravel-specific paths (e.g., storage/, bootstrap/).
   • Example:

     {
       "ignore": {
         "directories": ["app/Providers", "app/Exceptions"],
         "violations": ["solid.dip:App\\Jobs\\*"]
       }
     }
     

2. Initial Run:
   • Generate baseline:

     php bin/console phpquality:analyze --source=app --type=laravel --generate-baseline=phpquality.baseline.json
     

3. CI Integration:
   • Add to workflow:

     - name: PhpQuality
       run: php bin/console phpquality:analyze --source=app --type=laravel --baseline=phpquality.baseline.json --fail-on-violation
     

4. Post-Analysis:
   • Publish reports to /storage/app/public/reports or a CDN.
   • Link to reports in PR templates or Slack notifications.

Operational Impact

Maintenance

• Configuration Drift:
  • Risk: phpquality.json may become outdated as Laravel evolves (e.g., new Facade patterns).
  • Mitigation: Document rules in a CODE_QUALITY.md file and review annually.
• Bundle Updates:
  • Risk: Symfony 7.x dependencies may conflict with Laravel’s PHP version.
  • Mitigation: Use Docker to isolate the tool or pin versions in composer.json.
• False Positives:
  • Risk: Laravel’s dynamic features (e.g., Facades, Magic Methods) trigger violations.
  • Mitigation: Extend the Laravel preset via phpquality.json or submit patches to the project.

Support

• Debugging:
  • CLI: Use --no-html for terminal output to debug issues.
  • Docker: Inspect logs with --entrypoint=bash for troubleshooting.
• Community:
  • Limited Activity: 3 stars, no dependents. Expect self-support or GitHub issues.
  • Workarounds: Fork the bundle to add Laravel-specific logic if needed.
• Documentation:
  • Gaps: Minimal Laravel-specific guidance. Supplement with:
    • Custom phpquality.json examples.
    • Internal runbooks for CI integration.

Scaling

• Performance:
  • Large Codebases: Exclude directories (e.g., --exclude=app/Providers) to reduce analysis time.
  • Parallelization: Run analysis in CI after tests to avoid timeouts.
• Reporting:
  • HTML Reports: Can grow large for big projects. Use --json for lightweight exports.
  • Archiving: Store reports in S3 or artifact repositories (e.g., GitHub Actions artifacts).
• Distributed Teams:
  • Baseline Management: Use a shared phpquality.baseline.json in the repo to standardize rules.
  • Report Access: Publish reports to a shared dashboard (e.g., via Laravel’s Storage + Nginx).

Failure Modes