ssmiff / mezzio-tenancy
Database-per-tenant multi-tenancy for Mezzio on top of ssmiff/mezzio-doctrine: tenant resolution, runtime connection switching and --tenant on Doctrine commands.
Requires
- php: ~8.5.0
- doctrine/dbal: ^4.2
- laminas/laminas-servicemanager: ^4.5
- psr/container: ^1.1 || ^2.0
- psr/http-factory: ^1.0
- psr/http-message: ^1.1 || ^2.0
- psr/http-server-handler: ^1.0
- psr/http-server-middleware: ^1.0
- ssmiff/mezzio-container-helpers: ^0.1
- ssmiff/mezzio-doctrine: ^0.3
- symfony/console: ^6.4 || ^7.0
- symfony/process: ^6.4 || ^7.0 || ^8.0
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.95
- laminas/laminas-config-aggregator: ^1.18
- laminas/laminas-diactoros: ^3.8
- 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
Database-per-tenant multi-tenancy for Mezzio, built on ssmiff/mezzio-doctrine.
- Finds the tenant of each request (header, subdomain, or your own resolver).
- Points a
tenantconnection and entity manager at that tenant's database for the duration of the request. - Adds
--tenant=<slug>to every Doctrine migrations and ORM console command, andtenancy:migrateto migrate every tenant.
Requires PHP 8.5. Licensed under the MIT licence.
Install
composer require ssmiff/mezzio-tenancy
It depends on ssmiff/mezzio-doctrine and ssmiff/mezzio-container-helpers; laminas-component-installer registers all three config providers.
You also need a PSR-17 ResponseFactoryInterface in the container (Mezzio provides one).
Concepts
- The landlord database holds the list of tenants. It is a normal mezzio-doctrine connection, called
landlordunless you settenancy.landlord_connection, which you define. Tenants are plainTenantvalue objects read and written with DBAL byDbalTenantRepository; no ORM entity or entity manager is involved. Replace it by providing your ownTenantRepository. - Each tenant has its own database. The connection and entity manager for it are both called
tenant. The module defines the connection; you map your tenant entities and migrations onto it. tenantis a dynamic connection: its parameters come from the active tenant, so one name serves every tenant.
Configure
return [ 'doctrine' => [ 'connections' => [ 'landlord' => ['driver' => 'pdo_mysql', 'host' => '...', 'dbname' => 'landlord', 'user' => '...', 'password' => '...'], ], 'entity_managers' => [ 'tenant' => ['mapping' => ['paths' => ['src/Tenant/Entity']]], ], 'migrations' => [ 'connections' => [ 'tenant' => ['migrations_paths' => ['Database\\Migrations\\Tenant' => 'database/migrations/tenant']], ], ], ], 'tenancy' => [ 'landlord_connection' => 'landlord', 'resolvers' => [Ssmiff\MezzioTenancy\Resolver\HeaderResolver::class, Ssmiff\MezzioTenancy\Resolver\SubdomainResolver::class], 'header' => 'X-Tenant', 'base_domain' => 'example.com', 'connection_template' => ['driver' => 'pdo_mysql', 'host' => '...', 'user' => '...', 'password' => '...'], 'required' => true, ], ];
| Key | Meaning |
|---|---|
tenancy.landlord_connection |
the doctrine.connections entry holding the tenants table (default landlord) |
tenancy.resolvers |
resolver service ids, tried in order; the first to name a tenant wins |
tenancy.header |
header read by HeaderResolver (default X-Tenant) |
tenancy.base_domain |
SubdomainResolver takes the single label below it: acme.example.com is tenant acme. Unset disables it |
tenancy.connection_template |
DBAL parameters shared by every tenant; each tenant's own params are merged over them |
tenancy.required |
when true (default) a request with no tenant gets a 404; when false it passes through with no tenant active |
The module itself configures: the tenant connection, the shipped landlord migration, and the console listener.
Another landlord connection name
Name the connection what you like and point tenancy.landlord_connection at it. The landlord migrations follow the
setting, so there is nothing else to register:
return [ 'doctrine' => [ 'connections' => [ 'central' => ['driver' => 'pdo_pgsql', 'host' => '...', 'dbname' => 'central', 'user' => '...', 'password' => '...'], ], ], 'tenancy' => [ 'landlord_connection' => 'central', ], ];
vendor/bin/laminas migrations:migrate --conn=central
Migrations of your own for that connection go under doctrine.migrations.connections.central.migrations_paths as usual;
the landlord migrations are added to them, not replaced.
Setting up the landlord database
vendor/bin/laminas migrations:migrate --conn=landlord # or your landlord_connection
vendor/bin/laminas tenancy:create acme "Acme Ltd" --param=dbname=acme_db
vendor/bin/laminas tenancy:list
A tenant is a slug (lowercase letters, digits, dashes), a name, an active flag and params: the DBAL parameters for its database, merged over connection_template.
Without a provisioner, create the tenant's database yourself (SQLite files are created on first use).
Database credentials live in the landlord table, so protect that database accordingly.
Provisioning tenant storage
Set tenancy.provisioner and tenancy:create creates each tenant's storage, named <prefix><slug> (dashes become
underscores), and saves the parameters that point at it; tenancy:delete --drop destroys it. Three provisioners ship:
A database per tenant (MySQL, MariaDB, PostgreSQL). CREATE DATABASE tenant_acme; the tenant gets dbname:
'tenancy' => [ 'provisioner' => Ssmiff\MezzioTenancy\Provisioning\DatabaseProvisioner::class, 'prefix' => 'tenant_', 'provisioning_connection' => 'admin', // a user allowed to CREATE/DROP DATABASE; null uses the landlord connection 'connection_template' => ['driver' => 'pdo_pgsql', 'host' => 'db', 'user' => 'app', 'password' => '...'], ],
A schema per tenant (PostgreSQL). CREATE SCHEMA tenant_acme in one database; the tenant gets a search_path
of its schema, so its tables and migrations version table live there. provisioning_connection and
connection_template both point at that database:
'tenancy' => [ 'provisioner' => Ssmiff\MezzioTenancy\Provisioning\SchemaProvisioner::class, 'connection_template' => ['driver' => 'pdo_pgsql', 'host' => 'db', 'dbname' => 'app', 'user' => 'app', 'password' => '...'], ],
An SQLite file per tenant. data/tenants/tenant_acme.sqlite; the tenant gets path:
'tenancy' => [ 'provisioner' => Ssmiff\MezzioTenancy\Provisioning\SqliteFileProvisioner::class, 'sqlite_directory' => 'data/tenants', // relative to doctrine.base_path 'connection_template' => ['driver' => 'pdo_sqlite'], ],
Then:
vendor/bin/laminas tenancy:create acme "Acme Ltd" # creates tenant_acme and registers it
vendor/bin/laminas tenancy:migrate --only=acme # builds its tables
vendor/bin/laminas tenancy:delete acme # unregisters it; the data stays
vendor/bin/laminas tenancy:delete acme --drop # unregisters it and destroys tenant_acme (asks for the slug)
tenancy:create --no-provisionregisters the tenant under the same name without creating anything, for storage that already exists.--paramadds or overrides parameters; one that would point away from the created storage needs--no-provision.--dropasks you to type the slug, or takes--force(required when not interactive). It only destroys a tenant whose saved parameters still match what the provisioner would create for it; anything else is refused.- If registering fails after the storage was created, the storage is dropped again.
Your own provisioner
Implement Ssmiff\MezzioTenancy\Provisioning\TenantProvisioner (params(), create(), drop()), register it as a
service and name it in tenancy.provisioner. TenantName::for($prefix, $slug) gives the usual safe name:
final readonly class ManagedDatabaseProvisioner implements TenantProvisioner { public function __construct(private CloudDatabases $api, private string $prefix = 'tenant_') {} public function params(string $slug): array { return ['dbname' => TenantName::for($this->prefix, $slug)]; } public function create(string $slug): void { $this->api->createDatabase(TenantName::for($this->prefix, $slug)); } public function drop(string $slug): void { $this->api->deleteDatabase(TenantName::for($this->prefix, $slug)); } }
| Key | Meaning |
|---|---|
tenancy.provisioner |
service id of the TenantProvisioner; null (default) for none |
tenancy.prefix |
put in front of the slug in storage names (default tenant_); lowercase letters, digits, _ |
tenancy.provisioning_connection |
connection the database and schema provisioners run DDL on (default: the landlord connection) |
tenancy.sqlite_directory |
where SqliteFileProvisioner puts files, relative to doctrine.base_path (default data/tenants) |
Handling requests
Add Ssmiff\MezzioTenancy\Http\TenantMiddleware to the pipeline before routing to tenant routes. For every request it:
- asks the resolvers for a slug (no slug: 404, or pass through when
requiredisfalse), - looks the tenant up in the landlord database (unknown or inactive: 404
{"error":"Unknown tenant"}), - activates it, sets the
Ssmiff\MezzioTenancy\Tenantrequest attribute, runs the handler, then deactivates it.
Inject the tenant database like any other, using the attributes from mezzio-container-helpers:
public function __construct( #[UseEntityManager('tenant')] private EntityManagerInterface $entityManager, ) {}
For handlers built once per request (PHP-FPM), the injected entity manager belongs to that request's tenant.
The tenant services are not shared in the container, so asking the container again always gives the current tenant's.
Custom resolvers
Implement Ssmiff\MezzioTenancy\Resolver\TenantResolver and add its service id to tenancy.resolvers:
final readonly class JwtTenantResolver implements TenantResolver { public function identify(ServerRequestInterface $request): ?string { return /* a slug from a claim, a session, a path segment... */; } }
Running code for a tenant
$switcher->run($tenant, function (Tenant $tenant) use ($registry) { $registry->entityManager('tenant')->persist(...); });
TenantSwitcher::run() activates the tenant, runs the callback, and restores whichever tenant (or none) was active before.
Inside the callback, get the entity manager from the Registry or the container; an object injected earlier still points at the earlier tenant.
From the console: tenancy:run-as
Run any console command with a tenant active. Put -- before the command when it has options of its own:
vendor/bin/laminas tenancy:run-as acme -- app:send-invoices --since=yesterday
vendor/bin/laminas tenancy:run-as acme -- migrations:status
The tenant is active for the whole command, so the command and the services it is built with see the tenant in
TenantContext and get its tenant connection and entity manager; the previous state is restored afterwards. The exit
code is the command's own.
Migrations and ORM commands are given --tenant=<slug> instead, because they pick their connection with --conn
rather than from the active tenant; run-as on them is the same as passing --tenant yourself. Unknown and inactive
tenants are refused. To run a command for every tenant, use a loop in the shell, or tenancy:migrate for migrations.
Console
Every migrations and ORM command gets --tenant=<slug>, which implies --conn=tenant:
vendor/bin/laminas migrations:migrate --tenant=acme
vendor/bin/laminas migrations:diff --tenant=acme
vendor/bin/laminas orm:validate-schema --tenant=acme
--conn=tenant without --tenant, and --tenant with another connection, are errors.
| Command | |
|---|---|
tenancy:create <slug> <name> [--param=key=value ...] [--no-provision] |
register a tenant and, with a provisioner, create its storage |
tenancy:delete <slug> [--drop [--force]] |
unregister a tenant; with --drop, destroy its storage |
tenancy:list |
list tenants |
tenancy:run-as <slug> -- <command> [args...] |
run a console command with the tenant active |
tenancy:migrate [--only=<slug>] |
run migrations:migrate --tenant=<slug> for each active tenant, one process per tenant |
Tenants are migrated in separate processes because Doctrine Migrations keeps one connection per process.
Development
composer install
composer check