Context Laravel Package

Technical Evaluation

Architecture Fit

• Immutable, execution-scoped context propagation aligns perfectly with Laravel’s middleware stack, async workers (Swoole/fibers), and event-driven architectures (Laravel Echo, ReactPHP). The package’s design mirrors OpenTelemetry’s specification for context, ensuring compatibility with distributed tracing systems.
• Baggage support enables attaching custom metadata (e.g., tenant_id, user_id) to traces, which is critical for Laravel’s multi-tenant and user-specific workflows. This integrates seamlessly with Laravel’s existing request()->user() or auth()->tenant() patterns.
• Fiber and event-loop support is a game-changer for Laravel apps using Swoole, Amp, or ReactPHP, where manual context management in callbacks is error-prone. The bindContext() utility abstracts this complexity, reducing boilerplate.
• Middleware integration: The package’s implicit propagation model fits Laravel’s middleware pipeline (Kernel.php), where each request naturally inherits and propagates context through the stack.

Integration Feasibility

• Low-risk for synchronous Laravel apps: The core Context::activate()/detach() pattern can be adopted incrementally in middleware, services, or repositories without disrupting existing flows.
• Async Laravel (Swoole/fibers): Requires enabling OTEL_PHP_FIBERS_ENABLED and preloading vendor/autoload.php (for non-CLI SAPIs). This is a one-time configuration change with minimal runtime overhead.
• Event loops (ReactPHP/Amp): The bindContext() helper provides a drop-in solution for wrapping callbacks, though custom event loop integrations may need adjustments for performance-sensitive use cases.
• Queue workers (Horizon/Swoole): Context propagation across job dispatches and retries is automatic with proper setup, eliminating the need for manual trace ID passing in job payloads.

Technical Risk

Key Questions

1. Async Strategy:

   • Are we using Swoole, fibers, ReactPHP, or Amp? If yes, how will we test context propagation under load?
   • Do we need custom event loop integrations, or will bindContext() suffice?

2. Observability Backend:

   • Which OpenTelemetry-compatible backend (Jaeger, Datadog, Lightstep) will we use? Are there proprietary extensions needed?
   • How will we correlate traces with Laravel’s existing logging (Monolog, Sentry)?

3. Laravel Ecosystem:

   • Which components (HTTP, queues, WebSockets, CLI) need instrumentation first? Prioritize based on debugging pain points.
   • How will we sync baggage (e.g., tenant_id) with Laravel’s auth/tenant systems?

4. Performance:

   • What is the acceptable overhead for context propagation? Benchmark in staging.
   • Will fiber/event loop integrations meet latency requirements (e.g., real-time WebSockets)?

5. Compliance:

   • Do we need traceable user actions for GDPR/PCI DSS? If so, how will baggage map to Laravel’s data models?
   • Are there audit requirements for trace retention or export?

6. Team Readiness:

   • Does the team have OpenTelemetry experience, or will training be needed?
   • How will we monitor context propagation in production (e.g., dropped traces, leaks)?

Integration Approach

Stack Fit

• Laravel Core:

  • Middleware: Wrap Context::activate()/detach() around the middleware pipeline to propagate traces for HTTP requests.
  • Service Container: Bind Context to Laravel’s container for dependency injection (e.g., app(Context::class)).
  • Request/Response: Use Context::getBaggage() to attach/detach metadata (e.g., request()->attributes ↔ baggage).

• Async Laravel:

  • Swoole/Fibers: Enable OTEL_PHP_FIBERS_ENABLED and preload autoload.php. Test with Swoole\Coroutine or PHP fibers.
  • Event Loops: Integrate bindContext() with ReactPHP/Amp loops. For custom loops, implement Context::getCurrent() restoration.
  • Queues: Propagate context across job dispatches using Context::storeInBaggage() and Context::extractFromBaggage().

• HTTP Clients:

  • Guzzle/Symfony HTTP Client: Use OpenTelemetry’s Propagator to inject/extract trace context in headers.
  • Laravel HTTP Client: Extend the client to auto-propagate context via middleware.

• CLI/Artisan:

  • Wrap Artisan::command() in Context::activate() to trace CLI workflows (e.g., php artisan queue:work).

• WebSockets:

  • Instrument Laravel Echo/Pusher to propagate context in event payloads (e.g., authenticate middleware).

Migration Path

Compatibility

• Laravel Versions:
  • Supported: Laravel 9+ (PHP 8.1+). Laravel 8 may work but lacks fiber support.
  • Legacy: Laravel 7/