Weave Code
Laravel Referer Laravel Package
spatie/laravel-referer
Store a visitor’s original referrer in the Laravel session. Detects from utm_source first, then the external domain from the Referer header, otherwise empty. Configurable session key and referrer sources via published config.
Remember a visitor's original referer
Frequently asked questions about Laravel Referer
- How does spatie/laravel-referer prioritize referrer sources? Can I change the order?
- The package prioritizes `utm_source` query parameters first, then falls back to the external domain from the `Referer` header. You can reorder or disable sources entirely by modifying the `sources` array in the published config file. For example, to prioritize the `Referer` header over UTM, swap their positions in the array.
- Will this package work with Laravel 10+ and PHP 8.1+? Are there breaking changes?
- Yes, the package is fully compatible with Laravel 10+ and PHP 8.1+. Spatie maintains backward compatibility, but always check the [release notes](https://github.com/spatie/laravel-referer/releases) for minor version updates. No breaking changes are expected for major Laravel releases, as it relies on core Laravel features.
- Can I use this for GDPR-compliant tracking? How do I handle user consent?
- The package itself only stores referrer data in the session, which is ephemeral and doesn’t persist beyond the user’s session lifetime. However, you’ll need to implement consent management (e.g., via cookies or explicit opt-in) before storing or processing this data. Combine it with a consent tool like `spatie/laravel-cookie-consent` for full compliance.
- Does this package work with Redis or database session drivers? Any performance concerns?
- Yes, it supports all Laravel session drivers, including Redis and database. Performance impact is minimal since it only writes to the session once per user journey. For high-traffic apps, ensure your session driver is optimized (e.g., Redis with proper eviction policies). Benchmark under load if using database sessions.
- How do I access the stored referrer in my Laravel controllers or views?
- The referrer is stored in the session under the key defined in `config/laravel-referer.php` (default: `referer`). Access it via `session('referer')` in controllers or Blade views. Example: `{{ session('referer') ?? 'direct' }}` for a fallback default value.
- What happens if both UTM and Referer are missing? Can I set a default value?
- If both sources are unavailable, the session key will be empty. You can set a default value (e.g., `'direct'`) when accessing the session data, like `session('referer', 'direct')`. Alternatively, modify the middleware to inject a default via the config or a service provider.
- Is there a way to exclude certain domains (e.g., internal subdomains) from being tracked?
- Yes, you can extend the package by creating a custom referrer source or modifying the existing `RequestHeader` source to filter out unwanted domains. For example, override the `isExternal()` logic in a custom class and add it to the `sources` array in the config.
- How do I test this package in my Laravel application? Are there edge cases to consider?
- Test by simulating requests with and without UTM parameters and `Referer` headers. Use Laravel’s HTTP tests to mock headers and query strings. Edge cases include: subdomains (e.g., `sub.example.com`), malformed UTM params (e.g., `utm_source=`), and missing headers. Validate session persistence across requests.
- Can I integrate this with Google Analytics or other analytics tools?
- Absolutely. The stored referrer can be passed to Google Analytics via the `ga()` helper or custom JavaScript. Example: `ga('set', 'referrer', '@{{ session('referer') }}');`. For other tools, use middleware to inject the referrer into your analytics payload before sending.
- Are there alternatives to this package? When would I choose another?
- Alternatives include custom middleware or packages like `laravel-utm` for UTM-specific tracking. Choose this package if you need a lightweight, configurable solution that combines UTM and Referer logic. Opt for alternatives if you require advanced features like real-time analytics processing or third-party integrations.
Weaver
How can I help you explore Laravel packages today?