Cli Snapshot Profiler Event Subscriber Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require aeatech/cli-snapshot-profiler-event-subscriber
   

2. Register the Subscriber Add the subscriber to your Laravel service provider (e.g., AppServiceProvider):

   use Aeatech\CliSnapshotProfilerEventSubscriber\CliSnapshotProfilerSubscriber;
   
   public function boot()
   {
       $this->app->make(CliSnapshotProfilerSubscriber::class)->subscribe();
   }
   

3. First Use Case Run a CLI command (e.g., php artisan migrate) and observe the generated profiling snapshot in:

   storage/logs/cli-snapshots/
   

   Snapshots are stored as .prof files (Xdebug-compatible).

Implementation Patterns

Workflow for CLI Profiling

1. Enable Profiling Trigger profiling for a specific command by setting an environment variable:

   PROFILER_ENABLED=true php artisan your:command
   

   Or programmatically:

   $this->app->make(CliSnapshotProfilerSubscriber::class)->enable();
   

2. Customize Snapshot Path Override the default storage path in config (if published):

   'snapshot_path' => storage_path('custom-profiler-snapshots'),
   

3. Integrate with Artisan Commands Use the subscriber in custom commands to profile execution:

   use Aeatech\CliSnapshotProfilerEventSubscriber\CliSnapshotProfilerSubscriber;
   
   protected function handle()
   {
       $profiler = app(CliSnapshotProfilerSubscriber::class);
       $profiler->enable();
   
       // Command logic here...
   
       $profiler->disable(); // Optional: Force snapshot generation
   }
   

4. Analyze Snapshots Use tools like QCacheGrind or KCacheGrind to open .prof files:

   qcachegrind storage/logs/cli-snapshots/your-command.prof
   

Gotchas and Tips

Pitfalls

1. Xdebug Requirement

   • The package relies on Xdebug for profiling. Ensure Xdebug is installed and configured:

     ; php.ini
     zend_extension=xdebug.so
     xdebug.mode=profile
     xdebug.output_dir=/path/to/storage/logs/cli-snapshots
     

   • Tip: Use xdebug.start_with_request=trigger to avoid profiling all requests.

2. Environment-Specific Issues

   • Profiling may fail in production if PROFILER_ENABLED is not set or Xdebug is disabled.
   • Fix: Add a check in your AppServiceProvider:

     if (!app()->environment('local') && !env('PROFILER_ENABLED')) {
         return;
     }
     

3. Snapshot Naming Conflicts

   • Snapshots are named using the command name + timestamp. Overlapping runs may overwrite files.
   • Solution: Customize the filename in the subscriber:

     $profiler->setSnapshotName('custom-' . now()->format('Y-m-d_His'));
     

4. Performance Overhead

   • Profiling adds latency. Disable it in CI/CD pipelines or high-frequency CLI tasks.

Debugging Tips

• Verify Xdebug Works Run a test command and check for .prof files in the output directory.

  php -dxdebug.mode=profile artisan your:command
  

• Log Subscriber Events Add debug logs to confirm the subscriber is active:

  public function subscribe()
  {
      event(new \Illuminate\Console\Events\CommandStarting('your:command'));
      \Log::debug('Profiler subscriber triggered for command: your:command');
  }
  

Extension Points

1. Custom Profiler Logic Extend the subscriber to add pre/post-profiling hooks:

   use Aeatech\CliSnapshotProfilerEventSubscriber\Contracts\ProfilerSubscriber;
   
   class CustomProfilerSubscriber implements ProfilerSubscriber
   {
       public function enable()
       {
           // Custom logic (e.g., flush cache before profiling)
       }
   }
   

2. Snapshot Processing Automate snapshot cleanup or analysis:

   // Example: Delete old snapshots
   $this->app->booted(function () {
       $profiler = app(CliSnapshotProfilerSubscriber::class);
       $profiler->cleanupOldSnapshots(7); // Keep last 7 days
   });
   

3. Integration with Monitoring Forward snapshots to a monitoring system (e.g., Sentry, Datadog) for alerting:

   $profiler->onSnapshotGenerated(function ($path) {
       \Log::info("Snapshot generated: $path");
       // Upload to external service...
   });