Referable Bundle Laravel Package

Getting Started

Install via Composer (composer require <vendor>/<package>) and let Laravel auto-discover the service provider. Publish the config (php artisan vendor:publish --tag=referer-config) and run migrations if the package persists referers. The first use case is capturing the HTTP referer on incoming requests: add the provided middleware to your web group, then resolve RefererManager from the container (now autowirable in v2.0.0) to read the referer for the current request. With v2.0.0, referer values are available immediately in the first request—no need to wait for a follow‑up request—so you can use them during initial page loads or API calls.

Implementation Patterns

• Middleware + session/database: Use the middleware to store the referer in the session for later attribution (e.g., signup forms) or persist it to a referers table via an Eloquent model.
• Dependency injection: Type‑hint RefererManager in controllers, form requests, or services. It exposes methods to get the current referer, previous referer, or raw header value.
• Doctrine integration: If you use Doctrine entities (e.g., with laravel-doctrine/orm), listen to LifecycleEventArgs using the updated namespace (see Gotchas). This lets you attach referer data to entities on persist/update.
• Attribution workflows: Capture referer on landing, store it as a cookie or session key, then associate it with a user on registration or first order. Use the manager to fall back to the Referer header when no session value exists.
• Testing: Fake the manager in tests via $this->mock(RefererManager::class) or set the Referer header on test requests. The v2.0.0 first‑request availability means you can assert referer values in the same request lifecycle.

Gotchas and Tips

• Breaking change – Doctrine namespace: The LifecycleEventArgs class namespace changed in v2.0.0. Update any custom event listeners or subscribers that type‑hint the old namespace (likely Doctrine\ORM\Event\LifecycleEventArgs → Doctrine\Persistence\Event\LifecycleEventArgs). Failing to do so will cause fatal errors.
• Dropped Symfony 4.4 support: This release no longer supports Symfony 4.4 components, which affects older Laravel versions (e.g., Laravel 6/7). Ensure your app runs on Laravel 8+ (Symfony 5.4+) before upgrading.
• Header spoofing: The Referer header is client‑controlled. Sanitize or validate it before storing (e.g., check scheme/host) to avoid open‑redirect or XSS risks.
• Missing referer: Direct traffic sends no Referer. Always handle null gracefully—the manager should return null rather than throwing.
• Middleware order: Register the referer middleware early in the web group (after session start) so the manager has access to the session. If you need it in API routes, add it to the api group separately.
• Config quirks: Check the config file for toggles like enabled, store_in_session, or trusted_hosts. Disabling the middleware in tests may be necessary to avoid side effects.
• Extension points: You can bind a custom implementation of RefererManager in a service provider if you need to alter parsing logic, and you can extend the middleware to add custom storage drivers.