Laravel Mixpanel Api Laravel Package

Getting Started

Install the package with Composer and let Laravel auto-discover the service provider:

composer require vendor/laravel-mixpanel
php artisan vendor:publish --tag=mixpanel-config

Set the project token in .env:

MIXPANEL_TOKEN=your_project_token

For server-side ingestion (events/profiles) the project token is usually enough. For export, insights, funnels, and retention endpoints you will typically also need Mixpanel service account credentials or an API secret:

MIXPANEL_SERVICE_ACCOUNT_USERNAME=
MIXPANEL_SERVICE_ACCOUNT_SECRET=
MIXPANEL_EU_RESIDENCY=false

Look first at config/mixpanel.php to confirm host/endpoint, token names, queue settings, and whether the package exposes a facade, injectable client, or both. A good first use case is tracking a signup from a controller or listener:

use Mixpanel;

Mixpanel::track('User Signed Up', [
    'plan' => 'pro',
    'source' => 'web',
], $user->id);

If profiles are part of your onboarding flow, call identify/people->set before or alongside the event so Mixpanel attributes activity to the right distinct ID. Since 1.0.0 is the initial release, pin the version in composer.json and review minor releases for API changes.

Implementation Patterns

Centralize event names and properties. Create a small Analytics service or MixpanelEvent enum so event names, property keys, and required fields are not scattered across controllers. This makes schema changes and QA much easier.

Prefer queued tracking for non-critical events. Tracking should not slow down requests or fail user flows. Dispatch a job or use the package’s queue integration if available, and let failed jobs retry with backoff. Keep synchronous tracking for cases where you must observe the result immediately.

Use Laravel events/listeners as the integration point. Track from domain events such as UserRegistered, OrderPlaced, or SubscriptionRenewed rather than directly in controllers. This keeps analytics consistent across web, API, console, and queue contexts.

Handle anonymous-to-known identity transitions deliberately. Use alias when an anonymous visitor signs up, then associate subsequent events with the authenticated user’s distinct ID. Be consistent: either use your database user ID, UUID, or email hash, but do not mix identifiers across events for the same user.

Separate ingestion and analytics querying. Event/profile tracking uses the project token; insights, funnels, retention, and exports usually require service account credentials or an API secret. Consider two clients/configs if the package supports it, and never expose service account credentials to frontend code.

Attach request context once. Middleware can enrich events with request_id, locale, user agent, and sanitized IP. Avoid duplicating this in every controller. For GDPR/CCPA-sensitive apps, explicitly decide whether to send IPs or set ip to 0 to prevent geo-location.

Use exports and queries for reporting, not request-time dashboards. Funnel/retention/insights calls hit Mixpanel’s query APIs and are subject to rate limits and longer response times. Cache results, run them in scheduled jobs, and store snapshots if you need fast internal dashboards.

Testing pattern. Use Http::fake() or the package’s fake/spy if provided. Assert that the correct endpoint, token, distinct ID, event name, and properties are sent. For queued tracking, use Queue::fake() and assert the job is dispatched, then test the job separately.

Gotchas and Tips

• Project token ≠ query credentials. A common failure is configuring only MIXPANEL_TOKEN and then wondering why export/insights/funnels/retention return auth errors. Check the package docs/config for the exact service account fields.
• EU residency must be consistent. If your project is in Mixpanel EU, configure the EU host/endpoint. Sending ingestion data to the wrong region can appear to succeed while data lands in the wrong place or is unavailable to your project.
• Queue failures can silently drop analytics. Monitor failed jobs and add logging around tracking jobs. Decide whether analytics failures should be ignored, retried, or alerted.
• Use $insert_id for deduplication. If your queue retries or your code can send the same event twice, provide a stable $insert_id so Mixpanel can deduplicate.
• Watch property and event size limits. Mixpanel has limits on event name length, property count, and property value size. Sanitize large payloads and avoid dumping full request bodies or model arrays into properties.
• Reserved properties matter. Properties beginning with $ have special meaning ($time, $insert_id, $ip, etc.). Do not overload them unless you intend Mixpanel’s semantics.
• Profile updates need a distinct ID. people->set, increment, and similar calls must target a consistent distinct ID. Mixing aliases and raw IDs can create duplicate profiles.
• Timezone and $time handling. Server timestamps are usually fine, but if you backfill events or import historical data, set $time explicitly and confirm timezone assumptions.
• Config caching quirks. After changing Mixpanel env vars in production, run php artisan config:clear or redeploy with config caching rebuilt. Stale config is a frequent “why is it still using the old token?” cause.
• Extension points to look for. Check whether the package allows custom HTTP clients, event transformers, middleware, or a custom queue connection. Those are the right places to add retries, logging, PII scrubbing, and test fakes without forking the package.
• Version pinning for 1.0.0. Initial releases often stabilize API names and config keys over the first few patch/minor versions. Pin to ^1.0 and review changelogs before upgrading in production.