Tenancy Bundle

Multi-tenancy for Symfony. Zero boilerplate, zero leaks.

Documentation · Runnable demo · Changelog · Roadmap · Upgrade guide

Resolve a tenant once at the edge of the request — every Symfony subsystem reconfigures itself for the rest of the lifecycle.

• The DBAL connection switches to the tenant's database (or the Doctrine SQL filter scopes every query)
• Cache pools namespace by tenant
• The Mailer transport swaps to the tenant's SMTP/DSN
• The Flysystem filesystem scopes each tenant's uploads
• Messenger envelopes stamp the active tenant and re-boot it on the consumer side
• Your code stays tenant-unaware:

// Controller — no $tenantId parameter, no manual filtering, no leaks
public function index(InvoiceRepository $repo): Response
{
    return $this->render('invoice/index.html.twig', [
        'invoices' => $repo->findAll(),  // automatically scoped to the active tenant
    ]);
}

That's it. The event-driven kernel extension does the rest.

Why this exists

Laravel has stancl/tenancy. Symfony users have been writing their own glue for years — manual $tenantId parameters, leaked queries discovered in production, half-built abstractions that don't compose with Doctrine + Messenger + Cache + Mailer at the same time. This bundle treats tenancy as a first-class kernel extension, not a database switcher bolted on top.

Quality signals

• PHPStan level 9 clean — no @phpstan-ignore, no mixed shortcuts
• 970 tests / 3,830 assertions across the unit + integration suites
• CI matrix: PHP 8.2 / 8.3 / 8.4 × Symfony 7.4 / 8.0 / 8.1, plus prefer-lowest, "No Doctrine", "No Messenger", and a composer audit supply-chain gate
• demo-smoke live-stack gate: every push to master rebuilds the three-tenant FrankenPHP + Caddy + MariaDB demo and exercises tenant isolation end-to-end via bin/smoke.sh (~90s)
• ASVS-L1 threat model per phase, security gate before phase verification
• Strict mode on by default — a missing tenant on a #[TenantAware] entity is an exception, not silent data leakage

Install

composer require danplaton4/tenancy-bundle

Register the bundle in config/bundles.php, then run bin/console tenancy:init to scaffold config/packages/tenancy.yaml.

One-shot setup: bin/console tenancy:install handles both steps in a single command. It uses nikic/php-parser to AST-edit config/bundles.php safely — install as a dev dependency first: composer require --dev nikic/php-parser. Without it the command exits 1 with a clear error and prints the manual snippet to paste.

Configure (config/packages/tenancy.yaml):

tenancy:
    driver: database_per_tenant   # or shared_db
    database:
        enabled: true

Mark tenant-scoped entities (shared-DB mode only):

use Tenancy\Bundle\Attribute\TenantAware;

#[ORM\Entity]
#[TenantAware]
class Invoice { /* ... */ }

That's the minimum. See the Documentation for resolver options, custom bootstrappers, Messenger integration, testing, and the contributor guide.

Try the demo

A runnable three-tenant Symfony app lives under examples/saas/:

git clone https://github.com/danplaton4/tenancy-bundle.git
cd tenancy-bundle/examples/saas
docker compose up -d --wait --build           # ~30s warm, ~110s cold
open http://acme.tenancy.localhost/           # or curl -H 'Host: acme.tenancy.localhost' http://localhost/

Three tenants (acme, globex, initech) + a landlord page, FrankenPHP + Caddy + MariaDB 11, with the Profiler tab and Mailpit always-up. If host ports 80 / 8025 are already taken on your machine, override:

PORT_HTTP=8081 PORT_MAILPIT_UI=8026 docker compose up -d --wait --build
BASE_PORT=8081 bash bin/smoke.sh              # DNS-independent isolation proof

See examples/saas/README.md for the full walkthrough — three-step fallback ladder (curl Host: → /etc/hosts → browser-native *.localhost), Mailpit + Profiler walkthroughs, CI gate details.

Features

Isolation

• Database-per-tenant — DBAL connection switches at runtime per tenant via TenantDriverMiddleware, no wrapper_class config required
• Shared-database — Doctrine SQL filter with the #[TenantAware] attribute; zero manual query scoping; strict-mode by default

Per-tenant subsystems (bootstrappers)

• Cache namespace isolation — per-tenant cache pool prefixing, no cross-tenant bleed
• Mailer — per-tenant SMTP DSN + From + Reply-To headers, sync + async safe via the X-Transport strategy
• Filesystem (Flysystem) — per-tenant storage in prefix mode (default) or a per-tenant adapter for S3-style separation
• Messenger context propagation — TenantStamp on every envelope, re-booted on consume; works under sync and async transports

Data sharing

