Mixpanel Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require gordalina/mixpanel-bundle:~3.0
   

   Register the bundle in config/bundles.php:

   Castrocrea\MixpanelBundle\CarstrocreaMixpanelBundle::class => ['all' => true],
   

2. Configure: Add your Mixpanel token to config/packages/castrocrea_mixpanel.yaml:

   castrocrea_mixpanel:
       projects:
           default:
               token: "%env(MIXPANEL_TOKEN)%"
   

   (Use .env for sensitive tokens.)

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

   use Castrocrea\MixpanelBundle\Service\Mixpanel;
   
   class UserController extends AbstractController
   {
       public function trackEvent(Mixpanel $mixpanel)
       {
           $mixpanel->track('User Registered', [
               'user_id' => '123',
               'email' => 'user@example.com',
               'plan' => 'premium'
           ]);
       }
   }
   

Implementation Patterns

Core Workflows

1. Dependency Injection: Inject Mixpanel service into controllers/services:

   public function __construct(private Mixpanel $mixpanel) {}
   

2. Event Tracking:

   • Basic Events:

     $this->mixpanel->track('Product Viewed', ['product_id' => 42]);
     

   • People Properties:

     $this->mixpanel->peopleSet('user123', ['plan' => 'free']);
     $this->mixpanel->peopleIncrement('user123', 'login_count');
     

3. Annotations (Legacy): Use @Mixpanel\Track on controller methods (if annotations are enabled in config):

   /**
    * @Mixpanel\Track(event="Checkout Started")
    */
   public function checkout() {}
   

4. Symfony Profiler Integration: Enable in config:

   castrocrea_mixpanel:
       profiler: true
   

   View tracked events in the Symfony Profiler toolbar.

Integration Tips

1. Environment-Specific Tokens: Use .env variables and parameter bags:

   token: "%env(MIXPANEL_TOKEN)%"
   

   php bin/console debug:container castrocrea_mixpanel
   

2. Batching Events: For high-traffic apps, batch events to reduce API calls:

   $this->mixpanel->batch([
       ['event' => 'View', 'properties' => ['page' => 'home']],
       ['event' => 'Click', 'properties' => ['button' => 'cta']]
   ]);
   

3. User Identification: Always include distinct_id (e.g., user_id or device_id) for accurate tracking:

   $this->mixpanel->track('Custom Event', ['distinct_id' => $user->id]);
   

4. Async Tracking: Offload tracking to a queue (e.g., Symfony Messenger) for performance:

   $this->messageBus->dispatch(new TrackEvent('event_name', $properties));
   

Gotchas and Tips

Pitfalls

1. Token Leaks:

   • Never hardcode tokens in config files. Always use .env or parameter bags.
   • Restrict .env to gitignore.

2. Rate Limits:

   • Mixpanel has rate limits. Batch events to avoid throttling:

     $this->mixpanel->setBatchSize(10); // Default is 1
     

3. Annotations Deprecation: The @Mixpanel\Track annotation is undocumented and may break. Prefer DI-based tracking.

4. Profiler Overhead: Disabling profiler in production:

   castrocrea_mixpanel:
       profiler: "%kernel.debug%" # Only in dev
   

Debugging

1. Enable Logging: Add to config/packages/monolog.yaml:

   handlers:
       mixpanel:
           type: stream
           path: "%kernel.logs_dir%/mixpanel.log"
           level: debug
   

   Then enable logging in the bundle:

   castrocrea_mixpanel:
       debug: true
   

2. Validate Events: Use Mixpanel’s debugger to verify events.

3. Common Errors:

   • InvalidTokenException: Check your token in .env or config.
   • NetworkError: Ensure your server can reach mixpanel.com.

Extension Points

1. Custom Event Builders: Create a decorator for Mixpanel service to add domain-specific logic:

   class CustomMixpanel extends Mixpanel
   {
       public function trackPurchase(User $user, Product $product)
       {
           $this->track('Purchase', [
               'user_id' => $user->id,
               'product_id' => $product->id,
               'amount' => $product->price,
               'currency' => 'USD'
           ]);
       }
   }
   

   Register as a service:

   services:
       App\Service\CustomMixpanel:
           decorates: 'castrocrea_mixpanel'
           arguments: ['@castrocrea_mixpanel.inner']
   

2. Event Normalization: Use a subscriber to standardize event properties before sending:

   class MixpanelEventSubscriber implements EventSubscriberInterface
   {
       public static function getSubscribedEvents()
       {
           return [
               KernelEvents::VIEW => 'onKernelView',
           ];
       }
   
       public function onKernelView(ViewEvent $event)
       {
           $event->getController()?->__invoke($event->getRequest());
           // Normalize properties here
       }
   }
   

3. Multi-Tenant Support: Extend the config to support multiple projects:

   castrocrea_mixpanel:
       projects:
           project_a:
               token: "%env(MIXPANEL_TOKEN_A)%"
           project_b:
               token: "%env(MIXPANEL_TOKEN_B)%"
   

   Switch projects dynamically:

   $this->mixpanel->setProject('project_b');