Robo Phpstan Laravel Package

Technical Evaluation

Architecture Fit

• Static Analysis Integration: The package provides Robo tasks for PHPStan, a static analysis tool, making it a low-risk, high-value addition for Laravel projects where code quality, maintainability, and developer productivity are priorities.
• Task Automation: Aligns well with Laravel’s CLI-driven workflows (e.g., php artisan), enabling seamless integration into existing build pipelines (e.g., Git hooks, CI/CD).
• Extensibility: PHPStan is already a common dependency in Laravel ecosystems (via phpstan/extension-installer or standalone). This package abstracts repetitive PHPStan command execution, reducing boilerplate.

Integration Feasibility

• Minimal Dependencies: Requires only robo/robo and phpstan/phpstan, both widely adopted in PHP ecosystems.
• Laravel Compatibility: No Laravel-specific dependencies, but can be integrated via Composer and Robo’s task runner.
• Configuration Override: PHPStan’s configuration (.phpstan.neon) remains the single source of truth; this package merely wraps execution logic.

Technical Risk

• Low Risk:
  • No breaking changes to Laravel core or PHPStan’s core functionality.
  • Tasks are idempotent (e.g., phpstan:analyze) and can be tested in isolation.
• Edge Cases:
  • Custom PHPStan configurations (e.g., parallel analysis, custom rules) may require additional Robo task parameters.
  • Potential conflicts if multiple Robo tasks modify the same environment (e.g., autoloading).

Key Questions

1. Use Case Clarity:
   • Will this replace existing PHPStan CLI calls, or augment them (e.g., adding pre-commit checks)?
   • Does the team need custom PHPStan configurations (e.g., per-project rules)?
2. CI/CD Impact:
   • How will this integrate with existing pipelines (e.g., GitHub Actions, GitLab CI)?
   • Should tasks be gated (e.g., fail builds on errors) or advisory?
3. Developer Adoption:
   • Will teams need training on Robo task syntax (e.g., robo phpstan:analyze)?
   • Does the team already use Robo for other tasks (e.g., robo test)?
4. Performance:
   • Will PHPStan analysis slow down local development? (Mitigate with caching or parallel execution.)
5. Alternatives:
   • Is there a preference for native PHPStan CLI or other tools (e.g., Psalm, Pest)?

Integration Approach

Stack Fit

• Laravel + PHP Ecosystem:
  • Robo: Already used in Laravel for task automation (e.g., robo deploy, robo test).
  • PHPStan: Commonly integrated via Composer scripts or CI tools.
  • CI/CD: Seamless integration with tools like GitHub Actions (via robo commands).
• Non-Laravel Projects:
  • Useful for any PHP project using Robo, but Laravel’s CLI-centric workflow maximizes value.

Migration Path

1. Assessment Phase:
   • Audit existing PHPStan usage (e.g., composer exec phpstan analyze).
   • Identify gaps (e.g., missing pre-commit checks, parallel analysis).
2. Pilot Integration:
   • Add sweetchuck/robo-phpstan to composer.json dev dependencies.
   • Replace manual PHPStan commands with Robo tasks in robo.phar or Robofile.php.
   • Example:

     // Robofile.php
     $tasks->task('phpstan:analyze', \Sweetchuck\RoboPhpStan\Tasks\AnalyzeTask::class);
     

3. CI/CD Update:
   • Replace composer exec phpstan with ./vendor/bin/robo phpstan:analyze.
   • Add tasks to pre-commit hooks (e.g., Husky) or CI stages.
4. Gradual Rollout:
   • Start with advisory checks (exit code 0), then enforce failures in CI.

Compatibility

• PHPStan Version: Ensure compatibility with the Laravel project’s PHPStan version (e.g., PHPStan 1.x vs. 0.x).
• Robo Version: Requires Robo 3.x; check Laravel’s existing Robo usage.
• Configuration: PHPStan’s .neon file remains unchanged; tasks inherit its settings.

Sequencing

1. Pre-requisites:
   • Install PHPStan and Robo via Composer.
   • Configure PHPStan (.phpstan.neon).
2. Task Implementation:
   • Define Robo tasks in Robofile.php or a dedicated config file.
   • Example tasks:
     • phpstan:analyze (run analysis)
     • phpstan:check (exit on errors)
     • phpstan:parallel (parallel analysis)
3. Testing:
   • Validate tasks locally with ./vendor/bin/robo phpstan:analyze.
   • Test CI integration (e.g., GitHub Actions).
4. Documentation:
   • Add usage examples to team docs (e.g., robo phpstan:check --level=5).

Operational Impact

Maintenance

• Low Overhead:
  • No Laravel-specific maintenance; relies on PHPStan/Robo updates.
  • Tasks are self-contained and can be version-pinned.
• Dependency Management:
  • Monitor sweetchuck/robo-phpstan for updates (though low activity suggests stability).
  • Upgrade PHPStan/Robo as needed (test compatibility).

Support

• Troubleshooting:
  • Debugging focuses on PHPStan configuration or Robo task syntax.
  • Common issues:
    • Incorrect .neon paths (validate with phpstan:analyze --help).
    • Permission errors (ensure storage/ or bootstrap/cache/ writable).
• Fallback:
  • Revert to manual PHPStan CLI if tasks fail (e.g., composer exec phpstan analyze).

Scaling

• Performance:
  • PHPStan analysis scales with hardware (parallel execution recommended for large codebases).
  • Robo tasks are lightweight; overhead is minimal.
• Team Growth:
  • Standardizes analysis across developers, reducing "works on my machine" issues.
  • Enables consistent enforcement (e.g., level 5 checks in CI).

Failure Modes

Ramp-Up

• Onboarding:
  • Developers: 15–30 minutes to learn Robo task syntax (e.g., robo phpstan:check).
  • Ops/DevOps: 30–60 minutes to integrate into CI/CD.
• Training:
  • Add a CONTRIBUTING.md section with Robo/PHPStan task examples.
  • Host a workshop on static analysis best practices.
• Adoption Metrics:
  • Track usage via CI logs (e.g., "phpstan:check passed").
  • Survey team on pain points (e.g., false positives).