Symfony Runtime Context Bundle Laravel Package

Getting Started

1. Install: composer require tourze/symfony-runtime-context-bundle.
2. Register the bundle (if not auto-discovered) in config/bundles.php:

   Tourze\Symfony\RuntimeContextBundle\RuntimeContextBundle::class => ['all' => true],
   

3. Look first at README.md and src/ — specifically the bundle class, the context service interface, and any compiler pass. The public service ID is what you'll inject everywhere else.
4. First use case: stash per-request values (tenant ID, request ID, trace ID, authenticated user reference) in a runtime context during a listener/middleware, then read them from services that can't cheaply receive them via constructor injection (log processors, domain services, third-party SDK adapters).

Note on 1.0.1: the release notes only link the GitHub compare (1.0.0...1.0.1). Treat this as a patch bump. Read the diff at the link before adopting, and pin ^1.0 rather than an exact version while you validate.

Laravel caveat: this is a Symfony bundle, not a Laravel package. It is not auto-discovered by Laravel and has no service provider. In a Laravel app you have three realistic options:

• Use the underlying context library directly and skip the bundle.
• Bridge it manually by instantiating/bootstrapping the bundle inside a custom ServiceProvider.
• Keep it out of Laravel and use it only where the Symfony kernel is actually present.

For plain PHP (non-framework) usage, check whether the context class is usable standalone — that is usually the cleanest port.

Implementation Patterns

• Set-once, read-anywhere middleware/listener. Populate the context early (before the controller), e.g. from a kernel.request listener or Laravel middleware. Everything downstream reads from the injected context service.
• Inject, don't reach for globals. Constructor-inject the context service into consumers. If you're tempted to use a static/facade, wrap it in a small adapter so tests can substitute a fake.
• Log enrichment. Register a Monolog processor that pulls the context and merges it into extra. This is usually the highest-value integration and the reason teams install a context bundle.
• Tracing correlation. Push trace_id/span_id into the context at the request boundary; emit them in every log line and error report. Pairs cleanly with OpenTelemetry.
• Decorator pattern for legacy code. Instead of threading a RequestContext argument through dozens of constructors, decorate the few entry-point services and set context there.
• Test seeding. In setUp(), clear and seed the context with fixtures. Assert against a fake or against the real service if it's cheap. Always clear in tearDown().
• Reset per request. In long-running runtimes (Octane, RoadRunner, FrankenPHP, Swoole), explicitly reset the context at the start/end of each request so state cannot bleed.

Gotchas and Tips

• Symfony/Laravel mismatch. Do not assume composer require "just works" in Laravel. Confirm a service provider exists or write a bridge; otherwise Symfony's container wiring will never run.
• Context leakage in long-running workers. This is the classic failure mode. A singleton context survives between requests under Octane/RoadRunner. Wire an explicit reset and test it with two consecutive requests.
• Cross-test contamination. If the context is a shared service, one test can poison the next. Clear it in tearDown() unconditionally.
• Autowiring surprises. If the context service is private or aliased under a non-obvious ID, __construct(RuntimeContext $ctx) will fail with "cannot autowire." Check services.yaml / the bundle's extension for the alias and bind to the interface.
• Patch-release opacity. 1.0.1's changelog is only a compare link. Diff 1.0.0...1.0.1 before bumping in production; patch releases on young bundles sometimes carry small API or container-config tweaks. Pin ^1.0 and run your test suite against the bump.
• Extension points to look for: custom context providers (register via tag), the Monolog processor (enable/disable per env), and any compiler pass that lets you swap the storage backend. Configure these rather than editing vendor code.
• Env-specific config. Monolog processors and per-request listeners are commonly gated to prod/dev. Double-check the bundle doesn't auto-register a processor in test, or assertion output gets noisy.
• Don't put large or sensitive payloads in context. Treat it as identifiers and scalars; avoid embedding the full user model or credentials, since it can end up serialized into logs and traces.