Weave Code
Laravel Mixpanel Laravel Package
genealabs/laravel-mixpanel
Laravel Mixpanel integrates Mixpanel analytics into Laravel apps with a simple facade, config-based tracking, and automatic user identification. Send events, track page views, and manage distinct IDs and opt-out without boilerplate.
MixPanel wrapper for Laravel.
Frequently asked questions about Laravel Mixpanel
- How do I install genealabs/laravel-mixpanel in a Laravel app?
- Install it with composer require genealabs/laravel-mixpanel. The service provider and Mixpanel facade are registered through Laravel package auto-discovery, so you do not need to edit config/app.php by hand. Then publish the configuration file with php artisan vendor:publish and add your Mixpanel credentials. Nothing else is required before you can call the facade from your code.
- How do I configure my Mixpanel token and credentials in Laravel?
- The package ships a publishable config file that holds your Mixpanel API credentials, so you publish it and set the token, typically from an environment variable. Version 13.0.0 moved configuration into a dedicated config file (PR #121), which means config key paths changed and existing setups need a republish plus updates to env files, CI variables, and secrets templates. Keep the token as a deploy-time secret rather than hardcoding it, and verify it resolves to a non-null value in every environment.
- Which Laravel and PHP versions does laravel-mixpanel support?
- Release 13.0.0 lists Laravel 13 and PHP 8.5 support as additions, but major releases typically also drop older version constraints and the notes only mention additions. Read the composer.json constraints inside the tagged release, since that file is the authoritative source. Do not upgrade Laravel or PHP purely to satisfy an analytics wrapper; let your framework roadmap drive that decision and schedule this as a separate migration.
- How do I track events with the Mixpanel facade in Laravel?
- Call the facade from a controller, service, listener, or job, for example Mixpanel::track('Invoice Paid', ['plan' => $plan, 'amount' => $amount]). It is a lightweight wrapper around the official Mixpanel PHP SDK, so event names and properties behave as documented upstream. Tracking revenue, lifecycle, and entitlement events on the server is the sweet spot, because these calls do not depend on a browser pixel and survive ad blockers.
- How do I identify users and set Mixpanel people profile properties?
- Use the facade's identify call with the distinct ID and any traits you want on the profile, then use the people methods to set or update properties. Keep that ID stable and identical to whatever your browser-side Mixpanel SDK sends, otherwise one user becomes two profiles and every cross-surface funnel is wrong. For B2B products, aligning the ID with your account, workspace, or organization model is usually what you actually want to measure.
- What is getMixpanelKey() in 13.0.0 and when should I use it?
- getMixpanelKey() was added in 13.0.0 and lets the Mixpanel distinct ID follow your own account or workspace key instead of defaulting to the authenticated user. That is the difference between being able to answer seat-level B2B questions and not being able to. It is opt-in, but changing this key after go-live fragments historical user history, so it needs a data-governance sign-off rather than only a code review.
- How do I upgrade from laravel-mixpanel 12.x to 13.x and what breaks?
- The main breaking change in 13.0.0 is that configuration moved into a dedicated publishable file (PR #121), so config key paths change. Republish the config, then re-point application code, CI pipelines, secrets templates, and deploy manifests that read the old layout. Check the composer.json constraints for dropped Laravel or PHP versions before planning, and treat this as a scheduled migration rather than a patch bump.
- Can I send Mixpanel events from queued jobs and background workers?
- Yes. Tracking calls are plain server-side PHP, so they work in queued jobs, event listeners, and artisan commands just as well as in controllers. The package does not add its own queue infrastructure, so if you want events off the request path you should wrap the calls in a Laravel job yourself. That is usually worth doing for anything triggered inside a latency-sensitive web request.
- What happens in production if the Mixpanel token is missing or misconfigured?
- The most likely and quietest failure is that the token resolves to null, events are silently dropped, and no exception surfaces. Application health checks stay green while your funnel chart falls off a cliff a week later. Add an explicit deploy or boot check that the token is present, log a warning whenever tracking is skipped, and watch Mixpanel event volume as part of release verification.
- How do I test Mixpanel tracking, and should I just use the official Mixpanel PHP SDK instead?
- The package doesn't document a built-in fake, so the usual approach is to swap the facade root or bind a test double in the container and assert the expected calls. If you would rather not carry a thin wrapper, you can use the official Mixpanel PHP SDK directly and wire your own service provider and config, trading boilerplate for one less dependency. Either way, remember this is a single-vendor, server-only tool with no consent or PII policy layer of its own, so the event taxonomy and identity model remain yours to own.
Weaver
How can I help you explore Laravel packages today?