pong106/landlord

A simple, single database multi-tenancy solution for Laravel 5.2+

Landlord for Laravel & Lumen 5.2+. Supports Laravel 7.0.

, _(*1)

, _(*2)

A single database multi-tenancy package for Laravel & Lumen 5.2+., _(*3)

Upgrading from Landlord v1? Make sure to read the change log to see what needs updating., _(*4)

Installation

To get started, require this package:, _(*5)

composer require pong106/landlord

Laravel

Add the ServiceProvider in config/app.php:, _(*6)

    'providers' => [
        ...
        HipsterJazzbo\Landlord\LandlordServiceProvider::class,
    ],

Register the Facade if you’d like:, _(*7)

    'aliases' => [
        ...
        'Landlord'   => HipsterJazzbo\Landlord\Facades\Landlord::class,
    ],

You could also publish the config file:, _(*8)

php artisan vendor:publish --provider="HipsterJazzbo\Landlord\LandlordServiceProvider"

and set your default_tenant_columns setting, if you have an app-wide default. LandLord will use this setting to scope models that don’t have a $tenantColumns property set., _(*9)

Lumen

You'll need to set the service provider in your bootstrap/app.php:, _(*10)

$app->register(HipsterJazzbo\Landlord\LandlordServiceProvider::class);

And make sure you've un-commented $app->withEloquent()., _(*11)

Usage

This package assumes that you have at least one column on all of your Tenant scoped tables that references which tenant each row belongs to., _(*12)

For example, you might have a companies table, and a bunch of other tables that have a company_id column., _(*13)

Adding and Removing Tenants

IMPORTANT NOTE: Landlord is stateless. This means that when you call addTenant(), it will only scope the current request., _(*14)

Make sure that you are adding your tenants in such a way that it happens on every request, and before you need Models scoped, like in a middleware or as part of a stateless authentication method like OAuth., _(*15)

You can tell Landlord to automatically scope by a given Tenant by calling addTenant(), either from the Landlord facade, or by injecting an instance of TenantManager()., _(*16)

You can pass in either a tenant column and id:, _(*17)

Landlord::addTenant('tenant_id', 1);

Or an instance of a Tenant model:, _(*18)

$tenant = Tenant::find(1);

Landlord::addTenant($tenant);

If you pass a Model instance, Landlord will use Eloquent’s getForeignKey() method to decide the tenant column name., _(*19)

You can add as many tenants as you need to, however Landlord will only allow one of each type of tenant at a time., _(*20)

To remove a tenant and stop scoping by it, simply call removeTenant():, _(*21)

Landlord::removeTenant('tenant_id');

// Or you can again pass a Model instance:
$tenant = Tenant::find(1);

Landlord::removeTenant($tenant);

You can also check whether Landlord currently is scoping by a given tenant:, _(*22)

// As you would expect by now, $tenant can be either a string column name or a Model instance
Landlord::hasTenant($tenant);

And if for some reason you need to, you can retrieve Landlord's tenants:, _(*23)

// $tenants is a Laravel Collection object, in the format 'tenant_id' => 1
$tenants = Landlord::getTenants();

Setting up your Models

To set up a model to be scoped automatically, simply use the BelongsToTenants trait:, _(*24)

use Illuminate\Database\Eloquent\Model;
use HipsterJazzbo\Landlord\BelongsToTenants;

class ExampleModel extends Model
{
    use BelongsToTenants;
}

If you’d like to override the tenants that apply to a particular model, you can set the $tenantColumns property:, _(*25)

use Illuminate\Database\Eloquent\Model;
use HipsterJazzbo\Landlord\BelongsToTenants;

class ExampleModel extends Model
{
    use BelongsToTenants;

    public $tenantColumns = ['tenant_id'];
}

Creating new Tenant scoped Models

When you create a new instance of a Model which uses BelongsToTenants, Landlord will automatically add any applicable Tenant ids, if they are not already set:, _(*26)

// 'tenant_id' will automatically be set by Landlord
$model = ExampleModel::create(['name' => 'whatever']);

Querying Tenant scoped Models

After you've added tenants, all queries against a Model which uses BelongsToTenant will be scoped automatically:, _(*27)

// This will only include Models belonging to the current tenant(s)
ExampleModel::all();

// This will fail with a ModelNotFoundForTenantException if it belongs to the wrong tenant
ExampleModel::find(2);

Note: When you are developing a multi tenanted application, it can be confusing sometimes why you keep getting ModelNotFound exceptions for rows that DO exist, because they belong to the wrong tenant., _(*28)

Landlord will catch those exceptions, and re-throw them as ModelNotFoundForTenantException, to help you out :), _(*29)

If you need to query across all tenants, you can use allTenants():, _(*30)

// Will include results from ALL tenants, just for this query
ExampleModel::allTenants()->get()

Under the hood, Landlord uses Laravel's anonymous global scopes. This means that if you are scoping by multiple tenants simultaneously, and you want to exclude one of the for a single query, you can do so:, _(*31)

// Will not scope by 'tenant_id', but will continue to scope by any other tenants that have been set
ExampleModel::withoutGlobalScope('tenant_id')->get();

Contributing

If you find an issue, or have a better way to do something, feel free to open an issue or a pull request., _(*32)