• Shared entities (#[Shared]) — landlord-side master records replicate to a tenant-side read-only copy via Doctrine events, with opt-in async fan-out over Messenger and a compile-time #[Shared] ⊕ #[TenantAware] mutual-exclusion guard. tenancy:shared:resync for bulk/initial sync.

Operations & scale

• Maintenance mode — per-tenant HTTP 503 + Retry-After, IP/route/path allow-list bypass, optional Twig template; tenancy:maintenance:enable|disable|status. Other tenants and the landlord keep serving.
• Health checks — GET /_tenancy/health/live + /_tenancy/health/ready/{slug} in IETF application/health+json, a bounded fleet dashboard, and a tenancy:health CLI. Optional liip/monitor-bundle auto-registration. Every response is DSN-redacted.
• Parallel migrations — tenancy:migrate --parallel runs per-tenant migrations concurrently through a bounded subprocess pool (--concurrency, --dry-run, --format=json); the no-flag path stays sequential.

Resolution & DX

• 5 built-in resolvers — Host (subdomain), Origin header (SPA-friendly, allow-listed), X-Tenant-ID header, query param, CLI --tenant flag. Chain in any order via config; add your own.
• CLI commands — tenancy:install (one-shot setup), tenancy:init (scaffold config), tenancy:migrate (per-tenant, --parallel), tenancy:run (wrap any command in tenant context), plus the maintenance, health, and shared:resync commands above
• Symfony Profiler tab — "Tenancy" panel in the WDT showing slug, label, driver, resolver, bootstrappers, error state. Auto-registered when kernel.debug=true, compile-stripped in prod
• PHPStan extension — three consumer-facing static rules (tenancy.mutualExclusion, tenancy.sharedEntityLeak, tenancy.tenantIdDrift) auto-loaded via phpstan/extension-installer
• PHPUnit testing trait — InteractsWithTenancy sets up a clean tenant DB/schema per test method, real SQLite, no mocks
• Custom entity support — extend AbstractTenant (MappedSuperclass) to add columns like brandColor, plan, billingId without breaking Doctrine inheritance

How it works

The bundle hooks into the Symfony kernel via a kernel.request listener at priority 20 (above Security at 8, below Router at 32). A resolver chain identifies the tenant from the request. Once resolved, BootstrapperChain runs every registered bootstrapper to reconfigure its subsystem. On kernel.terminate, tenant context is cleared.

Request → Router → TenantContextOrchestrator (priority 20)
                         │
                   ResolverChain
                   (Host / Origin / Header / QueryParam / Console)
                         │
                   TenantResolved event
                         │
                   BootstrapperChain.boot()
                    ├─ DatabaseSwitchBootstrapper
                    ├─ DoctrineBootstrapper
                    ├─ CacheBootstrapper
                    ├─ MailerBootstrapper
                    └─ FilesystemBootstrapper
                         │
                   TenantBootstrapped event
                         │
                     Controller runs
                         │
                   kernel.terminate
                         │
                   TenantContextCleared event

Bootstrappers are Symfony services tagged with tenancy.bootstrapper — add your own by implementing TenantBootstrapperInterface and tagging the service. No bundle internals to modify. See the Custom Bootstrapper guide.

Comparison

Philosophy

A data leak across tenants is a security incident, not a config mistake — so strict mode is on by default. Opt out explicitly if you understand the trade-off.

The bundle is a kernel extension, not just a database switcher: every Symfony subsystem (database, cache, queue, mailer, filesystem) participates in the tenant lifecycle through the same event-driven bootstrapper model. Doctrine is treated as an optional dependency — every entry point is guarded by class_exists / interface_exists, so the bundle installs cleanly into a Symfony app that doesn't use Doctrine at all.

Requirements

• PHP ^8.2
• Symfony ^7.4, ^8.0, or ^8.1
• Optional: doctrine/orm ^3, doctrine/dbal ^4, doctrine/migrations, symfony/messenger, symfony/mailer, league/flysystem-bundle, liip/monitor-bundle

Documentation

The full docs site is published from docs/ to https://danplaton4.github.io/tenancy-bundle/.

Highlights:

• Getting started
• Database-per-tenant guide
• Shared-DB guide
• Cache isolation
• Messenger integration
• Origin-header resolver (SPA)
• Profiler tab
• Testing with InteractsWithTenancy
• Operations: maintenance mode · health checks · parallel migrations
• Architecture (contributor guide)

Roadmap

See the roadmap on the documentation site for what's shipping next and what's tracked-but-unscheduled. Open a GitHub issue if you want something prioritized — real demand is the single strongest input to the next milestone's scope.

Contributing

See CONTRIBUTING.md. Bug reports, design discussions, and PRs are all welcome — the bundle is small enough that the first contributor read of the code can land a real change in a single session.

License

MIT License. See LICENSE.