Weave Code
Laravel Pirsch Laravel Package
pirsch-analytics/laravel-pirsch
Integrate Pirsch analytics into Laravel with a simple, privacy-friendly API. Track page views and custom events server-side—no cookies, no GDPR headaches—and review stats in the Pirsch dashboard.
Official Laravel integration for Pirsch Analytics.
Frequently asked questions about Laravel Pirsch
- How do I install and set up pirsch-analytics/laravel-pirsch in a Laravel app?
- Install it with Composer using composer require pirsch-analytics/laravel-pirsch, then publish the package config file and fill in your Pirsch credentials. You need the client ID, client secret and host for your Pirsch account, which you set as environment variables. After that, tracking is a single facade call such as Pirsch::hit() for pageviews or Pirsch::event() for custom events. There are no migrations, no frontend assets and no queues of the package's own, so setup is genuinely a few minutes.
- Which Laravel and PHP versions does laravel-pirsch support?
- Version 1.1.0 added Laravel 13 support, alongside the earlier Laravel versions the package already covered. Because that release is primarily a widened framework constraint, you should read composer.json in the tagged release to confirm the current minimum Laravel and PHP versions rather than assuming the floor did not move. If you are still running an older Laravel release, check whether the constraint still admits it before upgrading the package.
- Is Pirsch Analytics GDPR compliant, and do I need a cookie banner?
- Pirsch is cookieless and EU-hosted, which is the main reason teams pick it over GA4, but cookieless does not automatically mean consent-free in every jurisdiction. Whether you still need consent or a privacy notice depends on your country, your lawful basis and how you configure the product. Treat this as a legal question rather than an engineering one and get sign-off from whoever owns privacy in your organisation.
- Should I call Pirsch::hit() directly in a controller or queue it?
- Calling the facade synchronously inside a controller is the simplest option but ties user-facing response time to a third-party HTTP request, which is a bad trade on hot paths. The usual recommendation is to dispatch tracking from a queued job or from terminate() middleware so the response is not blocked by an outbound call. Whichever you pick, decide explicitly and check what timeout and retry behaviour applies on failure.
- How do I track custom events with laravel-pirsch?
- Use the event method on the Pirsch facade, for example Pirsch::event() with the event name you want to appear in the dashboard. It is the same client-side-free, server-side approach as pageviews, so you can fire it from controllers, listeners, jobs or console commands. Check the underlying Pirsch PHP SDK for the exact signature and which optional fields such as duration or metadata the version you installed accepts. Keep event names stable and documented, otherwise your dashboard segments become noise.
- What configuration does the package need, and where do I put the client credentials?
- The package ships a publishable config file and reads three or four environment variables: the client ID, the client secret and the Pirsch host endpoint. Publish the config with artisan vendor:publish, keep the secret out of version control, and set the values per environment. Decide early who owns the Pirsch account, the domain registration and rotating the client secret, because losing that secret silently breaks tracking.
- Can laravel-pirsch track clicks, scroll depth or heatmaps?
- No. This package is a server-side client wrapper around the Pirsch API, so it records pageviews and events you explicitly trigger from PHP. Anything that needs to observe real browser behaviour, such as clicks, scroll depth or heatmaps, requires a client-side script, which this package does not ship. If behavioural capture is a requirement, the package is a poor fit and you should look at a tag-based setup instead.
- How do I stop analytics being sent from local development, CI or test runs?
- There is no documented built-in dry-run mode, so do not assume calls are no-ops outside production. The safe pattern is to guard every call site behind an environment check, or to only register dispatch from code paths that never run in tests. Verify it yourself by running the test suite with no network access and confirming nothing attempts an outbound request. Also confirm what the client does on transport failure, since a silent no-op can look identical to success.
- Can I migrate from GA4 to Pirsch and backfill historical data with this package?
- You cannot backfill history through this package, because it is a write-only client that sends new hits to Pirsch rather than importing existing data. The practical approach is to run Pirsch and your current provider in parallel for two to four weeks, reconcile a handful of important pages against the old numbers, then remove the old tag. Expect absolute figures to differ, since bot filtering and attribution models are not the same across vendors.
- Is laravel-pirsch safe to rely on in production?
- It is a thin facade and service provider over the Pirsch PHP SDK, maintained by a small commercial vendor with community involvement, so treat it as an analytics side-channel rather than a system of record. The bigger operational risk is silent data loss: analytics dispatch is fire-and-forget, and swallowed transport errors leave you with a healthy app and empty dashboards. Verify during rollout that hits actually arrive, monitor for gaps, and keep the call sites easy to swap if you ever need to change provider.
Weaver
How can I help you explore Laravel packages today?