Mixpanel Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require dlapps/mixpanel-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       Dlapps\MixpanelBundle\DlappsMixpanelBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php artisan config:publish dlapps/mixpanel-bundle
   

   Update config/packages/dlapps_mixpanel.yaml with your Mixpanel API token and project token.

3. First Use Case Track a user event in a controller:

   use Dlapps\MixpanelBundle\Mixpanel;
   
   class UserController extends Controller
   {
       public function trackEvent()
       {
           $mixpanel = $this->container->get('dlapps_mixpanel');
           $mixpanel->track('User Registered', ['email' => 'user@example.com']);
       }
   }
   

Implementation Patterns

Dependency Injection

• Service Container Integration Inject the Mixpanel service directly into controllers/services:

  public function __construct(Mixpanel $mixpanel)
  {
      $this->mixpanel = $mixpanel;
  }
  

• Event Listeners Use listeners to track events globally (e.g., Registered events):

  // src/EventListener/MixpanelTrackListener.php
  public function onUserRegistered(UserRegisteredEvent $event)
  {
      $this->mixpanel->track('User Registered', $event->getUser()->toArray());
  }
  

Common Workflows

1. Tracking Events

   $this->mixpanel->track('Product Viewed', [
       'product_id' => $product->id,
       'price' => $product->price,
       'category' => $product->category,
   ]);
   

2. Identifying Users

   $this->mixpanel->identify('user123', ['$email' => 'user@example.com']);
   

3. People Analytics

   $this->mixpanel->peopleSet('user123', ['plan' => 'premium']);
   $this->mixpanel->peopleIncrement('user123', 'revenue', 99.99);
   

4. Batch Processing

   $this->mixpanel->trackBatch([
       ['event' => 'Login', 'properties' => ['user_id' => '123']],
       ['event' => 'Page View', 'properties' => ['page' => 'home']],
   ]);
   

Integration Tips

• Symfony Events Bind Mixpanel tracking to Symfony events (e.g., kernel.request):

  # config/services.yaml
  services:
      App\EventListener\MixpanelRequestListener:
          tags:
              - { name: kernel.event_listener, event: kernel.request, method: onKernelRequest }
  

• Laravel Mix (if applicable) If using Laravel Mix, ensure no conflicts with frontend JS tracking by coordinating with backend events.

Gotchas and Tips

Pitfalls

1. Deprecated API

   • The package was last updated in 2017 and may not support Mixpanel’s latest API (v2). Test thoroughly for:
     • Rate limits (Mixpanel’s API has strict limits).
     • Property naming (e.g., $ prefixed properties like $email).
     • Batch request size (Mixpanel’s max batch size is 100 events).

2. Configuration Overrides

   • Ensure config/packages/dlapps_mixpanel.yaml is correctly merged:

     dlapps_mixpanel:
         api_token: '%env(MIXPANEL_API_TOKEN)%'
         project_token: '%env(MIXPANEL_PROJECT_TOKEN)%'
         debug: '%kernel.debug%'  # Enable for testing
     

3. Error Handling

   • Mixpanel’s API may return 429 (Too Many Requests). Implement retry logic:

     try {
         $this->mixpanel->track('Event', $properties);
     } catch (\GuzzleHttp\Exception\RequestException $e) {
         if ($e->getCode() === 429) {
             // Retry or log
         }
     }
     

Debugging

• Enable Debug Mode Set debug: true in config to log raw API responses:

  dlapps_mixpanel:
      debug: true
  

• Check HTTP Client The bundle uses Guzzle under the hood. Verify:

  • CORS headers aren’t blocking requests.
  • The User-Agent is set (Mixpanel may reject requests without it).

Extension Points

1. Custom HTTP Client Override the default Guzzle client in a service:

   # config/packages/dlapps_mixpanel.yaml
   dlapps_mixpanel:
       client:
           class: App\Service\CustomMixpanelClient
   

2. Event Transformers Extend the Dlapps\MixpanelBundle\Event\EventTransformer to modify properties before sending:

   class CustomEventTransformer extends EventTransformer
   {
       public function transform($event, array $properties)
       {
           $properties['custom_field'] = 'value';
           return parent::transform($event, $properties);
       }
   }
   

   Then bind it in services:

   services:
       dlapps_mixpanel.event_transformer:
           class: App\Event\CustomEventTransformer
           tags: ['dlapps_mixpanel.event_transformer']
   

3. Async Tracking For high-traffic sites, queue events using Laravel Queues:

   dispatch(new TrackMixpanelEvent('Event', $properties));
   

   Implement the job to defer API calls.

Configuration Quirks

• Token Validation Mixpanel’s API rejects requests with invalid tokens. Validate tokens via:

  curl -X GET "https://mixpanel.com/api/2.0/jobs" -H "Authorization: Basic YOUR_TOKEN"
  

• Environment Variables Ensure .env has:

  MIXPANEL_API_TOKEN=your_api_token
  MIXPANEL_PROJECT_TOKEN=your_project_token