Laravel Stats Phploc Laravel Package

Technical Evaluation

Architecture Fit

• Static Analysis Tool: The package provides static code metrics (LOC, complexity, dependencies) but is not a runtime dependency—it’s a standalone CLI tool (PHAR) or Phive-managed binary. This makes it non-intrusive to Laravel’s architecture but requires external execution.
• Laravel Integration: The laravel-stats wrapper (mentioned in the README) suggests this was designed for Laravel-specific reporting, but the fork itself is not a Laravel package—it’s a compatibility layer for wnx/laravel-stats.
• Use Case Alignment: Best suited for:
  • Codebase health monitoring (e.g., CI/CD checks, tech debt tracking).
  • Developer insights (e.g., class/method complexity trends).
  • Non-production environments (per the warning).

Integration Feasibility

• No Composer Dependency: The package explicitly discourages Composer installation (per Sebastian Bergmann’s tweet), requiring manual PHAR/Phive setup.
• Laravel-Specific Wrapper: The laravel-stats package (not this fork) would handle Laravel integration (e.g., publishing metrics to a dashboard). This fork is only for compatibility.
• Output Parsing: To integrate metrics into Laravel, you’d need to:
  1. Run phploc.phar via Artisan::command() or a shell command.
  2. Parse JSON/XML output (if supported) or regex-scrape CLI output.
  3. Store results in a database (e.g., laravel-stats uses SQLite).

Technical Risk

Key Questions

1. Why not use the original phploc?
   • The fork is only for wnx/laravel-stats compatibility. If you don’t need Laravel integration, use the official PHAR.
2. How will metrics be consumed?
   • Will they be stored in a DB, displayed in a dashboard, or logged? This dictates parsing/integration effort.
3. What’s the CI/CD workflow?
   • Should metrics block builds (e.g., fail if complexity exceeds thresholds) or log trends?
4. PHP Version Support:
   • The fork drops PHP <8.0 support. Is your Laravel app on PHP 8.0+?
5. Maintenance Plan:
   • Who will handle updates if the fork or upstream phploc breaks?

Integration Approach

Stack Fit

• Best For:
  • Laravel + PHP 8.0+ projects using wnx/laravel-stats (or building a similar dashboard).
  • Non-production environments (CI/CD, local dev insights).
• Poor Fit:
  • Production runtime dependencies (this is a static analysis tool, not a library).
  • Projects needing real-time metrics (runs as a batch process).

Migration Path

1. Option A: Use Official PHAR (Recommended if no Laravel integration needed)

   • Download: wget https://phar.phpunit.de/phploc.phar
   • Run via shell_exec() or Artisan::command():

     $output = shell_exec('php phploc.phar src --log-json metrics.json');
     

   • Parse JSON output (if using --log-json).

2. Option B: Laravel-Specific Integration (If using wnx/laravel-stats)

   • Install wnx/laravel-stats (not this fork) for built-in Laravel support.
   • Configure phploc as a scheduled task (e.g., php artisan stats:run).

3. Option C: Custom Integration (For Advanced Use Cases)

   • Step 1: Set up PHAR/Phive in a tools/ directory.
   • Step 2: Create an Artisan command:

     php artisan make:command PhpLocMetrics
     

     // app/Console/Commands/PhpLocMetrics.php
     public function handle() {
         $command = base_path('tools/phploc.phar') . ' src --log-json';
         $output = shell_exec($command);
         $metrics = json_decode($output, true);
         // Store in DB or log
     }
     

   • Step 3: Schedule via Laravel’s scheduler or CI/CD.

Compatibility

Sequencing

1. Pre-requisite: Ensure PHP 8.0+ and Laravel 8+ (or compatible version).
2. Installation:
   • Add PHAR to tools/ directory or use Phive.
   • (Optional) Install wnx/laravel-stats if Laravel integration is needed.
3. Configuration:
   • Define which directories to scan (e.g., app/, packages/).
   • Set up output parsing (JSON preferred).
4. Automation:
   • Schedule via Laravel scheduler or CI/CD (e.g., GitHub Actions).
5. Monitoring:
   • Alert on thresholds (e.g., "Average Method Complexity > 10").

Operational Impact

Maintenance

• Pros:
  • No Laravel core dependencies (isolated tool).
  • Lightweight (no database schema changes).
• Cons:
  • Manual PHAR updates required (no Composer autoupdate).
  • Fork-specific risks: If wnx/laravel-stats changes, this fork may break.
  • Output parsing maintenance: CLI format may change in future releases.

Support

• Debugging:
  • Issues likely stem from:
    • PHAR execution (permissions, paths).
    • Output parsing (regex/JSON handling).
    • Laravel integration (if using wnx/laravel-stats).
  • No official support: Community-driven (GitHub issues).
• Fallback:
  • Use the official PHAR if fork issues arise.

Scaling

• Performance:
  • Low overhead: Runs outside Laravel’s request cycle.
  • Large codebases: May take minutes for deep scans (e.g., 100K+ LOC).
• Parallelization:
  • Can be run in CI/CD pipelines in parallel with other tasks.
  • For real-time insights, consider incremental scanning (e.g., only modified files).

Failure Modes

Ramp-Up

• Developer Onboarding:
  • Low effort: Just run php phploc.phar src to see metrics.
  • High effort: Custom parsing/integration requires PHP/CLI knowledge.
• Documentation:
  • Existing: README covers basic usage; no Laravel-specific docs.
  • Gaps: Need to document:
    • PHAR setup steps.
    • Output