Php Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require daemon8ai/daemon8-php
   

2. Configuration: Add your Daemon8 API key to .env:

   DAEMON8_API_KEY=your_api_key_here
   

3. First Use Case: Instrument a Laravel route or service method:

   use Daemon8\Daemon8;
   
   Route::get('/api/health', function () {
       return Daemon8::observe('health_check', function () {
           return response()->json(['status' => 'ok']);
       });
   });
   

   • Where to look first:
     • Daemon8 PHP SDK Docs
     • Daemon8::observe() method for core functionality
     • Daemon8\Observers namespace for built-in observers

Implementation Patterns

Laravel-Specific Patterns

1. Service Provider Integration: Create a custom service provider to auto-register Daemon8:

   // app/Providers/Daemon8ServiceProvider.php
   namespace App\Providers;
   
   use Daemon8\Daemon8;
   use Illuminate\Support\ServiceProvider;
   
   class Daemon8ServiceProvider extends ServiceProvider
   {
       public function register()
       {
           $this->app->singleton(Daemon8::class, function ($app) {
               $daemon8 = new Daemon8();
               $daemon8->setApiKey(config('daemon8.api_key'));
               return $daemon8;
           });
       }
   
       public function boot()
       {
           $this->app->booted(function () {
               Daemon8::start();
           });
       }
   }
   

   Register in config/app.php providers array.

2. Middleware for HTTP Observability:

   // app/Http/Middleware/ObserveRequests.php
   namespace App\Http\Middleware;
   
   use Daemon8\Daemon8;
   use Closure;
   
   class ObserveRequests
   {
       public function handle($request, Closure $next)
       {
           return Daemon8::observe('http_request', function () use ($request, $next) {
               return $next($request);
           });
       }
   }
   

   Add to app/Http/Kernel.php middleware stack.

3. Queue Job Instrumentation:

   // app/Jobs/ProcessOrder.php
   namespace App\Jobs;
   
   use Daemon8\Daemon8;
   use Illuminate\Bus\Queueable;
   
   class ProcessOrder implements Queueable
   {
       use Dispatchable, InteractsWithQueue, Queueable;
   
       public function handle()
       {
           Daemon8::observe('process_order_job', function () {
               // Job logic here
           });
       }
   }
   

4. Artisan Command Observability:

   // app/Console/Commands/ExampleCommand.php
   namespace App\Console\Commands;
   
   use Daemon8\Daemon8;
   use Illuminate\Console\Command;
   
   class ExampleCommand extends Command
   {
       protected $signature = 'example:command';
       protected $description = 'An example command';
   
       public function handle()
       {
           Daemon8::observe('example_command', function () {
               // Command logic here
           });
       }
   }
   

Common Workflows

1. Tracking Business Metrics:

   Daemon8::observe('checkout_flow', function () {
       // Track entire checkout process
       $order = Order::create($request->all());
       $payment = Payment::process($order);
       return $payment;
   }, ['user_id' => auth()->id(), 'cart_value' => $cartTotal]);
   

2. Error Tracking:

   try {
       $result = Daemon8::observe('critical_operation', function () {
           return $service->execute();
       });
   } catch (\Exception $e) {
       Daemon8::observe('error_critical_operation', function () use ($e) {
           throw $e;
       }, ['error_class' => get_class($e)]);
       throw $e;
   }
   

3. Performance Benchmarking:

   $baseline = Daemon8::observe('baseline_performance', function () {
       return $slowService->execute();
   });
   
   $optimized = Daemon8::observe('optimized_performance', function () {
       return $fastService->execute();
   });
   

Gotchas and Tips

Common Pitfalls

1. Authentication Issues:

   • Gotcha: Forgetting to set the API key or using incorrect permissions.
   • Fix: Verify .env has DAEMON8_API_KEY and check Daemon8 dashboard for API key status.
   • Tip: Use environment variables for sensitive data:

     Daemon8::setApiKey(env('DAEMON8_API_KEY'));
     

2. Performance Overhead:

   • Gotcha: Observing too many fine-grained operations can impact performance.
   • Fix: Use sampling for high-frequency operations:

     Daemon8::observe('high_freq_operation', function () {
         // ...
     }, [], 0.1); // 10% sampling rate
     

   • Tip: Monitor with DAEMON8_DEBUG=true in .env to see overhead metrics.

3. Network Dependencies:

   • Gotcha: Daemon8 API unavailability can break your application.
   • Fix: Implement fallback logging:

     try {
         Daemon8::observe('critical_path', $callback);
     } catch (\Exception $e) {
         \Log::error('Daemon8 failed', ['exception' => $e]);
         $callback();
     }
     

4. Data Privacy:

   • Gotcha: Accidentally sending sensitive data in observations.
   • Fix: Explicitly filter sensitive data:

     $context = [
         'user_id' => auth()->id(),
         'email' => str_replace('@', '[AT]', auth()->user()->email),
         'cart_items' => $cart->items->count()
     ];
     Daemon8::observe('checkout', $callback, $context);
     

5. Observer Conflicts:

   • Gotcha: Multiple observers modifying the same data.
   • Fix: Use observer priorities or namespaces:

     Daemon8::addObserver(new MemoryObserver(), 100); // Low priority
     Daemon8::addObserver(new ExecutionObserver(), 200); // High priority
     

Debugging Tips

1. Enable Debug Mode:

   DAEMON8_DEBUG=true
   

   This outputs raw observation data to Laravel logs.

2. Inspect Observations:

   $observations = Daemon8::getObservations();
   dd($observations);
   

3. Test Locally: Use the local testing mode:

   Daemon8::setTestMode(true);
   // All observations will be stored in memory
   $observations = Daemon8::getObservations();
   

4. Check API Status: Verify Daemon8 API connectivity:

   if (!Daemon8::ping()) {
       \Log::warning('Daemon8 API unavailable');
   }
   

Extension Points

1. Custom Observers: Create domain-specific observers:

   namespace App\Observers;
   
   use Daemon8\ObserverInterface;
   
   class OrderObserver implements ObserverInterface
   {
       public function observe($name, callable $callback, array $context = [], float $sampleRate = 1.0)
       {
           // Custom logic before/after observation
           $result = $callback();
   
           // Add custom context
           $context['order_status'] = $result->status;
           return $result;
       }
   }
   

2. Middleware for Auto-Instrumentation:

   // app/Http/Middleware/InstrumentRequests.php
   namespace App\Http\Middleware;
   
   use Daemon8\Daemon8;
   use Closure;
   
   class InstrumentRequests
   {
       public function handle($request, Closure $next)
       {
           $routeName = $request->route()->getName();
           return Daemon8::observe("route_{$routeName}", function () use ($request, $next) {
               return $next($request);
           }, [
               'method' => $request->method(),
               'path' => $request->path(),
               'ip' => $request->ip()
           ]);
       }
   }
   

3. Event Listeners:

   // app/Listeners/InstrumentEvents.php
   namespace App\Listeners;
   
   use Daemon8\Daemon8;
   use Illuminate\Queue\Events\JobProcessed;
   
   class InstrumentEvents
   {
       public function handle(JobProcessed $event)
       {
           Daemon8::observe('job_processed', function () use ($event) {
               // Job already processed, just observe
           }, [
               'job' => get_class($event->job),
               'queue' => $event->job->queue,