Php Profiler Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require perftools/php-profiler
   

   Add the XHProf extension to your PHP installation (requires pecl install xhprof).

2. First Use Case Enable profiling in a Laravel controller or middleware:

   use PerfTools\Profiler;
   
   public function index()
   {
       Profiler::start('my_controller_action');
   
       // Your logic here...
   
       Profiler::stop();
       return view('results', ['data' => Profiler::getData()]);
   }
   

3. Viewing Results Use the included XHGUI viewer (included in the package) to visualize the data:

   php vendor/bin/xhgui
   

   Access http://localhost:8080 to see the profiling results.

Implementation Patterns

Common Workflows

1. Middleware Integration Wrap profiling logic in middleware for automatic instrumentation:

   public function handle($request, Closure $next)
   {
       Profiler::start('request_' . $request->path());
       $response = $next($request);
       Profiler::stop();
       return $response;
   }
   

2. Service-Level Profiling Profile critical services (e.g., repositories, jobs):

   public function fetchData()
   {
       Profiler::start('UserRepository::fetchActiveUsers');
       $users = User::where('active', true)->get();
       Profiler::stop();
       return $users;
   }
   

3. Conditional Profiling Enable profiling only in development/staging:

   if (app()->environment(['local', 'staging'])) {
       Profiler::start('critical_path');
       // ...
       Profiler::stop();
   }
   

4. Custom Metrics Track custom events (e.g., database queries, API calls):

   Profiler::start('DB::query', 'SELECT * FROM users');
   DB::select('SELECT * FROM users');
   Profiler::stop();
   

Integration Tips

• Laravel Debugbar: Merge XHProf data with Debugbar for unified views.
• Queue Jobs: Profile async jobs by wrapping handle():

  public function handle()
  {
      Profiler::start('SendEmailJob');
      // Job logic...
      Profiler::stop();
  }
  

• API Responses: Attach profiling data to API responses (for debugging):

  return response()->json([
      'data' => $result,
      'profiling' => Profiler::getData()
  ]);
  

Gotchas and Tips

Pitfalls

1. Memory Overhead Profiling adds ~10-20% overhead. Disable in production:

   if (app()->environment('production')) {
       Profiler::disable();
   }
   

2. XHProf Extension

   • Requires PHP 7.4–8.2 (check compatibility).
   • May conflict with other extensions (e.g., xdebug). Disable XDebug if using both:

     xdebug.mode=off
     

3. Data Retention XHGUI stores data in runtime/xhprof. Clear old files periodically:

   rm -rf runtime/xhprof/*
   

4. Nested Profiling Avoid deeply nested start/stop calls—it bloats the call graph. Use parent-child relationships:

   Profiler::start('parent');
   Profiler::start('child');
   // ...
   Profiler::stop(); // Stops 'child' and closes 'parent'
   

Debugging Tips

• Missing Data: Verify XHProf is enabled (php -m | grep xhprof).
• Slow Queries: Use Profiler::start('query', 'SQL_HERE') to isolate DB bottlenecks.
• Flame Graphs: Generate flame graphs from XHGUI for visual analysis.

Extension Points

1. Custom Data Collectors Extend PerfTools\Profiler\Collector\BaseCollector to add metrics (e.g., Redis calls):

   class RedisCollector extends BaseCollector {
       public function collect() {
           return ['cache_hits' => Redis::get('hits')];
       }
   }
   

2. Hooks Use Laravel’s booted event to auto-start profiling:

   public function boot()
   {
       if (app()->environment('local')) {
           Profiler::start('app_boot');
       }
   }
   

3. Storage Backends Replace XHGUI with a custom storage (e.g., database) by implementing PerfTools\Profiler\Storage\StorageInterface.