Laravel Stats Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require "wnx/laravel-stats" --dev
   

   The package auto-registers, so no additional steps are needed unless you want to customize behavior.

2. First Run:

   php artisan config:clear && php artisan stats
   

   This generates a human-readable report in the terminal, summarizing:

   • Project metrics (classes, methods, lines of code)
   • Dependency analysis (composer packages, Laravel components)
   • Code complexity (cyclomatic complexity, depth of nesting)

3. JSON Output (for programmatic use):

   php artisan stats --json
   

   Outputs structured data for integration with CI/CD pipelines or monitoring tools.

First Use Case: Quick Project Health Check

Run php artisan stats after a major refactor or before a release to:

• Validate if class/method counts align with expectations.
• Identify bloated components (e.g., a UserController with 50+ methods).
• Spot unused dependencies (e.g., abandoned packages in composer.json).

Implementation Patterns

Workflows

1. CI/CD Integration:

   • Add to phpunit.xml or GitHub Actions:

     <php>
         <env name="STATS_JSON" value="1"/>
     </php>
     

   • Parse JSON output in workflows to enforce metrics (e.g., fail if cyclomatic complexity > 20).

2. Local Development:

   • Alias the command in .bashrc:

     alias stats='php artisan stats'
     

   • Run before PRs to catch regressions:

     git diff --name-only HEAD~1 HEAD | grep '\.php$' && stats
     

3. Custom Reports:

   • Extend the Wnx\LaravelStats\Commands\StatsCommand class to filter output (e.g., only show App\Http\Controllers):

     protected function getReport(): Report
     {
         return parent::getReport()->filterByNamespace('App\Http\Controllers');
     }
     

Integration Tips

1. Laravel Forge/Envoyer:

   • Cache the JSON output in a stats.json file and compare across deployments:

     php artisan stats --json > stats.json
     

   • Use diff to detect metric changes:

     diff stats.json stats.previous.json
     

2. IDE Plugins:

   • Parse the JSON output to highlight "hotspots" in PHPStorm/WebStorm using annotations.

3. Documentation:

   • Reference stats in CONTRIBUTING.md to guide new devs on project structure:

     This project has 420 classes (avg. 15 methods/class). Aim for <20 cyclomatic complexity.
     

Gotchas and Tips

Pitfalls

1. Performance:

   • Avoid running on large codebases (>50K LOC) in CI; cache results or run locally.
   • Exclude vendor/ and node_modules/ from analysis by publishing the config:

     'exclude' => [
         'vendor/',
         'node_modules/',
         'tests/',
     ],
     

2. False Positives:

   • Laravel’s Illuminate\Support\Collection may inflate method counts. Ignore it in config:

     'ignored_namespaces' => [
         'Illuminate\Support\',
     ],
     

3. Dynamic Classes:

   • Traits and anonymous classes may cause parsing errors. Use --skip-errors to continue:

     php artisan stats --skip-errors
     

Debugging

1. Verbose Output:

   • Enable debug mode to see raw parsing logs:

     php artisan stats --verbose
     

2. Custom Parsers:

   • Override Wnx\LaravelStats\Parsers\ParserInterface to handle custom syntax (e.g., Blade templates):

     class BladeParser implements ParserInterface
     {
         public function parse(string $file): array
         {
             // Custom logic for Blade files
         }
     }
     

3. Configuration Quirks:

   • Ensure config/laravel-stats.php is published if modifying defaults:

     php artisan vendor:publish --tag=laravel-stats-config
     

   • Clear config cache after changes:

     php artisan config:clear
     

Extension Points

1. Add Custom Metrics:

   • Extend Wnx\LaravelStats\Report to include domain-specific metrics (e.g., "API endpoint coverage"):

     class CustomReport extends Report
     {
         public function calculateApiCoverage(): int
         {
             // Logic to count API routes vs. implemented controllers
         }
     }
     

2. Visualization:

   • Use the JSON output to generate graphs with tools like:

     jq '.metrics.methods | length' stats.json  # Count methods
     

   • Integrate with Grafana for time-series tracking.

3. Git Hooks:

   • Pre-commit hook to block merges if metrics exceed thresholds:

     # .git/hooks/pre-commit
     php artisan stats --json | jq '.metrics.complexity > 20' && exit 1