Tracker Hub Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require beeketing/tracker-hub-bundle
   

   Add the bundle to config/bundles.php:

   return [
       // ...
       Beeketing\TrackerHubBundle\BeeketingTrackerHubBundle::class => ['all' => true],
   ];
   

2. Configuration Define your tracker clients in config/packages/bk_tracker_hub.yaml:

   bk_tracker_hub:
       clients:
           mixpanel:
               write_token: '%env(MIXPANEL_WRITE_TOKEN)%'
           customerio:
               site_id: '%env(CUSTOMER_IO_SITE_ID)%'
               api_key: '%env(CUSTOMER_IO_API_KEY)%'
   

3. First Use Case Inject TrackerHub service into a controller or service:

   use Beeketing\TrackerHubBundle\TrackerHub;
   
   public function __construct(private TrackerHub $trackerHub) {}
   
   public function trackUserEvent(User $user, string $event, array $properties = []): void
   {
       $this->trackerHub->identify($user->id, [
           'email' => $user->email,
           'name' => $user->name,
       ]);
       $this->trackerHub->track($user->id, $event, $properties);
   }
   

Implementation Patterns

Core Workflows

1. User Identification

   • Use identify() to set user traits upfront (e.g., signup, profile updates).
   • Example: Track user metadata during authentication:

     $this->trackerHub->identify($userId, [
         'plan' => $user->subscription->plan,
         'last_active' => now()->toDateTimeString(),
     ]);
     

2. Event Tracking

   • Track actions with track() (e.g., clicks, purchases, form submissions).
   • Example: E-commerce checkout:

     $this->trackerHub->track($userId, 'Checkout Started', [
         'cart_value' => $order->total,
         'items' => count($order->items),
     ]);
     

3. Batch Processing

   • Queue events for async processing (recommended for high-volume apps):

     $this->trackerHub->queueTrack($userId, 'Page View', ['page' => 'home']);
     // Process later via a queue worker (e.g., Symfony Messenger)
     

Integration Tips

• Symfony Events Bind to Symfony events (e.g., Kernel::TERMINATE) to track page views:

  $eventDispatcher->addListener(Kernel::TERMINATE, function (Request $request) {
      $this->trackerHub->track('anonymous', 'Page View', [
          'path' => $request->getPathInfo(),
      ]);
  });
  

• Doctrine Lifecycle Callbacks Track entity changes (e.g., postPersist for new users):

  use Doctrine\ORM\Event\LifecycleEventArgs;
  
  public function postPersist(User $user, LifecycleEventArgs $args): void
  {
      $this->trackerHub->identify($user->id, [
          'signup_method' => 'web',
          'created_at' => $user->createdAt->format('Y-m-d'),
      ]);
  }
  

• Middleware for API Tracking Wrap API requests to track endpoints:

  public function handle(Request $request, Closure $next)
  {
      $this->trackerHub->track('api_user', 'API Request', [
          'endpoint' => $request->getPathInfo(),
          'method' => $request->getMethod(),
      ]);
      return $next($request);
  }
  

Gotchas and Tips

Pitfalls

1. Configuration Overrides

   • Ensure bk_tracker_hub config is merged correctly in config/packages/. Use !imports to override defaults:

     imports:
         - { resource: 'config/packages/bk_tracker_hub.yaml' }
     

2. Queue Dependencies

   • If using queueTrack(), ensure your queue system (e.g., RabbitMQ, Symfony Messenger) is configured. Unprocessed events may pile up silently.

3. API Rate Limits

   • Trackers like Mixpanel/Customer.io have rate limits. Implement retries with exponential backoff:

     $this->trackerHub->track($userId, 'Event', $properties, [
         'retry_after' => 5, // seconds
     ]);
     

4. Anonymous Users

   • Use a consistent ID (e.g., anonymous_${request->getClientIp()}) for unauthenticated users to avoid duplicate tracking.

Debugging

• Enable Debug Mode Set debug: true in config to log failed requests:

  bk_tracker_hub:
      debug: true
  

  Check logs in var/log/dev.log.

• Mocking for Tests Use a custom TrackerHub service in tests:

  $this->container->set('tracker_hub', $this->createMock(TrackerHub::class));
  

Extension Points

1. Custom Clients Extend the bundle to support additional trackers (e.g., Amplitude, PostHog):

   // src/Service/CustomTrackerClient.php
   class CustomTrackerClient implements TrackerClientInterface
   {
       public function track(string $userId, string $event, array $properties): void
       {
           // Custom logic
       }
   }
   

   Register in services.yaml:

   services:
       App\Service\CustomTrackerClient:
           tags: ['tracker_hub.client']
   

2. Event Transformers Modify event data before sending:

   $this->trackerHub->track($userId, 'Event', $properties, [
       'transformer' => function (array $data) {
           $data['sanitized'] = strtolower($data['original'] ?? '');
           return $data;
       },
   ]);
   

3. Environment-Specific Clients Disable trackers in staging/dev:

   bk_tracker_hub:
       clients:
           mixpanel:
               write_token: '%env(MIXPANEL_WRITE_TOKEN)%'
               enabled: '%kernel.debug%'