Download the PHP package kraz/doctrine-context-bundle without Composer

Doctrine Context Bundle

A Symfony bundle that makes working with multiple Doctrine entity managers or DBAL connections painless. It wraps the standard Doctrine commands so that a single command can target one specific context or fan out across all of them automatically. The only hard dependency is doctrine/dbal - ORM and Migrations support are both optional.

The problem

When a project has more than one entity manager or DBAL connection, running the same operation across all of them requires repeating the command manually once per context:

There is also a subtle schema-pollution problem: after running migrations, doctrine:schema:update and doctrine:schema:validate see the migration metadata table (e.g. doctrine_migration_versions) as an unmanaged table and report it as something to drop or as a validation error.

What this bundle does

• Database command integration

  The command doctrine:database:create fans out across all registered contexts. Works with DBAL alone - no ORM or Migrations required. Accepts --connection / --conn to target a single context and --connections / --conns to target a specific subset.

• Migrations command integration

  requires doctrine/doctrine-migrations-bundle

  Every doctrine:migrations:* command gains --em / --ems and --conn / --conns options. Pass one to target a single context or a subset, or omit all to run across every registered context in sequence.

• ORM command integration

  requires doctrine/orm

  The doctrine:schema:create, doctrine:schema:validate, and doctrine:mapping:info receive the same fan-out behaviour, including --em / --ems for subset selection.

• Schema filter

  The migration metadata table remains hidden for commands like doctrine:schema:update and doctrine:schema:validate, so those commands never see it as unmanaged.

• Additional command options for every wrapped command

  • --ctx-isolation: When set, a failure in one context does not abort the remaining contexts.
  • --ctx-all: Explicitly runs the command over all registered contexts. Required when explicit_context is enabled and no specific context is given.
  • --ctx-output-style: Control how the context name is being printed to the output.

• Bundle configurations about commands execution behavior

  • explicit_context: When true, every wrapped command requires an explicit context via --em, --ems, --conn, --conns, --connection, --connections, or --ctx-all. Prevents accidental fan-out in production environments.

Requirements

Installation

Register the bundle in config/bundles.php if you are not using Symfony Flex:

Configuration

Register each entity manager or connection that should be treated as a named context. You may use entity_managers (requires doctrine/orm) or connections, but not both for the same name.

The migration-related options (migrations_paths, storage, services, etc.) are only available when doctrine/doctrine-migrations-bundle is installed. Without it, a context is configured with just its name.

DBAL only (no ORM, no Migrations)

With DBAL connections and Migrations

With entity managers (ORM) and Migrations

With entity managers (ORM), no Migrations

Requiring explicit context selection

Set explicit_context: true to prevent any wrapped command from fanning out over all contexts unless the caller deliberately opts in with --ctx-all. Every invocation must target a specific context or pass --ctx-all explicitly, making accidental mass operations impossible.

With this option active, the following is an error:

Provide a context or opt into all:

Full configuration reference

The migration-related keys below are only accepted when doctrine/doctrine-migrations-bundle is installed.

Usage

Run migrations for all contexts

Omitting --em / --conn fans the command out across every registered context:

Output will be grouped by context:

Target a specific context

Target a subset of contexts

Use the plural form of each option to pass multiple context names. Values can be supplied as separate arguments or as a comma-separated list - both forms are equivalent and may be combined:

Continue past failures with --ctx-isolation

By default, a failure in one context stops execution when executed in non-interactive mode. Use --ctx-isolation to continue with the remaining contexts regardless:

Run over all contexts explicitly with --ctx-all

--ctx-all behaves identically to omitting a specific context (fans out over every registered context), but makes the intent explicit. It is required when explicit_context: true is configured and no specific context is given:

Create databases

All supported commands

Always available (DBAL only):

When doctrine/doctrine-migrations-bundle is installed:

When doctrine/orm is installed:

Schema filter

When doctrine/doctrine-migrations-bundle is installed, the bundle automatically registers a DBAL schema filter per context that hides the migration metadata table from doctrine:schema:update and doctrine:schema:validate. This prevents those commands from flagging the migration table as an unmanaged or extra table.

The filter activates only during schema update/validate commands and is otherwise transparent.

Acknowledgements

The idea behind this bundle is credited to DoctrineMigrationsMultipleDatabaseBundle which was heavily refactored to support Symfony 8 and some functional enhancements.

License

This bundle is licensed under the MIT License. See the LICENSE file for details.