Profiling Laravel Package

Getting Started

1. Install (verify GPL-2.0 compatibility with your project first):

   composer require makinacorpus/profiling
   

2. Look first at the package README and src/ directory. You’ll likely find a small set of classes such as Profiler or Timer that wrap hrtime(). There is no Laravel service provider or facade, so you instantiate manually.
3. First use case – time a suspicious block in a controller or service:

   use MakinaCorpus\Profiling\Profiler;
   
   $profiler = new Profiler();
   $profiler->start('query');
   $users = User::where('active', true)->get();
   $profiler->stop('query');
   
   // In local/debug only:
   dump($profiler->getDuration('query')); // nanoseconds or seconds, check source
   

   Confirm the exact API (method names, units) from the source before relying on it.

Implementation Patterns

• Bind as a singleton in AppServiceProvider so the same profiler instance is reused across a request:

  $this->app->singleton(Profiler::class, fn () => new Profiler());
  

• Wrap in a helper for fluent timing:

  function profile(string $label, callable $callback) {
      $p = app(Profiler::class);
      $p->start($label);
      try {
          return $callback();
      } finally {
          $p->stop($label);
      }
  }
  
  $result = profile('expensive', fn () => SomeService::compute());
  

• Middleware for request-level timings (local only):

  public function handle($request, Closure $next) {
      if (! app()->environment('local')) {
          return $next($request);
      }
      $p = app(Profiler::class);
      $p->start('request');
      $response = $next($request);
      $p->stop('request');
      Log::debug('Request duration', ['duration' => $p->getDuration('request')]);
      return $response;
  }
  

• Artisan commands for benchmarking batches or warm-up tasks:

  $p = new Profiler();
  $p->start('import');
  $this->importLargeFile();
  $p->stop('import');
  $this->info('Import took ' . $p->getDuration('import') . ' ns');
  

• Tests – assert performance budgets (use sparingly; CI variance is high):

  $p = new Profiler();
  $p->start('serialize');
  $payload = $model->toArray();
  $p->stop('serialize');
  $this->assertLessThan(5_000_000, $p->getDuration('serialize')); // 5 ms in ns
  

• Integration tip: Use it only for micro‑optimisation in local/staging. For general request profiling, Laravel’s Benchmark helper (Benchmark::measure()) or Telescope/Debugbar provide richer context with zero extra dependencies.

Gotchas and Tips

• License: GPL-2.0 is a serious concern for closed-source or commercial Laravel apps. Legal review is required before shipping.
• PHP version: Relies on hrtime() – PHP 7.3+. Confirm your minimum PHP version.
• Not a profiler suite: No memory usage, call graphs, flamegraphs, or aggregation. It’s a thin timer; expect to read the source (it’s tiny).
• Overhead and production safety: Always guard with app()->environment('local') or a config flag. Do not leave active in production.
• No Laravel auto-discovery: You must register bindings/facades yourself. There is no config file to publish.
• Units and API stability: Verify whether durations are in nanoseconds or seconds and whether methods return or throw on missing labels. Write a small test around it.
• Debugging: Use dump()/Log::debug() on results; because there is no reporter, you’ll build your own output formatting.
• Extension points: Likely none beyond subclassing. If you need custom reporting, you may end up forking or wrapping it.
• Low activity (1 star, 0 dependents): Treat as a lightweight utility rather than a long-term dependency. Alternatives: symfony/stopwatch (well-maintained, PSR-friendly), Laravel’s Benchmark, or spatie/laravel-ray for richer local debugging.