This is where your description should go. Limit it to a paragraph or two. Consider adding a small example.
You can install the package via composer:
composer require michaelnabil230/laravel-multi-tenancyYou can publish and run the migrations with:
php artisan multi-tenancy:installThis is the contents of the published config file:
use MichaelNabil230\MultiTenancy\Events;
use MichaelNabil230\MultiTenancy\Listeners;
return [
/**
* NameServer of the server for ex:'ns1.contabo.net'.
*/
'name_server' => null,
/**
* The list of domains hosting your central app.
*
* Only relevant if you're using the domain or subdomain identification middleware.
*/
'central_domains' => [
'127.0.0.1',
'localhost',
],
/*
* These fields are used by tenant:artisan command to match one or more tenant
*/
'artisan_search_fields' => [
'id',
],
/**
* All events for tenancy
*/
'events' => [
// Tenant events
Events\Tenant\CreatingTenant::class => [],
Events\Tenant\TenantCreated::class => [
Listeners\SeedDatabase::class,
],
Events\Tenant\SavingTenant::class => [],
Events\Tenant\TenantSaved::class => [],
Events\Tenant\UpdatingTenant::class => [],
Events\Tenant\TenantUpdated::class => [],
Events\Tenant\DeletingTenant::class => [],
Events\Tenant\TenantDeleted::class => [],
// Domain events
Events\Domain\CreatingDomain::class => [],
Events\Domain\DomainCreated::class => [],
Events\Domain\SavingDomain::class => [],
Events\Domain\DomainSaved::class => [],
Events\Domain\UpdatingDomain::class => [],
Events\Domain\DomainUpdated::class => [],
Events\Domain\DeletingDomain::class => [],
Events\Domain\DomainDeleted::class => [],
// DataBase events
Events\DataBase\SeedingDatabase::class => [],
Events\DataBase\DatabaseSeeded::class => [],
// Tenancy events
Events\Tenancy\InitializingTenancy::class => [],
Events\Tenancy\TenancyInitialized::class => [
Listeners\BootstrapTenancy::class,
],
Events\Tenancy\EndingTenancy::class => [],
Events\Tenancy\TenancyEnded::class => [
Listeners\RevertToCentralContext::class,
],
Events\Tenancy\BootstrappingTenancy::class => [],
Events\Tenancy\TenancyBootstrapped::class => [],
Events\RevertingToCentralContext::class => [],
Events\RevertedToCentralContext::class => [],
],
/**
* Tenancy bootstrappers are executed when the tenancy is initialized.
* Their responsibility is making Laravel features tenant-aware.
*
* To configure their behavior, see the config keys below.
*/
'bootstrappers' => [
MichaelNabil230\MultiTenancy\Bootstrappers\CacheTenancyBootstrapper::class,
MichaelNabil230\MultiTenancy\Bootstrappers\FilesystemTenancyBootstrapper::class,
MichaelNabil230\MultiTenancy\Bootstrappers\QueueTenancyBootstrapper::class,
// MichaelNabil230\MultiTenancy\Bootstrappers\RedisTenancyBootstrapper::class, // Note: phpredis is needed
],
/**
* Redis tenancy config. Used by RedisTenancyBootstrapper.
*
* Note: You need phpredis to use Redis tenancy.
*
* Note: You don't need to use this if you're using Redis only for the cache.
* Redis tenancy is only relevant if you're making direct Redis calls,
* either using the Redis facade or injecting it as a dependency.
*/
'redis' => [
'prefix_base' => 'tenant', // Each key in Redis will be prepended by this prefix_base, followed by the tenant id.
'prefixed_connections' => [ // Redis connections whose keys are prefixed, to separate one tenant's keys from another.
// 'default',
],
],
/**
* Cache tenancy config. Used by CacheTenancyBootstrapper.
*
* This works for all Cache facade calls, cache() helper
* calls and direct calls to injected cache stores.
*/
'cache_prefix_key' => 'tenant_id_',
/**
* The session key Middleware in `ScopeSessions`
*/
'session_key' => 'ensure_valid_tenant_session_tenant_id',
/**
* Filesystem tenancy config. Used by FilesystemTenancyBootstrapper.
*/
'filesystem' => [
/**
* Each disk listed in the 'disks' array will be suffixed by the suffix_base, followed by the tenant_id.
*/
'suffix_base' => 'tenant',
'disks' => [
'local',
'public',
// 's3',
],
/**
* Use this for local disks.
*/
'root_override' => [
// Disks whose roots should be override after storage_path() is suffixed.
'local' => '%storage_path%/app/',
'public' => '%storage_path%/app/public/',
],
/**
* Should storage_path() be suffixed.
*
* Note: Disabling this will likely break local disk tenancy. Only disable this if you're using an external file storage service like S3.
*
* For the vast majority of applications, this feature should be enabled. But in some
* edge cases, it can cause issues (like using Passport with Vapor - see #196), so
* you may want to disable this if you are experiencing these edge case issues.
*/
'suffix_storage_path' => true,
/**
* By default, asset() calls are made multi-tenant too. You can use mix()
* for global, non-tenant-specific assets. However, you might have some issues when using
* packages that use asset() calls inside the tenant app. To avoid such issues, you can
* disable asset() helper tenancy and explicitly use tenant_asset() calls in places
* where you want to use tenant-specific assets (product images, avatars, etc).
*/
'asset_helper_tenancy' => true,
],
/**
* Features are classes that provide additional functionality
* not needed for the tenancy to be bootstrapped. They are run
* regardless of whether the tenancy has been initialized.
*
* See the documentation page for each class to
* understand which ones you want to enable.
*/
'features' => [
// MichaelNabil230\MultiTenancy\Features\TelescopeTags::class,
// MichaelNabil230\MultiTenancy\Features\TenantSetting::class,
],
/**
* Parameters used by the db:seed command.
*/
'seeder_parameters' => [
'--class' => 'TenantDatabaseSeeder',
'--force' => true,
],
/**
* Subscription for Tenant
*/
'subscription' => [
/**
* Enable if you need tenant has subscription in your application
*/
'enable' => false,
/**
* Route for the subscription index
*/
'route' => null,
/**
* All events for subscription
*/
'events' => [
// Subscription events
Events\Subscription\SubscriptionCreated::class => [],
Events\Subscription\SubscriptionUpdated::class => [],
Events\Subscription\SubscriptionCancelled::class => [],
Events\Subscription\SubscriptionChangePlan::class => [],
Events\Subscription\SubscriptionRenewed::class => [],
Events\Subscription\SubscriptionResume::class => [],
],
],
];The package is highly configurable. This page covers what you can configure in the config/multi-tenancy.php file, but note that many more things are configurable. Some things can be changed by extending classes (e.g. the Tenant model), and many things can be changed using static properties. These things will usually be mentioned on the respective pages of the documentation, but not every time. For this reason, don't be afraid to dive into the package's source code — whenever the class you're using has a public static property, it's intended to be configured.
You can set static properties like this (example):
\MichaelNabil230\MultiTenancy\MultiTenancy::$onFail = function () {
return redirect('https://my-central-domain.com/');
};A good place to put these calls is your app/Providers/TenancyServiceProvider's boot() method.
MultiTenancy::tenant();
// Can be change with the pass model name.
MultiTenancy::useTenantModel(Model::class);This config specifies what Tenant model should be used by the package. There's a high chance you're using a custom model,
as instructed to by the [Tenants], so be sure to change it in the config.
MultiTenancy::domain();
// Can be change with the pass model name.
MultiTenancy::useDomainModel(Model::class);Similar to the Tenant model config. If you're using a custom model for domains, change it in this config. If you're not using domains (e.g. if you're using path or request data identification) at all, ignore this config key altogether.
multi-tenancy.central_domains
The list of domains that host your [central app]. This is used by (among other things):
- the
InitializeTenancyBySubdomainmiddleware, to check whether the current hostname is a subdomain on one of your central domains.
multi-tenancy.bootstrappers
This config array lets you enable, disable or add your own [tenancy bootstrappers]
multi-tenancy.cache.*
This section is relevant to cache separation, specifically, to the CacheTenancyBootstrapper.
Note: To use the cache separation, you need to use a cache store that supports tagging, which is usually Redis.
See this section in the config, it's documented with comments.
multi-tenancy.filesystem.*
This section is relevant to storage separation, specifically, to the FilesystemTenancyBootstrapper.
See this section in the config, it's documented with comments.
multi-tenancy.redis.*
This section is relevant to Redis data separation, specifically, to the RedisTenancyBootstrapper.
Note: To use the this bootstrapper, you need phpredis.
See this section in the config, it's documented with comments.
multi-tenancy.features
This config array lets you enable, disable or add your own [feature classes]
multi-tenancy.seeder_parameters
The same as migration parameters, but for tenants:seed and the SeedDatabase job.
This package is heavily based around events, which makes it incredibly flexible.
By default, the events are configured in such a way that the package works like this:
- A request comes in for a tenant route and hits an identification middleware
- The identification middleware finds the correct tenant and runs
$this->tenancy->initialize($tenant);- The
MichaelNabil230\MultiTenancy\Tenancyclass sets the$tenantas the current tenant and fires aTenancyInitializedevent - The
BootstrapTenancyclass catches the event and executes classes known as [tenancy bootstrappers]. - The tenancy bootstrappers make changes to the application to make it "scoped" to the current tenant. This by default includes:
- Switching the database connection
- Suffixing filesystem paths
- Making queues store the tenant id & initialize tenancy when being processed
Again, all of the above is configurable. You might even disable all tenancy bootstrappers, and just use tenant identification and scope your app manually around the tenant stored in MichaelNabil230\MultiTenancy\Tenancy. The choice is yours.
This package comes with a very convenient service provider that's added to your application when you install the package. This service provider is used for mapping listeners to events specific to the package and is the place where you should put any tenancy-specific service container calls — to not pollute your AppServiceProvider.
Note that you can register listeners to this package's events anywhere you want. The event/listener mapping in the service provider exists only to make your life easier. If you want to register the listeners manually, like in the example below, you can.
Event::listen(TenancyInitialized::class, BootstrapTenancy::class);By default, the BootstrapTenancy class is listening to the TenancyInitialized event (exactly as you can see in the example above). That listener will execute the configured tenancy bootstrappers to transition the application into the tenant's context. You can read more about this on the [tenancy bootstrappers]
Conversely, when the TenancyEnded event fires, the RevertToCentralContext event transitions the app back into the central context.
Note: Some database events (SeedingDatabase, DatabaseSeeded and possibly others) are fired in the tenant context. Depending on how your application bootstraps tenancy, you might need to be specific about interacting with the central database in these events' listeners — that is, if you need to.
Note: All events are located in the MichaelNabil230\MultiTenancy\Events namespace.
InitializingTenancyTenancyInitializedEndingTenancyTenancyEndedBootstrappingTenancyTenancyBootstrappedRevertingToCentralContextRevertedToCentralContext
Note the difference between initializing tenancy and bootstrapping tenancy. Tenancy is initialized when a tenant is loaded into the Tenancy object. Whereas bootstrapping happens as a result of initialization — if you're using automatic tenancy, the BootstrapTenancy class is listening to the TenancyInitialized event and after it's done executing bootstrappers, it fires an event saying that tenancy was bootstrapped. You want to use the bootstrapped event if you want to execute something after the app has been transitioned to the tenant context.
The following events are dispatched as a result of Eloquent events being fired in the default Tenant implementation (the most often used events are bold):
CreatingTenantTenantCreatedSavingTenantTenantSavedUpdatingTenantTenantUpdatedDeletingTenantTenantDeleted
These events are optional. They're only relevant to you if you're using domains for your tenants.
CreatingDomainDomainCreatedSavingDomainDomainSavedUpdatingDomainDomainUpdatedDeletingDomainDomainDeleted
These events are also optional. They're relevant to you if you're using multi-database tenancy:
SeedingDatabaseDatabaseSeeded
You may register tenant routes in routes/tenant.php. These routes have no middleware applied on them, and their controller namespace is specified in app/Providers/TenancyServiceProvider.
By default, you will see the following setup:
Route::middleware([
'web',
InitializeTenancyByDomain::class,
])->group(function () {
Route::get('/', function () {
return 'This is your multi-tenant application. The id of the current tenant is ' . tenant('id');
});
});Routes within this group will have the web middleware group, an initialization middleware, and finally, a middleware related to the section below applied on them.
You may do the same for the api route group, for instance.
Also, you may use different initialization middleware than the domain one. For a full list, see the [Tenant identification].
In single-database tenancy, there are 4 types of models:
- your Tenant model
- primary models — models that directly belongTo tenants
- secondary models — models that indirectly belongTo tenants
- e.g. Comment belongsTo Post belongsTo Tenant
- or more complex, Vote belongsTo Comment belongsTo Post belongsTo Tenant
- global models — models that are not scoped to any tenant whatsoever
To scope your queries correctly, apply the MichaelNabil230\MultiTenancy\Traits\BelongsToTenant trait on primary models. This will ensure that all calls to your parent models are scoped to the current tenant, and that calls to their child relations are scoped through the parent relationships.
And that's it. Your models are now automatically scoped to the current tenant, and not scoped at all when there's no current tenant (e.g. in a central admin panel).
However, there's one edge case to keep in mind. Consider the following set-up:
class Post extends Model
{
use BelongsToTenant;
public function comments()
{
return $this->hasMany(Comment::class);
}
}
class Comment extends Model
{
public function post()
{
return $this->belongsTo(Post::class);
}
}Looks correct, but you might still accidentally access another tenant's comments.
If you use this:
Comment::all();then the model has no way of knowing how to scope that query, since it doesn't directly belong to the tenant. Also note that in practice, you really shouldn't be doing this much. You should ideally access secondary models through parent models in every single case.
However, sometimes you might have a use case where you really need to do that in the tenant context. For that reason, we also provide you with a BelongsToPrimaryModel trait, which lets you scope calls like the one above to the current tenant, by loading the parent relationship — which gets automatically scoped to the current tenant — on them.
So, to give you an example, you would do this:
class Comment extends Model
{
use BelongsToPrimaryModel;
public function getRelationshipToPrimaryModel(): string
{
return 'post';
}
public function post()
{
return $this->belongsTo(Post::class);
}
}And this will automatically scope the Comment::all() call to the current tenant. Note that the limitation of this is that you need to be able to define a relationship to a primary model, so if you need to do this on the "Vote" in Vote belongsTo Comment belongsTo Post belongsTo Tenant, you need to define some strange relationship. Laravel supports HasOneThrough, but not BelongsToThrough, so you'd need to do some hacks around that. For that reason, I recommend avoiding these Comment::all()-type queries altogether.
If you'd have a unique index such as:
$table->unique('slug');in a standard non-tenant, or multi-database-tenant, application, you need to scope this unique index to the tenant, meaning you'd do this on primary models:
$table->unique(['tenant_id', 'slug']);and this on secondary models:
// Imagine we're in a 'comments' table migration
$table->unique(['post_id', 'user_id']);The unique and exists validation rules of course aren't scoped to the current tenant, so you need to scope them manually like this:
Rule::unique('posts', 'slug')->where('tenant_id', tenant('id'));You'll be able to use these two methods:
// You may retrieve the current tenant using the tenant() helper.
// $tenant = tenant();
$rules = [
'id' => $tenant->exists('posts'),
'slug' => $tenant->unique('posts'),
]And the final thing to keep in mind is that DB facade calls, or any other types of direct database queries, of course won't be scoped to the current tenant.
The package can only provide scoping logic for the abstraction logic that Eloquent is, it can't do anything with low level database queries.
Be careful with using them.
Commands can be made tenant aware by applying the TenantAware trait. When using the trait it is required to append {--tenant=*} or {--tenant=} to the command signature.
Caution: If you append {--tenant=*}, then if no tenant option is provided when executing the command, the command will execute for all tenants.
use Illuminate\Console\Command;
use MichaelNabil230\MultiTenancy\Commands\Concerns\TenantAware;
class YourFavoriteCommand extends Command
{
use TenantAware;
protected $name = 'your-favorite-command';
public function handle()
{
return $this->line('The tenant is '. Tenant::current()->name);
}
}When executing the command, the handle method will be called for each tenant.
php artisan your-favorite-command Using the example above, the name of each tenant will be written to the output of the command.
You can also execute the command for a specific tenant:
php artisan your-favorite-command --tenant=1Can it run a seed command to a specific tenant or for all tenants with the same previous section
php artisan tenants:seed --tenant=123Can it run a create command to quickly create a tenant
php artisan create:tenant shop-1To disable the tenant scope, simply add withoutTenancy() to your query.
That's it, we only have to use that trait in our User model! Now your users may subscribe to plans.
use MichaelNabil230\MultiTenancy\MultiTenancy;
$plan = MultiTenancy::plan()->create([
'name' => 'Pro',
'description' => 'Pro plan',
'price' => 9.99,
'invoice_period' => 1,
'invoice_interval' => 'month',
'trial_period' => 15,
'trial_interval' => 'day',
]);
// Create multiple plan features at once
$plan->features()->saveMany([
new Feature(['name' => 'listings']),
new Feature(['name' => 'pictures_per_listing']),
new Feature(['name' => 'listing_duration_days', 'resettable_period' => 1, 'resettable_interval' => 'month']),
new Feature(['name' => 'listing_title_bold'])
]);Get all plans with sections and features:
$plans = MultiTenancy::plans();You can query the plan for further details, using the intuitive API as follows:
$plan = MultiTenancy::plan()->find(1);
// Get all plan features
$plan->features;
// Get all plan subscriptions
$plan->subscriptions;
// Check if the plan is free
$plan->isFree();
// Check if the plan has trial period
$plan->hasTrial();Both $plan->features and $plan->subscriptions are collections, driven from relationships, and thus you can query these relations as any normal Eloquent relationship. E.g. $plan->features()->where('name', 'listing_title_bold')->first().
You can subscribe a tenant to a plan by using the createSubscription(Plan $plan, Carbon $startDate = null) function available in the Tenant model. First,
retrieve an instance of your subscriber model, which typically will be your tenant model and an instance of the plan your tenant is subscribing to. Once you have retrieved the model instance, you may use the createSubscription method to create the model's subscription.
$tenant = MultiTenancy::tenant()->find(1);
$plan = MultiTenancy::plan()->find(1);
$tenant->createSubscription($plan, Carbon::now()->addMonths(4));The first argument passed to createSubscription while the argument is the plan instance your tenant is subscribing to, and there's an optional second parameter to specify custom start date as an instance of Illuminate\Support\Carbon (by default if not provided, it will start now).
You can change subscription plan easily as follows:
$plan = MultiTenancy::plan()->find(2);
$subscription = MultiTenancy::subscription()->find(1);
// Change subscription plan
$subscription->changePlan($plan);If both plans (current and new plan) have the same billing frequency (e.g., invoice_period and invoice_interval) the subscription will retain the same billing dates. If the plans don't have the same billing frequency, the subscription will have the new plan billing frequency, starting on the day of the change and the subscription usage data will be cleared. Also if the new plan has a trial period and it's a new subscription, the trial period will be applied.
For a subscription to be considered active one of the following must be true:
- Subscription has an active trial.
- Subscription
ends_atis in the future.
$user->subscribed($planId);Alternatively you can use the following methods available in the subscription model:
$user->subscription($planId)->active();
$user->subscription($planId)->canceled();
$user->subscription($planId)->ended();
$user->subscription($planId)->onTrial();Canceled subscriptions with an active trial or
ends_atin the future are considered active.
To renew a subscription you may use the renew method available in the subscription model. This will set a new ends_at date based on the selected plan and will clear the usage data of the subscription.
$user->subscription($planId)->renew();Canceled subscriptions with an ended period can't be renewed.
To cancel a subscription, simply use the cancel method on the user's subscription:
$user->subscription($planId)->cancel();// Get subscriptions by plan
$subscriptions = MultiTenancy::subscription()->planId($planId)->get();
// Get subscriptions recurring
$subscriptions = MultiTenancy::subscription()->recurring()->get();
// Get subscriptions canceled
$subscriptions = MultiTenancy::subscription()->canceled()->get();
// Get subscriptions not canceled
$subscriptions = MultiTenancy::subscription()->notCanceled()->get();
// Get subscriptions with ended period
$subscriptions = MultiTenancy::subscription()->ended()->get();
// Get subscriptions with on trial period
$subscriptions = MultiTenancy::subscription()->onTrial()->get();
// Get subscriptions with expired trial period
$subscriptions = MultiTenancy::subscription()->expiredTrial()->get();
// Get subscriptions with not on trial
$subscriptions = MultiTenancy::subscription()->notOnTrial()->get();
// Get subscriptions with on grace period
$subscriptions = MultiTenancy::subscription()->onGracePeriod()->get();
// Get subscriptions with not on grace period
$subscriptions = MultiTenancy::subscription()->notOnGracePeriod()->get();MultiTenancy Subscriptions uses 4 models:
MichaelNabil230\MultiTenancy\Models\Plan;
MichaelNabil230\MultiTenancy\Models\Feature;
MichaelNabil230\MultiTenancy\Models\Subscription;
MichaelNabil230\MultiTenancy\Models\Section;
composer testPlease see CHANGELOG for more information on what has changed recently.
Please see CONTRIBUTING for details.
Please review our security policy on how to report security vulnerabilities.
The MIT License (MIT). Please see License File for more information.