Churn Php Laravel Package

Technical Evaluation

Architecture Fit

• Code Health & Refactoring Tooling: churn-php is a static analysis tool designed to identify PHP files with high cyclomatic complexity and commit churn, making it a complementary tool to Laravel’s existing ecosystem (e.g., Pest, PHPStan, Psalm).
• Non-Invasive: Operates as a standalone CLI tool (via churn run) or Composer dev dependency, avoiding direct Laravel integration. This aligns with Laravel’s modular philosophy.
• Output Flexibility: Supports CSV, JSON, Markdown, and text formats, enabling integration with CI/CD pipelines, IDE plugins, or custom dashboards.
• Hook System: Allows custom logic (e.g., filtering, post-processing) via BeforeAnalysisHook, AfterFileAnalysisHook, and AfterAnalysisHook, which could be leveraged for Laravel-specific extensions (e.g., ignoring vendor files, focusing on app/ directory).

Integration Feasibility

• Low Coupling: No Laravel-specific dependencies; integrates via Composer or CLI.
• Git Dependency: Requires a VCS (default: Git), which is standard for Laravel projects.
• Parallel Processing: Supports multi-threaded analysis (parallelJobs config), reducing runtime for large codebases.
• Cache Support: Optional caching (cachePath) can speed up repeated runs in CI/CD.

Technical Risk

• False Positives/Negatives:
  • Cyclomatic complexity is language-agnostic but may misclassify Laravel-specific patterns (e.g., closures in Blade templates, dynamic method calls).
  • Commit churn depends on Git history; projects with shallow clones or monorepos may need adjustments.
• Performance:
  • Large codebases (e.g., monolithic Laravel apps) may slow down CI if not cached.
  • Memory usage could spike with parallelJobs > 1 on shared CI runners.
• Configuration Overhead:
  • Requires churn.yml tuning (e.g., filesToIgnore, directoriesToScan) to avoid noise (e.g., vendor/, node_modules/).
  • Hook development adds complexity if custom logic is needed.

Key Questions

1. Scope of Analysis:
   • Should we analyze only app/, or include packages//modules/ (if using modular Laravel)?
   • How to handle Blade templates (.blade.php)? Currently excluded by default.
2. CI/CD Integration:
   • Should churn results fail builds if scores exceed thresholds (maxScoreThreshold)?
   • How to surface results in Slack/GitHub PRs (e.g., via markdown output + CI annotations)?
3. Tooling Synergy:
   • How to combine with PHPStan/Psalm? Could churn trigger deeper analysis for high-scoring files?
   • Should we automate refactoring (e.g., via Rector) for critical files?
4. Maintenance:
   • Who owns churn.yml configuration? DevOps, backend team, or shared?
   • How to version-control churn results for trend analysis?

Integration Approach

Stack Fit

• Laravel Compatibility:
  • Works with PHP 7.1+ (Laravel 5.8+), Composer 2.0+, and Git (default).
  • No conflicts with Laravel’s autoloader or service container.
• Toolchain Synergy:
  • CI/CD: Integrates with GitHub Actions, GitLab CI, etc., via CLI or Composer scripts.
  • IDE: Output can feed into PHPStorm inspections or VSCode extensions.
  • Monitoring: JSON/CSV outputs enable time-series dashboards (e.g., Grafana) for code health trends.

Migration Path

1. Pilot Phase:
   • Install as dev dependency:

     composer require --dev bmitch/churn-php
     

   • Run manually on app/ directory:

     vendor/bin/churn run app/ --format markdown > churn-report.md
     

   • Validate output against known technical debt (e.g., legacy controllers).
2. CI/CD Integration:
   • Add to composer.json scripts:

     "scripts": {
       "churn": "churn run app/ --format json --maxScoreThreshold 0.8"
     }
     

   • Run in CI pipeline (e.g., GitHub Actions):

     - name: Run Churn Analysis
       run: composer churn
     

   • Optional: Fail build if maxScoreThreshold exceeded.
3. Configuration Hardening:
   • Create churn.yml with:

     directoriesToScan:
       - app/
       - packages/
     filesToIgnore:
       - app/Providers/*
       - app/Exceptions/*
     minScoreToShow: 0.3
     maxScoreThreshold: 0.7
     

   • Exclude vendor/, tests/, and Blade files by default.

Compatibility

• Laravel-Specific Adjustments:
  • Ignore Laravel-generated files: Add to filesToIgnore:

    filesToIgnore:
      - app/Providers/AppServiceProvider.php
      - app/Http/Kernel.php
      - bootstrap/*
    

  • Focus on business logic: Prioritize app/Http/Controllers/, app/Services/, and app/Models/ in directoriesToScan.
• Multi-Repo/Monorepo:
  • Use --configuration to override paths per repo.
  • Cache results (cachePath) to avoid redundant Git history scans.

Sequencing

1. Pre-Refactor:
   • Run churn before major features to identify high-churn areas and mitigate technical debt.
2. Post-Refactor:
   • Re-run churn to verify improvements in complexity/churn scores.
3. Regular Maintenance:
   • Schedule weekly/monthly churn runs in CI to track code health trends.
   • Use hooks to auto-label PRs with churn scores (via GitHub API).

Operational Impact

Maintenance

• Configuration Drift:
  • Risk: churn.yml may become outdated if directory structures change.
  • Mitigation: Document defaults and use Composer scripts to validate configs.
• Dependency Updates:
  • churn-php is actively maintained (last release: 2026), but PHPStan/PDepend (underlying tools) may require updates.
  • Mitigation: Pin versions in composer.json or use --dev updates cautiously.

Support

• Onboarding:
  • Developer Training: Teach teams to interpret churn scores (e.g., "0.8+ = refactor candidate").
  • Documentation: Add a CODE_HEALTH.md in the repo with churn examples and thresholds.
• Troubleshooting:
  • Common issues:
    • False positives: Adjust minScoreToShow or filesToIgnore.
    • Slow runs: Increase parallelJobs or use cachePath.
    • Git errors: Ensure full history is cloned (--depth 0 in CI).

Scaling

• Performance:
  • Large Codebases: Use cachePath to avoid re-scanning Git history.
  • Distributed Teams: Run churn locally before PRs to reduce CI load.
• Parallelization:
  • Default parallelJobs: 10 works for most Laravel apps; increase to 20+ for monorepos.
  • Monitor CI runtime and adjust based on queue depth.

Failure Modes

Ramp-Up

• Phase 1 (0–2 Weeks):
  • Install and run manually on a subset of directories.
  • Review top 5 files with the team to calibrate thresholds.
• Phase 2 (2–4 Weeks):
  • Integrate into PR templates (e.g., "Churn score: 0.6").
  • Add CI checks with