Download the PHP package hakam/multi-tenancy-bundle without Composer

Symfony Multi-Tenancy Bundle

The Multi-Tenancy Bundle for Symfony is a convenient solution for incorporating multi-tenant databases in your Symfony application. It simplifies the process of using Doctrine to handle multiple databases with a single entity manager, allowing you to switch between them during runtime.

This bundle comes with a range of features, including the ability to effortlessly switch between tenant databases by triggering an event. Additionally, it supports distinct entity mapping for both the main and tenant entities. It also includes custom extended Doctrine commands for managing tenant databases independently, as well as the capability to generate and execute migrations for each database separately.

In the near future, you will also be able to execute bulk migrations for all tenant databases with a single command. Additionally, the bundle allows you to create and prepare a tenant database if it doesn't already exist

Supported Databases:

• MySQL / MariaDB
• PostgreSQL
• SQLite

Installation

This bundle requires

• Symfony v5+ to run.
• Doctrine Bundle
• Doctrine Migration Bundle v3+ to run

Install using Composer

Using the Bundle

The idea behind this bundle is simple,You have a main database and multi-tenant databases So:

1. Create specific entity witch should implement TenantDbConfigurationInterface. In your main database to save all tenant databases configurations.
2. You can use the TenantDbConfigTrait to implement the full required db config entity fields .
   3. You can use the TimestampableTrait to add createdAt and updatedAt fields to your entity then you should add #[ORM\HasLifecycleCallbacks] attribute to your entity class.
   4. Split your entities in two directories, one for the main database and one for the tenant databases. For example Main and Tenant.
   5. Split the migrations in two directories, one for the main database and one for the tenant databases. For example Main and Tenant.
   6. Update your doctrine config to use the new directories for entities and migrations.See the example below.

You MUST config the default connection and the default entity manager to use the main database. see the example above, for the complete configuration

You just need to update the config for the main EntityManager , Then the bundle will handle the rest for you.

7. Add the TenantEntityManager to your service or controller arguments.
8. Dispatch SwitchDbEvent with a custom value for your tenant db Identifier. Example new SwitchDbEvent(1)
9. You can switch between all tenants dbs just by dispatch the same event with different db identifier.
10. Now your instance from TenantEntityManager is connected to the tenant db with Identifier = 1.
11. It's recommended having your tenant entities in a different directory from your Main entities.

12. You can execute doctrine migration commands using our proxy commands for tenant database.

    php bin/console tenant:database:create   # t:d:c  for short , To create non existing tenant dbs list 
    
    php bin/console tenant:migration:diff    # t:m:d  for short , To generate migraiton for tenant db 
    
    php bin/console tenant:migration:migrate init  # t:m:m init , To run migraitons for  new tenant dbs up to the latest version.
    
    php bin/console tenant:migration:migrate update  # t:m:m update , To run migrations for  all tenant db to the latest version.

    Example

    You can check this project example Multi-Tenant Bundle Example to see how to use the bundle.

Notes:

All the doctrine migration commands and files are generated and executed especially for tenant databases independent of the main db migrations, Thanks for Doctrine migration bundle v3+ .

All the tenant databases migrations will be saved in the same directory you configured for tenant entities.

  Update:  Now you can have different host, username and password for tenant dbs.
  Update:  All tenant databases share the same `dbusername` and `dbpassword` from the selected tenant host.
  Update:  Now you can have different driver for tenant dbs and main db.

Get Started Example

1. After configure the bundle as we mentioned above , you can use the following steps to get started.
2. You need to generate the main database migration with the new entity first. example php bin/console doctrine:migrations:diff
3. Then migrate the main database. example php bin/console doctrine:migrations:migrate
4. Now you are ready to create new tenant databases and switch between them.
5. To create a new tenant database and execute the migration for it. Add the TenantDbConfig entity to your main database. then you can use the following command. example php bin/console tenant:database:create this command will create a new tenant database and execute the migration for it.
6. To switch to a tenant database. example $this->dispatcher->dispatch(new SwitchDbEvent($tenantDb->getId())); then you can use the TenantEntityManager to execute your queries.

7. You can add a relation between your tenant entity and the TenantDbConfig entity to get the tenant db config easily.

8. You can use the custom doctrine commands for tenant databases to perform the same doctrine commands on tenant databases. example php bin/console tenant:migration:diff to generate migration for tenant db. example php bin/console tenant:migration:migrate update to execute migration for all tenant db to the latest version.
9. Now You can work with the TenantEntityManager as you work with the main entity manager.

10. You can now add or delete entities from the main or tenant databases and generate migrations for each database separately.

    Configuration

    In this example below you can find the list of all configuration parameters required witch you should create in config/packages/hakam_multi_tenancy.yaml with this configuration:

Suggested Patterns For Use

User

Store the users current tenant ID in the session or the User entity. This allows you to get the current tenant at any time.

Tenant Interface

Implement an interface on all your tenant entities. This allows you to identify if an entity is associated with a tenant object. Then you can get the current tenant ID from the current user, and switch the entity manager to the tenant DB.

Custom Controller

Extend your base controller class to overwrite some of the normal controller functions for persistence.

Custom Value Resolver

Symfony uses an Entity Value Resolver to load entities associated with parameters passed to controller actions. https://symfony.com/doc/current/controller/value_resolver.html

This resolver is essential to making sure your IsGranted and other Security actions work in the controllers.

Create a custom entity value resolver to switch based on a ReflectionClass of the entity (based on the TenantEntityInterface).

You can copy the value resolver here: https://github.com/symfony/symfony/blob/6.2/src/Symfony/Bridge/Doctrine/ArgumentResolver/EntityValueResolver.php

And modify it to exclude non TenantEntityInterface objects. Then switch DB based on the current user tenant.

Add the value resolver as a service.

Contribution

Want to contribute? Great!

• Fork your copy from the repository
• Add your new Awesome features
• Write MORE Tests
• Create a new Pull request

License

MIT

Free Software, Hell Yeah!