amare/app/Http/Middleware/CaptureMarketingOrigin.php

<?php

declare(strict_types=1);

namespace App\Http\Middleware;

use App\Domain\Contact\MarketingOrigin;
use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Log;
use Symfony\Component\HttpFoundation\Response;
use Throwable;

/**
 * Captures the marketing origin (UTM parameters, or the HTTP referrer as
 * a fallback) on the first public page load of a visit and stores it in
 * the session, so it can later travel with a contact briefing submission
 * (SPEC.md WEB-05).
 *
 * First *informative* touch wins: nothing is written until a page load
 * actually carries a UTM parameter or an external referrer, and once
 * that happens later page views never overwrite it — navigating to
 * another page without UTM parameters must not erase what arrived with
 * the visitor. A page load with no signal at all is left unrecorded so a
 * later, informative page load in the same session can still be
 * captured.
 *
 * Fail-open by construction: any failure here is caught and logged
 * without request data, and the request proceeds untouched. This path
 * must never be able to block a page load or, downstream, a conversion.
 */
final class CaptureMarketingOrigin
{
    /**
     * Technical routes that share the `web` middleware group but are never a
     * human arriving at the site. A crawler fetching `/sitemap.xml?utm_source=…`
     * would otherwise consume the first-touch slot with traffic that will never
     * submit a briefing.
     *
     * @var list<string>
     */
    private const IGNORED_ROUTES = ['sitemap', 'robots'];

    public function handle(Request $request, Closure $next): Response
    {
        if (in_array($request->route()?->getName(), self::IGNORED_ROUTES, true)) {
            return $next($request);
        }

        try {
            $this->captureFirstTouch($request);
        } catch (Throwable $exception) {
            Log::warning('Falha ao capturar origem de marketing (ignorada; fail-open)', [
                'exception' => $exception::class,
            ]);
        }

        return $next($request);
    }

    private function captureFirstTouch(Request $request): void
    {
        if (! $request->hasSession()) {
            return;
        }

        $session = $request->session();

        if ($session->has(MarketingOrigin::SESSION_KEY)) {
            return;
        }

        $origin = MarketingOrigin::capture(
            $request->query(),
            $request->headers->get('referer'),
            $request->getHost(),
        );

        if ($origin === []) {
            return;
        }

        $session->put(MarketingOrigin::SESSION_KEY, $origin);
    }
}