Phpqa Laravel Package

Technical Evaluation

Architecture Fit

• Unified Code Analysis: phpqa consolidates multiple PHP analyzers (e.g., PHP_CodeSniffer, PHPStan, Psalm, etc.) into a single CLI tool, reducing toolchain complexity. This aligns well with Laravel’s ecosystem, where developers often juggle multiple static analysis tools (e.g., phpstan, psalm, pint).
• Laravel-Specific Use Cases:
  • Bundle/Module Isolation: Ideal for analyzing individual Laravel modules (e.g., app/Modules/*) without per-module CI/CD configurations.
  • CI/CD Integration: Simplifies Jenkins/GitHub Actions workflows by replacing ad-hoc analyzer commands with a single phpqa invocation.
  • Legacy Codebases: Useful for Laravel 5.x/6.x projects where tooling fragmentation is common.
• Output Flexibility: Supports HTML, JSON, and CLI formats, enabling integration with Laravel’s testing suites (e.g., PestPHP) or IDE plugins (e.g., PHPStorm inspections).

Integration Feasibility

• Low Friction: No Laravel-specific dependencies; integrates via Composer (composer require edgedesign/phpqa).
• Configuration Override: Can extend Laravel’s existing phpstan.neon/psalm.xml files by leveraging phpqa's --config flag to merge settings.
• Artisan Command Wrapper: Potential to create a custom Artisan command (e.g., php artisan phpqa:run) to standardize usage across teams.
• Dependency Conflicts: Risk of version mismatches with Laravel’s bundled tools (e.g., PHP_CodeSniffer). Mitigated by phpqa's explicit version pinning in its composer.json.

Technical Risk

• PHP 5.4+ Constraint: Laravel 10+ requires PHP 8.1+. While phpqa supports modern PHP, older Laravel projects may need polyfills or forks.
• XSL Extension for HTML Reports: Non-critical but may require Docker/containerized environments for CI pipelines lacking the xsl extension.
• Toolchain Overlap: Potential redundancy with Laravel’s built-in tools (e.g., php artisan test --testdox-html). Requires clear documentation on when to use phpqa vs. native tools.
• Custom Rules: Limited support for Laravel-specific rules (e.g., Eloquent query validation). May need to combine with phpstan extensions.

Key Questions

1. Toolchain Standardization:
   • Should phpqa replace or complement existing analyzers (e.g., phpstan:baseline, pint)?
   • How will rule conflicts (e.g., phpstan vs. phpcs) be resolved?
2. Performance:
   • What’s the overhead of running phpqa vs. individual tools in CI? (Benchmark with Laravel’s monorepo structure.)
3. Developer Adoption:
   • How will teams transition from ad-hoc analyzer commands to phpqa?
   • Should phpqa be enforced via composer.json scripts (e.g., scripts.lint)?
4. Laravel-Specific Gaps:
   • Are there critical Laravel patterns (e.g., service containers, Blade templates) not covered by phpqa's default analyzers?
5. CI/CD Impact:
   • How will phpqa integrate with Laravel’s phpunit.xml or php-cs-fixer.dist.php configurations?

Integration Approach

Stack Fit

• Composer Ecosystem: Seamless integration via Packagist. No Laravel-specific bootstrapping required.
• CI/CD Pipelines:
  • GitHub Actions: Replace multi-step analyzer jobs with a single phpqa step.

    - name: Run PHPQA
      run: vendor/bin/phpqa analyze --format=github --config=.phpqa.php
    

  • Jenkins: Use the execute shell plugin to run phpqa with custom ignore patterns (e.g., ./vendor, ./storage).
• IDE/Editor:
  • PHPStorm: Configure phpqa as an external tool for on-save analysis.
  • VSCode: Use the PHP Intelephense extension to parse phpqa JSON output.
• Local Development:
  • Add to composer.json scripts:

    "scripts": {
      "lint": "phpqa analyze --format=cli",
      "lint:fix": "phpqa fix"
    }
    

Migration Path

1. Pilot Phase:
   • Run phpqa in parallel with existing tools to validate output parity.
   • Focus on high-impact modules (e.g., app/Http/Controllers).
2. Configuration Alignment:
   • Map Laravel’s phpstan.neon to phpqa's YAML/JSON config:

     # .phpqa.yaml
     analyze:
       directories: [app, config]
       ignore:
         - "app/Providers/AppServiceProvider.php" # Example override
       tools:
         phpstan:
           level: 8
           configuration: phpstan.neon
     

3. Phased Rollout:
   • Phase 1: Replace phpcs/phpmd with phpqa.
   • Phase 2: Add phpstan/psalm via phpqa config.
   • Phase 3: Deprecate individual analyzer commands in CI.

Compatibility

• Laravel Artisan: No direct integration, but can wrap phpqa in a custom command:

  // app/Console/Commands/RunPHPQA.php
  public function handle() {
      $exitCode = \Edgedesign\PHPQA\Application::run([
          'command' => 'analyze',
          'format' => 'cli',
          '--config' => base_path('.phpqa.php'),
      ]);
      exit($exitCode);
  }
  

• Service Providers: Not required, but can register phpqa paths in Laravel’s app config.
• Testing: Use phpqa in phpunit.xml as an external tool for pre-test analysis:

  <php>
      <listenFor>beforeTestSuite</listenFor>
      <command>vendor/bin/phpqa analyze --format=cli --exit-on-fail</command>
  </php>
  

Sequencing

1. Pre-Analysis:
   • Run phpqa fix (if using pint/php-cs-fixer) before analyze.
2. CI Pipeline Order:
   • composer install → phpqa analyze → phpunit → deploy.
3. Post-Deployment:
   • Use phpqa in deployment hooks to validate production-like environments.

Operational Impact

Maintenance

• Configuration Drift: Centralized config (e.g., .phpqa.yaml) reduces maintenance overhead vs. per-tool configs.
• Tool Updates:
  • phpqa abstracts analyzer versioning. Update via composer update edgedesign/phpqa.
  • Risk: Breaking changes in underlying tools (e.g., PHPStan 1.0 → 2.0). Mitigate with phpqa's config validation.
• Deprecation:
  • Plan to sunset individual analyzer commands (e.g., phpstan) after phpqa adoption.

Support

• Troubleshooting:
  • Debug with --debug flag. Logs can be directed to Laravel’s storage/logs/phpqa.log.
  • Use phpqa --help for tool-specific options (e.g., phpstan:rules).
• Onboarding:
  • Document phpqa in Laravel’s CONTRIBUTING.md alongside phpunit/pint.
  • Provide a cheat sheet for common commands (e.g., phpqa analyze app --format=html).
• Community:
  • Leverage phpqa's GitHub issues for support; escalate Laravel-specific bugs to the package maintainers.

Scaling

• Large Codebases:
  • Parallelize analysis with --jobs=N (if supported by underlying tools).
  • Cache results using Laravel’s cache:remember in a custom Artisan command.
• Distributed Teams:
  • Enforce phpqa via composer.json scripts to ensure consistency.
  • Use phpqa in pre-commit hooks (e.g., with husky) for local enforcement.
• Performance:
  • Benchmark phpqa vs. individual tools for Laravel’s monorepo structure (e.g., modules/*).
  • Consider splitting analysis by directory in CI to reduce timeout risks.

Failure Modes