README

Laravel multi-tenancy model scoping and automatic tenancy assignment.

Installation

composer require acdphp/laravel-multitenancy

Configuration

Publish config

php artisan vendor:publish --provider="Acdphp\Multitenancy\TenancyServiceProvider"

Change the column name to look for tenancy in models.

'tenant_ref_key' => 'company_id',

By default, the tenant id is automatically resolved using the authenticated user's tenant ref key defined above. You can disable this and define your own resolver logic in AppServiceProvider or any service provider.

'auto_resolve_tenant_id' => true,

By default, the tenant id is automatically assigned during creation using the resolved tenancy defined above. You can disable this and manually set tenant id as you normally would.

'auto_assign_tenant_id' => true,

Example Usage

use \Acdphp\Multitenancy\Traits\BelongsToTenant;

class Site extends Model
{
    use BelongsToTenant;
    
    protected $fillable = [
        'company_id',
        ...
    ];
}

Per-model column name override

The tenant_ref_key config defines the column name globally. You can override it for a specific model by defining the $tenantRefKey property. This affects auto-assignment on creation and all scoping queries for that model.

use \Acdphp\Multitenancy\Traits\BelongsToTenant;

class Site extends Model
{
    use BelongsToTenant;

    protected string $tenantRefKey = 'org_id'; // Override the global tenant_ref_key for this model

    protected $fillable = [
        'org_id',
        ...
    ];
}

Scoping from parent relationship

use \Acdphp\Multitenancy\Traits\BelongsToTenant;

class Product extends Model
{
    use BelongsToTenant;
    
    protected $fillable = [
        'site_id',
        ...
    ];
    
    protected string $scopeTenancyFromRelation = 'site'; // Define to scope from parent model
    
    public function site(): BelongsTo
    {
        return $this->belongsTo(Site::class);
    }
}

Custom tenant scope condition

When a model's tenancy is more than a simple column match (e.g. tenant-owned or public), define an applyTenantScope method with your own condition. The package uses it in place of the default tenant key filter — everything else (scope bypass, the missing-tenant case, auto-assignment on creation) is still handled for you before it runs.

use \Acdphp\Multitenancy\Traits\BelongsToTenant;

class Event extends Model
{
    use BelongsToTenant;

    protected function applyTenantScope(Builder $builder, array|int|string $tenantId): void
    {
        $builder->where(function (Builder $query) use ($tenantId) {
            $query->where('is_public', true)
                ->orWhereIn('company_id', (array) $tenantId);
        });
    }
}

Models scoping from a parent relationship apply the parent's custom condition automatically:

class Ticket extends Model
{
    use BelongsToTenant;

    protected string $scopeTenancyFromRelation = 'event'; // Ticket is visible when its event is

    public function event(): BelongsTo
    {
        return $this->belongsTo(Event::class);
    }
}

Note: since the tenancy of such a model is defined by the condition rather than a single column, the tenant ref key is not auto-appended to $fillable. If the model has no tenant column at all, also disable auto-assignment with protected bool $autoAssignTenantId = false;.

Manually setting the tenant

In the registration, for example, tenancy isn't set because it's a non-authenticated endpoint. The tenant has to be manually assigned.

use Acdphp\Multitenancy\Facades\Tenancy;

// Create a company and set it as tenant
$company = Company::create(...);
Tenancy::setTenantIdResolver(fn () => $company->id);

// Then proceed to create a user
User::create(...);

Custom Scoping Tenant ID

By default, the scoping uses the resolved tenant ID. You can set a custom scoping tenant ID resolver that supports a single value or an array of IDs.

use Acdphp\Multitenancy\Facades\Tenancy;

// Scope to a single tenant
Tenancy::setScopingTenantIdResolver(fn () => $tenantId);

// Scope to multiple tenants
Tenancy::setScopingTenantIdResolver(fn () => [1, 2, 3]);

Bypassing Scope

Sometimes, it's needed to bypass scoping when accessing a model that belongs to a tenant.

use Acdphp\Multitenancy\Facades\Tenancy;

Tenancy::bypassScope();

Or by using the middleware.

Route::middleware(['tenancy.scope.bypass'])->get('/resources/all', ...);

To re-enable scoping after bypassing:

Tenancy::resetScopeBypass();

Bypassing Automatic Tenancy Assignment

It's also possible to bypass auto-tenancy assignments.

use Acdphp\Multitenancy\Facades\Tenancy;

Tenancy::bypassCreating();

Or by using the middleware.

Route::middleware(['tenancy.creating.bypass'])->post('your-route', ...);

To re-enable auto-assignment after bypassing:

Tenancy::resetCreatingBypass();

Testing

composer test

# with docker-compose
docker-compose run --rm test-php84

Linting and static analysis

composer lint

# with docker-compose
docker-compose run --rm lint

Lint Fix

composer lint-fix

# with docker-compose
docker-compose run --rm lint-fix

License

The MIT License (MIT). Please see License File for more information.

acdphp / laravel-multitenancy

Maintainers

Package info

Statistics

Security