Doctrine Context Bundle Laravel Package

Getting Started

kraz/doctrine-context-bundle is a Doctrine integration bundle (Symfony bundle naming) rather than a first-party Laravel package. Start with the package README and its Doctrine context configuration reference, then confirm your app’s Symfony/Doctrine version compatibility before installing with Composer. In a Symfony app, register the bundle and add context configuration; in a Laravel app, expect to wire the relevant Doctrine services manually or use it only where Doctrine DBAL/ORM integration already exists.

The first practical use case is naming Doctrine contexts by tenant, connection, read replica, or domain boundary so SQL/profiler/log output tells you which context executed a query. Release 3.9.15 changes “Context name output style” and bumps dev dependencies only, so treat it as a low-risk presentation change. Begin by running your existing Doctrine-related tests and grepping for assertions or log parsers that depend on exact context-name formatting.

Implementation Patterns

Define contexts close to your Doctrine configuration and keep names stable and meaningful, such as tenant_acme, read_replica, or reporting. Switch context at clear boundaries: HTTP middleware, queued job setup, console command bootstrap, or test setup, and reset it in a finally block or equivalent teardown.

In Laravel, wrap context switching in middleware or a job base class, bind the context manager as a singleton if needed, and reset state between requests/jobs. For long-running workers and Octane-style runtimes, assume context can leak unless explicitly cleared. In Symfony, use the bundle’s service configuration and dependency injection rather than reaching into Doctrine internals directly.

Use fixed context names in tests and assert behaviour rather than exact formatted output where possible. If you snapshot logs, profiler output, or CLI output, update those snapshots for 3.9.15 because the context name output style changed. Keep context names low-cardinality and avoid embedding request IDs or user IDs directly.

For upgrades, the dev-dependency bump should not affect production runtime. Update the lockfile, clear Symfony’s cache/config cache, and verify any output-dependent tooling after upgrading.

Gotchas and Tips

The main 3.9.15 risk is not API breakage but output formatting: log parsers, snapshot tests, dashboards, and regex-based monitoring can break when context names are rendered differently. Search for exact context strings in tests and observability configuration before deploying.

Do not assume Laravel package discovery. The -bundle naming and Symfony-oriented integration mean you may need manual service wiring in Laravel or a separate Symfony deployment. Also clear cached configuration after changing bundle/Doctrine context settings.

Treat context names as identifiers, not free-form messages. Keep them stable, documented, and bounded. Always reset context in long-running processes, queued workers, and test teardown to prevent cross-request contamination. The dev-dependency bump is not a runtime feature; rely on the release’s PR #9 and package tests for the exact output-style change, and use the bundle’s service/config extension points rather than patching internals.