feat: add request context support

.changeset/brave-turkeys-serve.md

@@ -0,0 +1,5 @@
+---
+"posthog-php": minor
+---
+
+Add request context helpers for propagating request metadata and optional PostHog tracing headers.

examples/request-context-laravel-middleware.php

@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Middleware;
+
+use Closure;
+use Illuminate\Http\Request;
+use PostHog\PostHog;
+use Symfony\Component\HttpFoundation\Response;
+
+/**
+ * Laravel HTTP middleware example for PostHog request context.
+ *
+ * Register this middleware in Laravel as usual.
+ */
+final class PostHogRequestContext
+{
+    public function __construct(private ?bool $useTracingHeaders = null)
+    {
+    }
+
+    public function handle(Request $request, Closure $next): Response
+    {
+        $useTracingHeaders = $this->useTracingHeaders ?? (bool) config('posthog.use_tracing_headers', true);
+        $context = $useTracingHeaders
+            ? PostHog::contextFromHeaders($request->headers->all())
+            : [];
+
+        $context['properties'] = array_merge(
+            $context['properties'] ?? [],
+            array_filter(
+                [
+                    '$current_url' => $request->fullUrl(),
+                    '$request_method' => $request->method(),
+                    '$request_path' => $request->getPathInfo(),
+                    '$user_agent' => $request->userAgent(),
+                    '$ip' => $request->ip(),
+                ],
+                static fn($value): bool => $value !== null && $value !== ''
+            )
+        );
+
+        return PostHog::withContext($context, static fn(): Response => $next($request), ['fresh' => true]);
+    }
+}

examples/request-context-symfony-kernel.php

@@ -0,0 +1,63 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\HttpKernel;
+
+use PostHog\PostHog;
+use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\HttpFoundation\Response;
+use Symfony\Component\HttpKernel\HttpKernelInterface;
+
+/**
+ * Symfony HttpKernel decorator example for PostHog request context.
+ *
+ * Register this as a service decorating `http_kernel`. The `$useTracingHeaders`
+ * constructor argument should come from your Symfony bundle/integration config.
+ *
+ * Example services.yaml:
+ *
+ * App\HttpKernel\PostHogRequestContextKernel:
+ *   decorates: http_kernel
+ *   arguments:
+ *     $innerKernel: '@App\HttpKernel\PostHogRequestContextKernel.inner'
+ *     $useTracingHeaders: '%posthog.use_tracing_headers%'
+ */
+final class PostHogRequestContextKernel implements HttpKernelInterface
+{
+    public function __construct(
+        private HttpKernelInterface $innerKernel,
+        private bool $useTracingHeaders = true
+    ) {
+    }
+
+    public function handle(
+        Request $request,
+        int $type = HttpKernelInterface::MAIN_REQUEST,
+        bool $catch = true
+    ): Response {
+        $context = $this->useTracingHeaders
+            ? PostHog::contextFromHeaders($request->headers->all())
+            : [];
+
+        $context['properties'] = array_merge(
+            $context['properties'] ?? [],
+            array_filter(
+                [
+                    '$current_url' => $request->getUri(),
+                    '$request_method' => $request->getMethod(),
+                    '$request_path' => $request->getPathInfo(),
+                    '$user_agent' => $request->headers->get('user-agent'),
+                    '$ip' => $request->getClientIp(),
+                ],
+                static fn($value): bool => $value !== null && $value !== ''
+            )
+        );
+
+        return PostHog::withContext(
+            $context,
+            fn(): Response => $this->innerKernel->handle($request, $type, $catch),
+            ['fresh' => true]
+        );
+    }
+}