Rudder Php Sdk Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require rudderstack/rudder-php-sdk
   

   No need to clone the repo manually—Composer handles dependencies.

2. First Use Case: Track a user's page view in a Laravel controller:

   use Rudder\Rudder;
   
   // Initialize in a service provider (e.g., AppServiceProvider)
   Rudder::init(config('rudderstack.write_key'), [
       'data_plane_url' => config('rudderstack.data_plane_url'),
       'consumer'       => 'lib_curl', // or 'lib_http'
       'debug'          => env('RUDDER_DEBUG', false),
   ]);
   
   // Track an event in a controller
   Rudder::track('user_viewed_page', [
       'userId' => auth()->id(),
       'page'   => 'dashboard',
       'properties' => ['referrer' => request()->header('referer')]
   ]);
   

3. Where to Look First:

   • SDK Documentation (check examples/ for Laravel-like use cases).
   • config/rudderstack.php (create this file for centralized config).
   • app/Providers/RudderServiceProvider.php (recommended for SDK initialization).

Implementation Patterns

1. Centralized Initialization

• Initialize the SDK once in a service provider (e.g., AppServiceProvider):

  public function boot()
  {
      Rudder::init(config('rudderstack.write_key'), config('rudderstack.options'));
  }
  

• Store config in .env:

  RUDDER_WRITE_KEY=your_write_key
  RUDDER_DATA_PLANE_URL=https://your-data-plane.rudderstack.com
  RUDDER_DEBUG=false
  

2. Event Tracking Workflows

• Page Views:

  Rudder::page('Home', [
      'url' => url()->current(),
      'properties' => ['title' => 'Home Page']
  ]);
  

• User Actions (e.g., form submissions):

  Rudder::track('form_submitted', [
      'userId' => auth()->id(),
      'form'   => 'contact',
      'properties' => ['email' => $request->email]
  ]);
  

• Identify Users (for first-time visitors):

  Rudder::identify('user123', [
      'email' => 'user@example.com',
      'traits' => ['plan' => 'pro']
  ]);
  

3. Queue Management

• Flush Events Manually (e.g., before critical operations):

  Rudder::flush(); // Send queued events immediately
  

• Batch Processing: Configure flush_at (default: 100 events) and max_queue_size (default: 10,000) in initialization to balance latency and reliability.

4. Integration with Laravel Ecosystem

• Middleware for Auto-Tracking:

  // app/Http/Middleware/TrackPageViews.php
  public function handle($request, Closure $next)
  {
      Rudder::page($request->route()->getName(), [
          'url' => $request->url(),
          'properties' => ['user_agent' => $request->userAgent()]
      ]);
      return $next($request);
  }
  

• Observers for Eloquent Models:

  // app/Observers/UserObserver.php
  public function created(User $user)
  {
      Rudder::track('user_created', [
          'userId' => $user->id,
          'properties' => $user->toArray()
      ]);
  }
  

5. Debugging and Logging

• Enable debug mode in initialization (debug: true).
• Logs appear in storage/logs/rudder.log (create this file if missing):

  // In AppServiceProvider
  if (config('rudderstack.debug')) {
      Storage::makeDirectory('logs');
      Rudder::setLogger(function ($message) {
          Log::channel('single')->info($message);
      });
  }
  

Gotchas and Tips

Pitfalls

1. Write Key Exposure:

   • Never commit .env to version control. Use Laravel's .env encryption or a secrets manager.
   • Fix: Validate RUDDER_WRITE_KEY in AppServiceProvider:

     if (empty(config('rudderstack.write_key'))) {
         throw new \RuntimeException('RudderStack write key not configured.');
     }
     

2. Queue Size Limits:

   • If max_queue_size is exceeded, events may drop silently.
   • Fix: Monitor queue size with:

     $queueSize = Rudder::getQueueSize();
     if ($queueSize > config('rudderstack.max_queue_size') * 0.9) {
         Log::warning("RudderStack queue near capacity: {$queueSize}");
     }
     

3. Debug Mode in Production:

   • Debug logs (debug: true) can bloat storage logs.
   • Fix: Use environment-specific configs:

     'debug' => app()->environment('local'),
     

4. Consumer Library Quirks:

   • lib_curl is default but may fail on shared hosting (e.g., cURL disabled).
   • Fix: Fallback to lib_http:

     'consumer' => extension_loaded('curl') ? 'lib_curl' : 'lib_http',
     

Debugging Tips

1. Verify Events: Use RudderStack’s Debugger to confirm events are received.

   • Enable debug: true and check storage/logs/rudder.log for payloads.

2. Network Issues:

   • If events disappear, check:
     • data_plane_url is correct (HTTPS required).
     • No firewall/proxy blocks outbound requests to RudderStack.
     • Test: Use lib_http temporarily to rule out cURL issues.

3. Payload Validation: RudderStack rejects malformed events. Validate with:

   try {
       Rudder::track('event', ['invalid' => null]);
   } catch (\Rudder\Exception\InvalidPayloadException $e) {
       Log::error("RudderStack payload error: " . $e->getMessage());
   }
   

Extension Points

1. Custom Transformers: Modify event payloads before sending:

   Rudder::setTransformer(function ($event) {
       $event['properties']['processed_at'] = now()->toIso8601String();
       return $event;
   });
   

2. Batch Processing Hooks: Intercept batches before flushing:

   Rudder::setBatchProcessor(function ($batch) {
       // Add correlation IDs or enrich data
       foreach ($batch as &$event) {
           $event['context']['integration'] = 'laravel';
       }
       return $batch;
   });
   

3. Fallback for Offline Mode: Store events in a database table (rudder_events) and retry on next request:

   // In a queue job
   public function handle()
   {
       $events = DB::table('rudder_events')->limit(100)->get();
       foreach ($events as $event) {
           Rudder::track($event->event, $event->properties);
       }
       DB::table('rudder_events')->whereIn('id', $events->pluck('id'))->delete();
   }
   

Config Quirks

• flush_at vs. flush_queue:
  • flush_at: Auto-flushes when queue reaches this size (default: 100).
  • flush_queue: Manually flush the queue (use sparingly in high-traffic apps).
• Timeouts: Default timeout is 5 seconds. Increase for slow networks:

  'timeout' => 10, // seconds