Churn Php Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require --dev bmitch/churn-php
   

   or via Phive:

   phive install churn
   

2. First Run:

   vendor/bin/churn run src
   

   This scans the src directory for PHP files, calculates churn scores (commit frequency + cyclomatic complexity), and displays results in a table.

3. Key Outputs:

   • Churn Score: Combines commit frequency and cyclomatic complexity (higher = better refactoring candidate).
   • Columns: File, Commits, Complexity, Score, Lines.

Where to Look First

• Default Configuration: churn.yml (if present) or CLI flags.
• Output Formats: --format json|csv|markdown|text (default: text).
• Example Output:

  +-------------------------------------------+---------+------------+--------+--------+
  | File                                     | Commits | Complexity | Score  | Lines  |
  +-------------------------------------------+---------+------------+--------+--------+
  | src/Service/ComplexService.php           | 42      | 18         | 0.95   | 250    |
  | src/Controller/OldController.php         | 12      | 30         | 0.87   | 180    |
  +-------------------------------------------+---------+------------+--------+--------+
  

Implementation Patterns

Daily Workflows

1. Pre-Refactoring:

   vendor/bin/churn run src --min-score 0.5 --files-to-show 20
   

   • Focus on files with Score > 0.5 (adjust threshold as needed).
   • Prioritize files with high Complexity and frequent Commits.

2. CI Integration:

   • Add to composer.json scripts:

     "scripts": {
       "churn": "churn run src --max-score-threshold 0.8 --format json > churn.json"
     }
     

   • Use in CI to fail builds if churn scores exceed a threshold:

     composer churn && if [ $(jq '.results[0].score' churn.json) -gt 0.8 ]; then exit 1; fi
     

3. Custom Outputs:

   • Generate Markdown for team docs:

     vendor/bin/churn run src --format markdown > REFACTORING.md
     

   • Export to CSV for tracking:

     vendor/bin/churn run src --format csv > churn.csv
     

4. Ignoring Files:

   • Configure churn.yml to exclude tests or vendors:

     filesToIgnore:
       - tests/
       - vendor/
       - src/Helpers/*.php
     

Integration Tips

• Laravel-Specific:

  • Scan only Laravel-specific directories:

    vendor/bin/churn run app/Http app/Console app/Providers
    

  • Combine with phpstan or psalm for deeper analysis:

    vendor/bin/churn run src --format json | jq -r '.results[] | select(.score > 0.7) | .file' | xargs phpstan analyse
    

• Parallel Processing:

  • Speed up analysis with --parallel-jobs (default: 10):

    vendor/bin/churn run src --parallel-jobs 20
    

• Version Control:

  • Customize commitsSince for shorter/longer histories:

    # churn.yml
    commitsSince: "6 months ago"
    

  • Supports git, mercurial, fossil, or subversion (default: git).

Gotchas and Tips

Pitfalls

1. False Positives:

   • Issue: Files with high Complexity but low Commits (e.g., legacy code) may not need refactoring.
   • Fix: Use minScoreToShow to filter:

     minScoreToShow: 0.3  # Only show files with score >= 0.3
     

2. Performance:

   • Issue: Large codebases (e.g., 10K+ files) may slow down analysis.
   • Fix:
     • Limit directories: churn run app/Http app/Console.
     • Reduce parallelJobs if OOM errors occur.

3. VCS Limitations:

   • Issue: Shallow clones or non-Git repos may break commit counting.
   • Fix:
     • Ensure full Git history: git fetch --unshallow.
     • Set vcs: none for non-versioned projects (loses commit data).

4. Hooks Not Triggering:

   • Issue: Custom hooks (e.g., AfterFileAnalysisHook) may fail silently.
   • Fix:
     • Verify autoloader access or use full paths:

       hooks:
         - /absolute/path/to/MyHook.php
       

     • Check hook interfaces: AfterAnalysisHook, BeforeAnalysisHook.

5. Cache Issues:

   • Issue: Stale cache (cachePath) may show outdated scores.
   • Fix: Delete cache or set cachePath: null to disable:

     rm -f .churn.cache && vendor/bin/churn run src
     

Debugging Tips

1. Dry Runs:

   • Test with a subset of files:

     vendor/bin/churn run app/Http --files-to-show 5
     

2. Verbose Output:

   • Enable debug mode (if supported in future versions) or check logs for hook errors.

3. Complexity Calculation:

   • If scores seem off, verify with pdepend:

     vendor/bin/pdepend --ignore=tests/ --short src/ | grep "Complexity"
     

4. Configuration Overrides:

   • Override CLI args in churn.yml:

     # Overrides --min-score 0.5 and --parallel-jobs 5
     minScoreToShow: 0.5
     parallelJobs: 5
     

Extension Points

1. Custom Hooks:

   • Example: Log high-churn files to Slack.

     // src/Hooks/SlackHook.php
     namespace App\Hooks;
     
     use Churn\Event\Hook\AfterFileAnalysisHook;
     use Churn\Event\Event\AfterFileAnalysis;
     
     class SlackHook implements AfterFileAnalysisHook {
         public function onAfterFileAnalysis(AfterFileAnalysis $event) {
             if ($event->getScore() > 0.7) {
                 // Send Slack notification
             }
         }
     }
     

     Register in churn.yml:

     hooks:
       - App\Hooks\SlackHook
     

2. Output Format Extensions:

   • Extend the ResultsParser to add custom columns (e.g., "Last Modified").

3. VCS Integration:

   • Override commit counting for custom VCS systems by extending Churn\Vcs\VcsInterface.

4. Complexity Metrics:

   • Replace the default CyclomaticComplexityAssessor with a custom implementation using nikic/PHP-Parser for more granular control.