ssmiff / mezzio-doctrine
Doctrine DBAL, ORM and Migrations for Mezzio with named connections selectable on every console command with --conn.
Requires
- php: ~8.5.0
- doctrine/dbal: ^4.2
- doctrine/migrations: ^3.9
- doctrine/orm: ^3.3
- doctrine/persistence: ^4.0
- laminas/laminas-cli: ^1.10
- laminas/laminas-servicemanager: ^4.5
- psr/cache: ^3.0
- psr/container: ^1.1 || ^2.0
- psr/log: ^3.0
- ssmiff/mezzio-container-helpers: ^0.1
- symfony/cache: ^7.2
- symfony/console: ^6.4 || ^7.0
- symfony/event-dispatcher: ^6.4 || ^7.0
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.95
- phpunit/phpunit: ^11.5
- psalm/plugin-phpunit: ^0.19.5
- squizlabs/php_codesniffer: ^4.0
- symfony/filesystem: ^7.2 || ^8.0
- vimeo/psalm: ^6.13
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Doctrine DBAL, ORM and Migrations for Mezzio, with named connections selectable on every console command via --conn.
vendor/bin/laminas migrations:migrate
vendor/bin/laminas migrations:migrate --conn=reporting
vendor/bin/laminas migrations:generate --conn=reporting
vendor/bin/laminas orm:validate-schema --conn=main
vendor/bin/laminas db:run-sql "SELECT COUNT(*) FROM users" --conn=main
Requires PHP 8.5. Licensed under the MIT licence.
Requires ssmiff/mezzio-container-helpers
The #[UseEntityManager] and #[UseConnection] attributes, AttributeFactory and ConstructorResolver come from
ssmiff/mezzio-container-helpers. This package depends on it, so Composer installs it for you, but its
Ssmiff\MezzioContainerHelpers\ConfigProvider must be registered too, because it provides the ConstructorResolver service that AttributeFactory uses.
laminas-component-installer does that automatically; without it, add the provider to config/config.php before this one.
Both attributes implement the helpers' ParameterSource interface, so your own attributes can be mixed with them.
Install
composer require ssmiff/mezzio-doctrine
laminas-component-installer registers Ssmiff\MezzioDoctrine\ConfigProvider. Commands are exposed through laminas-cli.
Configure
Create one file, config/autoload/doctrine.global.php. Everything goes under the doctrine key.
Step 1: the smallest working setup
One database, entities in src/App/Entity. Copy this and change the connection details:
<?php return [ 'doctrine' => [ 'connections' => [ 'default' => [ 'driver' => 'pdo_mysql', 'host' => 'localhost', 'dbname' => 'my_app', 'user' => 'root', 'password' => 'secret', ], ], 'entity_managers' => [ 'default' => [ 'mapping' => ['paths' => ['src/App/Entity']], ], ], ], ];
That's it. You now have:
- a database connection called
default - an entity manager that reads
#[ORM\Entity]attributes fromsrc/App/Entity - migrations in
database/migrations/default(created for you the first time you run a migrations command)
Try it:
vendor/bin/laminas db:connections
vendor/bin/laminas migrations:status
vendor/bin/laminas db:run-sql "SELECT 1"
Using SQLite? Replace the connection with
['driver' => 'pdo_sqlite', 'path' => 'data/app.sqlite'].Have a URL instead? Use
['url' => 'postgresql://user:pass@host/dbname'].Any option Doctrine DBAL accepts can go in a connection: see the DBAL configuration docs.
Keep passwords out of git. Put the connection in
doctrine.local.php(which Mezzio ignores) or read it from the environment, e.g.'password' => getenv('DB_PASSWORD').
Step 2 (optional): add another database
Give it a name and add it next to default. Here we add reporting:
'connections' => [ 'default' => [/* as before */], 'reporting' => [ 'driver' => 'pdo_pgsql', 'host' => 'reports.internal', 'dbname' => 'reports', 'user' => 'app', 'password' => 'secret', ], ], 'entity_managers' => [ 'default' => ['mapping' => ['paths' => ['src/App/Entity']]], 'reporting' => ['mapping' => ['paths' => ['src/Reporting/Entity']]], ],
Then choose it with --conn on any command:
vendor/bin/laminas migrations:migrate --conn=reporting
vendor/bin/laminas db:run-sql "SELECT * FROM page_views LIMIT 10" --conn=reporting
Its migrations live in database/migrations/reporting by default.
Leave out the entity_managers entry if a database has no entities (for example, you only run migrations or raw SQL against it).
Step 3 (optional): everything else
You only need these if the defaults don't suit you. Each one goes under doctrine.
| I want to... | Add this |
|---|---|
make a connection other than default the default |
'default' => 'reporting' |
| run a quick query against a database | nothing: vendor/bin/laminas db:run-sql "SELECT ..." --conn=<name> (see Running SQL) |
| use the faster in-memory caches while developing | 'dev_mode' => true (put it in doctrine.local.php) |
| log every SQL query | 'logger' => 'my.psr3.logger' inside the connection |
set the PostgreSQL search_path |
'search_path' => ['app', 'public'] inside the connection |
| use XML mapping instead of attributes | 'driver' => 'xml' inside entity_managers.<name>.mapping |
| put migrations somewhere else | see Migrations below |
| rename the migrations version table | see Migrations below |
| add a custom column type | 'types' => ['money' => App\Dbal\MoneyType::class] |
store caches somewhere other than data/cache/doctrine |
'cache_dir' => 'var/cache/doctrine' |
Full reference
Top-level settings (directly under doctrine)
| Key | Default | What it does |
|---|---|---|
connections |
required | Your databases, keyed by name. See below. |
entity_managers |
[] |
ORM settings per database, using the same names. See below. |
migrations |
[] |
Migrations settings. See below. |
default |
'default' |
Which connection is used when you don't pick one. It must exist in connections. |
dev_mode |
false |
true uses in-memory caches, so entity changes are picked up immediately. |
base_path |
current directory | Relative paths (entities, migrations, SQLite files, cache) are resolved from here. |
cache_dir |
'data/cache/doctrine' |
Where metadata/query caches are written when dev_mode is off. |
types |
[] |
Custom DBAL column types, as 'name' => ClassName::class. |
Connection settings (connections.<name>)
Any Doctrine DBAL connection option
(driver, host, port, dbname, user, password, url, path, charset, ...), plus:
| Key | What it does |
|---|---|
logger |
Service id of a PSR-3 logger. Every query is logged to it. |
middlewares |
List of service ids of DBAL middlewares to wrap the connection in. |
params_provider |
Service id of a ParamsProvider that supplies the connection options at runtime instead of config. See Extension points. |
search_path |
PostgreSQL only. A schema name or a list of them, set with SET search_path each time the connection opens. See below. |
search_path
'connections' => [ 'default' => [ 'driver' => 'pdo_pgsql', 'host' => 'db', 'dbname' => 'app', 'user' => 'app', 'password' => '...', 'search_path' => ['tenant_a', 'public'], ], ],
- It is applied by
Ssmiff\MezzioDoctrine\Dbal\SearchPathMiddleware, added after your ownmiddlewaresand thelogger, so they see theSETstatement. It runs on every physical connect, including reconnects, migrations and console commands. - Each name is quoted as an identifier, so write schemas exactly as they are named (
'$user'works too). - A
driverother thanpdo_pgsqlorpgsqlis rejected. With onlydriverClass, it is not checked. - Unqualified
CREATE TABLEgoes into the first schema in the path. That includes the migrations version table. - A
ParamsProvidercan returnsearch_pathfromparams(). That replaces anysearch_pathset next toparams_providerin config, which otherwise still applies. - Behind PgBouncer in transaction pooling mode, a session
SETdoes not reliably stick. UseALTER ROLE ... SET search_paththere instead.
You can also use the middleware directly, for example in your own middlewares list:
new SearchPathMiddleware(['tenant_a', 'public']).
Entity manager settings (entity_managers.<name>)
| Key | Default | What it does |
|---|---|---|
mapping.paths |
[] |
Folders containing your entities. |
mapping.driver |
'attributes' |
How entities are mapped: 'attributes', 'xml', or the service id of your own MappingDriver. |
connection |
same as the entity manager's name | Which connection it uses. |
dev_mode |
top-level dev_mode |
Override dev_mode for just this entity manager. |
cache |
built-in file cache | Service id of a PSR-6 cache pool to use for metadata, query and result caches. |
naming_strategy |
underscore (firstName → first_name) |
Service id of a Doctrine NamingStrategy. |
event_subscribers |
[] |
List of service ids of Doctrine event subscribers. |
Migrations settings (migrations)
With no settings, connection my-db keeps its migrations in database/migrations/my-db, namespace Database\Migrations\MyDb,
and records them in the table doctrine_migration_versions.
To change that, use any Doctrine Migrations option
(migrations_paths, table_storage, all_or_nothing, transactional, check_database_platform, organize_migrations, custom_template), in one of two places:
migrations.defaultsapplies to every connection.migrations.connections.<name>applies to one connection, and wins overdefaults.
'migrations' => [ // every connection: use a different version table name 'defaults' => [ 'table_storage' => ['table_name' => 'migration_versions'], ], // just "reporting": keep its migrations in db/reporting 'connections' => [ 'reporting' => [ 'migrations_paths' => ['Reporting\\Migrations' => 'db/reporting'], ], ], ],
Use
Every connection has an entity manager of the same name.
$registry = $container->get(Doctrine\Persistence\ManagerRegistry::class); $registry->connection(); $registry->connection('reporting'); $registry->entityManager('main'); $registry->getRepository(User::class);
Doctrine\DBAL\Connection and Doctrine\ORM\EntityManagerInterface are registered for the default connection.
Commands
Doctrine's migrations and ORM commands are registered, each accepting --conn=<name>
(on migrations commands --em is a synonym; on ORM commands --conn and --em are the same selector).
| Commands |
|---|
migrations:migrate, :status, :generate, :diff, :list, :execute, :version, :current, :latest, :up-to-date, :rollup, :dump-schema, :sync-metadata-storage |
orm:info, orm:validate-schema, orm:mapping:describe, orm:run-dql, orm:schema-tool:create, :update, :drop, orm:clear-cache:metadata, :query, :result |
db:connections, db:run-sql |
Running SQL
db:run-sql runs one statement on a connection (the default one unless --conn says otherwise). A query prints its
rows as a table; anything else prints how many rows it changed:
vendor/bin/laminas db:run-sql "SELECT slug, name FROM tenants" --conn=landlord
vendor/bin/laminas db:run-sql "UPDATE users SET active = 0 WHERE id = 42"
vendor/bin/laminas db:run-sql "INSERT INTO tags (name) VALUES ('new') RETURNING id" --force-fetch
Statements starting with SELECT, WITH, SHOW, EXPLAIN, DESCRIBE, PRAGMA, VALUES or TABLE count as queries;
--force-fetch shows the rows of anything else. It runs whatever it is given with the connection's full rights.
Commands of your own
A command can take --conn too: add it with ConnectionOption::addTo($command, $registry) and implement
SelectsConnection. The --conn listener checks the name and calls selectConnection() before the command runs;
read the connection from there, not from the input, because Symfony parses the input again after the listeners, which
would undo a listener that changed it (tenancy's --tenant does).
Migrations per connection
Each connection has its own folder, namespace and version table:
| default | |
|---|---|
| directory | database/migrations/<connection>, created on demand |
| namespace | Database\Migrations\<Connection> |
| version table | doctrine_migration_versions |
Override under doctrine.migrations.connections.<name> with the usual migrations_paths and table_storage keys.
Migrations for a connection the app names
A package that ships migrations for a connection whose name the app chooses can't key its config by that name. It
provides a Ssmiff\MezzioDoctrine\Migrations\MigrationsPathsProvider instead, which is asked for the migrations of the
connection being migrated:
use Ssmiff\MezzioContainerHelpers\Attribute\ConfigValue; use Ssmiff\MezzioDoctrine\Migrations\MigrationsPathsProvider; final readonly class AuditMigrations implements MigrationsPathsProvider { public function __construct( #[ConfigValue('audit.connection', 'audit')] private string $connection, ) {} public function migrationsPaths(string $connection): array { return $connection === $this->connection ? ['Acme\\Audit\\Migrations' => __DIR__ . '/../migrations'] : []; } }
and registers it in its ConfigProvider:
'dependencies' => ['factories' => [AuditMigrations::class => AttributeFactory::class]], 'doctrine' => ['migrations' => ['paths_providers' => [AuditMigrations::class]]],
With 'audit' => ['connection' => 'reporting'] in the app's config, migrations:migrate --conn=reporting runs them.
A provider's paths are added to the connection's own migrations_paths (or the defaults); for a namespace both name,
the app's directory wins. ssmiff/mezzio-tenancy supplies its landlord
migrations this way.
migrations:diff needs an entity manager with mappings; on a connection without any it refuses, since the result would drop every table. Use migrations:generate there.
How --conn works
Doctrine's migrations commands are final and read their configuration once. ConnectionOptionListener, a ConsoleEvents::COMMAND
listener provided to laminas-cli as Laminas\Cli\SymfonyEventDispatcher, selects the connection on MigrationsConfigurationLoader or
RegistryEntityManagerProvider before the command runs. A project that defines its own Laminas\Cli\SymfonyEventDispatcher must attach
the listener itself.
Injecting connections and entity managers
The default connection and entity manager are ordinary container services:
public function __construct(private EntityManagerInterface $entityManager) {}
Every named connection and entity manager is a container service too, with ids from ServiceId:
ServiceId::entityManager('reporting') ServiceId::connection('audit')
Better still, the class can say which database it uses on its constructor property, and AttributeFactory (from the helpers package) reads it:
final readonly class RecordPageViewHandler { public function __construct( #[UseEntityManager('reporting')] private EntityManagerInterface $entityManager, ) { } }
'dependencies' => ['factories' => [RecordPageViewHandler::class => AttributeFactory::class]],
#[UseEntityManager('name')] and #[UseConnection('name')] pick the named service; a parameter without an attribute is resolved by its class type
(so a bare EntityManagerInterface is the default entity manager). Without the attribute factory, ConfigAbstractFactory with ServiceId ids does the same from config.
Inject the Registry itself only when the connection is chosen at runtime, for example one database per customer (see Extension points).
Custom factories
UseEntityManager and UseConnection are ParameterSource attributes from
ssmiff/mezzio-container-helpers, which also provides AttributeFactory, #[ConfigValue] and the
ConstructorResolver for factories that need to mix attribute-driven services with values made up in the factory. That package is a dependency of this one.
Development
composer install
composer check
Extension points
Most apps never need these. Use them when the database isn't known until the app is running, for example one database per customer, where the customer is chosen by the request or by a command-line option.
There are three pieces:
| Piece | What it does |
|---|---|
ParamsProvider |
Supplies a connection's settings (host, dbname, ...) from code instead of config. |
Registry::reset($name) |
Throws away a connection and its entity manager, so the next use builds them again, asking the ParamsProvider again. |
console_listeners |
Runs your code before any console command, e.g. to choose the customer before migrations:migrate runs. |
Full example: one database per customer
Every customer has their own database named customer_<id>. The app uses a connection called customer
whose database changes depending on who is being served.
1. Somewhere to store the current customer
namespace App\Customer; final class CurrentCustomer { public ?string $id = null; }
2. A ParamsProvider that builds the connection settings for that customer
namespace App\Customer; use RuntimeException; use Ssmiff\MezzioDoctrine\ParamsProvider; final readonly class CustomerDatabase implements ParamsProvider { public function __construct(private CurrentCustomer $customer) {} public function params(): array { if ($this->customer->id === null) { throw new RuntimeException('No customer selected.'); } return [ 'driver' => 'pdo_mysql', 'host' => 'localhost', 'dbname' => 'customer_' . $this->customer->id, 'user' => 'app', 'password' => 'secret', ]; } }
params() returns exactly what you would otherwise write in doctrine.connections.<name>.
It is called the first time the connection is used, and again after each reset().
3. Config
use App\Customer\CurrentCustomer; use App\Customer\CustomerDatabase; use App\Customer\SelectCustomerFromEnv; use Laminas\ServiceManager\Factory\InvokableFactory; use Ssmiff\MezzioContainerHelpers\Factory\AttributeFactory; return [ 'doctrine' => [ 'connections' => [ 'default' => [/* your normal app database */], 'customer' => ['params_provider' => CustomerDatabase::class], ], 'entity_managers' => [ 'customer' => ['mapping' => ['paths' => ['src/Customer/Entity']]], ], 'console_listeners' => [ SelectCustomerFromEnv::class => 10, // above 0 = runs before --conn is handled ], ], 'dependencies' => [ 'factories' => [ CurrentCustomer::class => InvokableFactory::class, CustomerDatabase::class => AttributeFactory::class, SelectCustomerFromEnv::class => AttributeFactory::class, ], ], ];
logger, middlewares and search_path can still go next to params_provider; every other connection setting comes from params().
For one schema per customer instead of one database, return 'search_path' => [$schema] from params().
4. Use it in a web request
A middleware sets the customer before anything touches the database:
namespace App\Customer; use Psr\Http\Message\ResponseInterface; use Psr\Http\Message\ServerRequestInterface; use Psr\Http\Server\MiddlewareInterface; use Psr\Http\Server\RequestHandlerInterface; final readonly class SelectCustomerMiddleware implements MiddlewareInterface { public function __construct(private CurrentCustomer $customer) {} public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface { $this->customer->id = $request->getHeaderLine('X-Customer-Id'); return $handler->handle($request); } }
Handlers then get the entity manager from the registry when they need it:
$orders = $registry->entityManager('customer')->getRepository(Order::class)->findAll();
With PHP-FPM every request starts fresh, so you don't need reset() here.
On a long-running server (RoadRunner, Swoole, FrankenPHP worker mode), call $registry->reset('customer')
after changing the customer, so the next request doesn't reuse the previous customer's connection.
Inject
Registry, notEntityManagerInterface, into anything that uses thecustomerconnection. Afterreset()an entity manager you were handed earlier is closed and still points at the old database.
5. Use it from the command line
A console listener reads the customer from an environment variable before the command runs:
namespace App\Customer; use Ssmiff\MezzioDoctrine\Console\ConsoleCommandListener; use Symfony\Component\Console\Event\ConsoleCommandEvent; final readonly class SelectCustomerFromEnv implements ConsoleCommandListener { public function __construct(private CurrentCustomer $customer) {} public function __invoke(ConsoleCommandEvent $event): void { $this->customer->id = getenv('CUSTOMER') ?: null; } }
CUSTOMER=42 vendor/bin/laminas migrations:migrate --conn=customer
6. Do something for every customer: reset()
To run work against each customer database in one process, change the customer and reset between them:
foreach (['41', '42', '43'] as $id) { $currentCustomer->id = $id; $registry->reset('customer'); // next line connects to customer_<id> $registry->connection('customer')->executeStatement('UPDATE orders SET archived = 1 WHERE ...'); }
Console listener details
console_listenersmaps a service id to a priority. Each service must implementSsmiff\MezzioDoctrine\Console\ConsoleCommandListener.- Listeners run on Symfony's
ConsoleEvents::COMMAND, before every command. The built-in--connhandling runs at priority 0, so use a priority above 0 if your listener must run first (as above, so the customer is set before the connection is chosen).