Laravel Referer Laravel Package

Product Decisions This Supports

• Feature Development: Enables tracking user acquisition sources (e.g., marketing campaigns, external links) for analytics, attribution, or personalized onboarding flows.
• Roadmap Alignment: Supports initiatives like A/B testing, referral programs, or cross-platform tracking (e.g., linking mobile/desktop user journeys).
• Build vs. Buy: Avoids reinventing session-based referrer logic; leverages a battle-tested, lightweight solution with minimal maintenance overhead.
• Use Cases:
  • Marketing Analytics: Correlate utm_source with user behavior (e.g., conversion rates, drop-off points).
  • Cross-Device Tracking: Merge session data across devices using the stored referrer as a pivot.
  • Security/Compliance: Log external referrers for fraud detection or GDPR-related data provenance.
  • UX Personalization: Trigger dynamic content (e.g., "You came from [Source]—here’s why we think you’ll like this") based on the referrer.

When to Consider This Package

• Adopt When:
  • Your Laravel app lacks a robust way to persist referrer data across requests (e.g., for analytics or attribution).
  • You prioritize UTM parameter tracking or need to distinguish between internal/external traffic sources.
  • Your team lacks bandwidth to build a custom session-based referrer solution (e.g., middleware + session handling).
  • You’re using Laravel and want a zero-config or minimal-config approach (e.g., no database required).
• Look Elsewhere If:
  • You need real-time referrer data (this stores it in session, not a database or cache).
  • Your use case requires deep link analysis (e.g., parsing complex URLs beyond domain/UTM).
  • You’re already using a dedicated analytics tool (e.g., Google Analytics, Mixpanel) that handles referrers natively.
  • Compliance requires long-term storage of referrer data (session storage is ephemeral).
  • You need multi-platform support (e.g., mobile apps) beyond web.

How to Pitch It (Stakeholders)

For Executives: *"This package lets us reliably track where users come from—whether from a marketing campaign (via UTM tags) or an external link—without building custom infrastructure. It’s a lightweight, open-source solution that plugs into Laravel’s session system, enabling us to:

• Measure campaign effectiveness by linking user behavior to acquisition sources.
• Improve personalization with context-aware onboarding (e.g., ‘Thanks for clicking through from [Source]!’).
• Reduce dev effort by avoiding reinventing session-based tracking logic. It’s MIT-licensed, actively maintained, and used by [X] teams—ideal for scaling our analytics without lock-in."*

For Engineering: *"Spatie’s laravel-referer gives us a drop-in way to persist the original referrer (UTM or Referer header) in the user’s session. Key benefits:

• Zero setup: Just install and use session()->get('referer') anywhere.
• Priority logic: Falls back to UTM params first, then external domains, then empty—no manual parsing needed.
• Laravel-native: Integrates seamlessly with sessions, middleware, or services.
• Lightweight: No database or external dependencies; just ~50 lines of code. Useful for:
• Analytics: Tagging user sessions with acquisition sources.
• Middleware: Redirecting or personalizing content based on referrer.
• Debugging: Logging external traffic sources for security/audit purposes. Downside: Session-bound (not persistent), but we can layer this with a database if needed."*