leemason / tenantable
Laravel multi tenancy.
Installs: 784
Dependents: 0
Suggesters: 0
Security: 0
Stars: 81
Watchers: 11
Forks: 27
Open Issues: 3
Requires
- laravel/framework: 5.2.*
Requires (Dev)
- phpunit/phpunit: ~4.0
This package is not auto-updated.
Last update: 2024-10-26 18:49:26 UTC
README
The Laravel Tenantable package is designed to enable multi-tenancy based database connections on the fly without having to access the database ::connection('name')
in every database call.
Installation
Just place require new package for your laravel installation via composer.json
composer require leemason/tenantable
Then hit composer dump-autoload
After updating composer, add the ServiceProvider to the providers array in config/app.php.
You should ideally have this inserted into the array just after the Illuminate\Database\DatabaseServiceProvider::class
to ensure its boot methods is called after the database is available but before any other Service Providers are booted.
Laravel 5.1:
LeeMason\Tenantable\TenantableServiceProvider::class,
Run the migrations
artisan migrate --path /vendor/leemason/tenantable/migrations
Then in your workflow create tenants the Eloquent way:
$tenant = new \LeeMason\Tenantable\Tenant(); $tenant->domain = 'domain.com'; $tenant->driver = 'mysql'; $tenant->host = 'localhost'; $tenant->database = 'domain_com'; $tenant->username = 'root'; $tenant->password = ''; $tenant->prefix = 'prefix'; $tenant->save();
And that's it! Whenever your app is visited via http://domain.com the default database connection will be set with the above details.
Compatibility
The Tenantable package has been developed with Laravel 5.1, i see no reason why it wouldn't work with 5.0 but it is only tested for 5.1 and above.
Introduction
The package simply resolves the correct connection details via the domain accessed via connection details saved in the database.
Once resolved it sets the default database connection with the saved values.
This prevents the need to keep switching, or programatically accessing the right connection depending on the tenant being accessed.
This means all of your routes, models, etc will run on the active tenant database (unless explicitly stated via ::connection('name')
)
Lifecycle
This is how things work during a HTTP request:
- Tenantable copies the name of the default database connection into the
tenantable.database.default
config area. - Tenantable gets the host string via the
Http\Request::getHost()
method. - Tenantable looks for a tenant in the database that match this host.
- If one isn't found, Tenantable looks in the Domains table to find a match (and if found uses eloquent relationships to return the Tenant model.
- When a match is found, the match is saved as the active tenant, and the database details for the tenant are placed in the
database.connections.tenant
config. - Then the default database connection is changed to 'tenant' and the connection purged (disconnected/reconnected).
- The
app.url
config is set the tenants domain. - If a match isn't found in either tables a TenantNotResolved event is fired and no config changes happen.
This is how it works during an artisan console request:
- Tenantable copies the name of the default database connection into the
tenantable.database.default
config area. - Tenantable registers a console option of
--tenant
where you can supply the id,uuid,domain or *,all to run for all tenants. - Tenantable checks to see if the tenant option is provided, if it isn't no tenant is resolved. The command runs normally.
- If a match is found it resolves the tenant (settings the tenant connection details) before excecuting the command.
- If you provide
--tenant
with either a*
or the stringall
Tenantable will run the command foreach tenant found in the database, setting the active tenant before running each time.
The Resolver Class
The \LeeMason\Tenantable\Resolver
class responsible for resolving and managing the active tenant during http and console access.
The TenantableServiceProvider
registers this class as a singleton for use anywhere in your app via method injection, or by using the app('LeeMason\Tenantable\Resolver')
helper function.
This class provides you with methods to access or alter the active tenant:
//fetch the resolver class either via the app() function or by injecting $resolver = app('LeeMason\Tenantable\Resolver'); //check if a tenant was resolved $resolver->isResolved(); // returns bool //get the active tenant model $tenant = $resolver->getActiveTenant(); // returns instance of \LeeMason\Tenantable\Tenant or null //set the active tenant $resolver->setActiveTenant(\LeeMason\Tenantable\Tenant $tenant); // fires a \LeeMason\Tenantable\Events\SetActiveTenantEvent event //purge tenant connection $resolver->purgeTenantConnection(); //reconnect tenant connection $resolver->reconnectTenantConnection();
The Tenant Model
The \LeeMason\Tenantable\Tenant
class is a very simple Eloquent model with some database connection attributes, and a meta attribute which is cast to a Illuminate\Support\Collection
when accessed.
Each attribute (except id,uuid,domain,driver,prefix,meta, and timestamps) are encrypted for security and are decrypted on access, encrypted on save automatically.
Each model instance is assigned a uuid
upon creation, this attribute cannot be set/changed as its a unique id generated for this tenant.
The reason for the uuid is to allow you to use an identifyer for the tenant elsewhere without exposing the tenants id or domain (for example in the filesystem, where you may store tenant specific files in sub folders).
The model can be used in any way other Eloquent models are to create/read/update/delete:
//create by mass assignment \LeeMason\Tenantable\Tenant::create([ 'domain' => 'http://...' .... ]); //call then save $tenant = \LeeMason\Tenantable\Tenant(); $tenant->domain = 'http://...'; ... $tenant->save(); //fetch all tenants $tenant = \LeeMason\Tenantable\Tenant::all(); //fetch by domain $tenant = \LeeMason\Tenantable\Tenant::where('domain', 'http://..')->first();
Events
The Tenantable packages produces a few events which can be consumed in your application
\LeeMason\Tenantable\Events\SetActiveTenantEvent(\LeeMason\Tenantable\Tenant $tenant)
This event is fired when a tenant is set as the active tenant and has a public $tenant
property containing the \LeeMason\Tenantable\Tenant
instance.
Note this may not be as a result of the resolver but is also fired when a tenant is set to active programatically.
\LeeMason\Tenantable\Events\TenantResolvedEvent(\LeeMason\Tenantable\Tenant $tenant)
This event is fired when a tenant is resolved by the resolver and has a public $tenant
property containing the \LeeMason\Tenantable\Tenant
instance.
Note this is only fired once per request as the resolver is responsible for this event.
\LeeMason\Tenantable\Events\TenantNotResolvedEvent(\LeeMason\Tenantable\Resolver $resolver)
This event is fired when by the resolver when it cannot resolve a tenant and has a public $resolver
property containing the \LeeMason\Tenantable\Resolver
instance.
Note this is only fired once per request as the resolver is responsible for this event.
Notes on using Artisan::call();
Using the Artisan
Facade to run a command provides no access to alter the applications active tenant before running (unlike console artisan access).
Because of this the currently active tenant will be used.
To run the command foreach tenant you will need to fetch all tenants using Tenant::all()
and run the Artisan::call()
method inside a foreach after setting the active tenant like so:
//fetch the resolver class either via the app() function or by injecting $resolver = app('LeeMason\Tenantable\Resolver'); //store the current tenant $resolvedTenant = $resolver->getActiveTenant(); //fetch all tenants and loop / call command for each $tenants = \LeeMason\Tenantable\Tenant::all(); foreach($tenants as $tenant){ $resolver->setActiveTenant($tenant); $result = \Artisan::call('commandname', ['array' => 'of', 'the' => 'arguments']); } //restore the correct tenant $resolver->setActiveTenant($resolvedTenant);
If you need to run the Artisan facade on the original default connection (ie not the tenant connection) simply call the Resolver::purgeTenantConnection()
function first:
//fetch the resolver class either via the app() function or by injecting $resolver = app('LeeMason\Tenantable\Resolver'); //store the current tenant $resolvedTenant = $resolver->getActiveTenant(); //purge the tenant from the default connection $resolver->purgeTenantConnection(); //call the command $result = \Artisan::call('commandname', ['array' => 'of', 'the' => 'arguments']); //restore the tenant connection as the default $resolver->reconnectTenantConnection();
The Future
- Add tests
- Add meta items to laravel config