Laravel Stats Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require danielbaylis/laravel-stats
   

   Publish the config file (if needed):

   php artisan vendor:publish --provider="DanielBaylis\LaravelStats\LaravelStatsServiceProvider"
   

2. Basic Usage Run the stats command to generate a report:

   php artisan stats:generate
   

   Outputs a JSON file (stats.json) in the project root by default.

3. First Use Case

   • Quick Project Health Check: Run php artisan stats:generate after a major refactor to verify file counts, class sizes, or dependency changes.
   • Onboarding: Share stats.json with new team members to contextualize project structure.

Implementation Patterns

Workflow Integration

1. CI/CD Pipeline

   • Add to post-merge or post-deploy steps to track growth:

     # Example GitHub Actions
     - name: Generate Stats
       run: php artisan stats:generate
     - name: Upload Artifact
       uses: actions/upload-artifact@v3
       with:
         name: project-stats
         path: stats.json
     

2. Custom Reports

   • Extend the StatsGenerator class to filter data (e.g., exclude tests):

     use DanielBaylis\LaravelStats\StatsGenerator;
     
     class CustomStatsGenerator extends StatsGenerator {
         protected function getExcludedPaths(): array {
             return array_merge(parent::getExcludedPaths(), [
                 'tests/',
                 'vendor/'
             ]);
         }
     }
     

3. Dashboard Integration

   • Parse stats.json in a frontend dashboard (e.g., Vue/React) to visualize:
     • File types over time.
     • Average class method count.
     • Dependency density.

Key Features to Leverage

• Exclusion Rules: Configure stats.php to ignore node_modules, storage/, etc.
• Grouping: Use --group-by=namespace to analyze stats per module.
• Comparison: Run php artisan stats:diff to compare against a baseline (e.g., stats-baseline.json).

Gotchas and Tips

Pitfalls

1. Performance

   • Avoid running on large monorepos (e.g., >50k files). Exclude irrelevant paths aggressively.
   • Cache results in CI to avoid redundant scans:

     php artisan stats:generate --cache=stats.cache
     

2. Config Overrides

   • Ensure config/stats.php merges correctly with defaults. Test with:

     php artisan stats:generate --config=custom-path
     

3. False Positives

   • The package counts all PHP files by default. Use --exclude to filter:

     php artisan stats:generate --exclude="*.blade.php"
     

Debugging

• Verbose Output: Use --verbose to see excluded files:

  php artisan stats:generate --verbose
  

• Validate JSON: Check for malformed data with:

  php artisan stats:validate
  

Extension Points

1. Custom Metrics

   • Override StatsGenerator::calculateMetrics() to add bespoke stats (e.g., "average trait usage per class").

2. Output Formats

   • Extend StatsGenerator to output Markdown/CSV:

     public function toMarkdown(): string {
         return "## Project Stats\n- Files: " . $this->stats['total_files'];
     }
     

3. Database Storage

   • Store stats.json in a DB table for historical analysis:

     // Example migration
     Schema::create('project_stats', function (Blueprint $table) {
         $table->id();
         $table->json('data');
         $table->timestamps();
     });