README

A flexible, resolver-based multi-tenancy package for Laravel.

Features

Hierarchical Tenancy: Organization → Branch → Owner.
Context-Aware: Resolves tenants from Request (Subdomain, Header, Route, Auth).
Security: Strict validation (e.g., Branch must belong to Organization).
Flexible Auth: Custom tenant resolution logic via ProvidesTenant interface.
Bypass: System-level bypass for super-admins.
Lightweight: Runtime resolution, no complex model inheritance.

Installation

composer require hatchyu/laravel-tenancy
php artisan vendor:publish --tag=tenancy-config

Core Concepts

this package models tenancy as a hierarchy:

Organization: The top-level tenant (e.g., "Acme Corp").
Branch: A sub-unit of an organization (e.g., "New York Office").
Owner: The user who owns specific data (optional).

Tenants are resolved per request and stored in the TenantContext.

[!IMPORTANT] If no tenant is resolved (and no bypass is active), the BelongsToTenant scope is NOT applied, effectively showing "public" data. Ensure your routes are protected by the ResolveTenancy middleware to enforce resolution for tenant-specific data.

Usage

1. Models

Add the BelongsToTenant trait to your models:

use Illuminate\Database\Eloquent\Model;
use Hatchyu\Tenancy\Traits\BelongsToTenant;
use Hatchyu\Tenancy\Enums\TenantType;

class Invoice extends Model
{
    use BelongsToTenant;

    protected static function tenantType(): TenantType
    {
        return TenantType::Organization; // or TenantType::Branch
    }

    protected static function tenantColumn(): string
    {
        return 'organization_id';
    }
}

2. Middleware

// In bootstrap/app.php
->withMiddleware(function (Middleware $middleware) {
    // 1. Global (Applies to everything)
    $middleware->append(\Hatchyu\Tenancy\Middleware\ResolveTenancy::class);
    
    // OR 2. Register Alias for Route Groups
    $middleware->alias([
        'tenancy' => \Hatchyu\Tenancy\Middleware\ResolveTenancy::class,
    ]);
});

Then apply to routes:

Route::middleware('tenancy')->group(function () {
    Route::get('/dashboard', ...);
});

3. Facade

You can use the Tenancy facade to access the current context:

use Hatchyu\Tenancy\Facades\Tenancy;
use Hatchyu\Tenancy\Enums\TenantType;

// Get current Tenant IDs
$orgId = Tenancy::get(TenantType::Organization);
$branchId = Tenancy::get(TenantType::Branch);

// Manually set context (e.g., in tests or jobs)
Tenancy::set(TenantType::Organization, 1);

Configuration & Resolvers

Configure resolvers in config/tenancy.php. The order matters!

Available Resolvers

SubdomainOrganizationResolver: Extracts org from subdomain (e.g., acme.app.com).
HeaderOrganizationResolver: Reads X-Organization-ID header.
AuthOrganizationResolver: Uses Auth::user()->organization_id (or ProvidesTenant interface).
RouteBranchResolver: Resolves branch from route params (strictly verifies org ownership).
AuthBranchResolver: Uses Auth::user()->branch_id (strictly verifies org ownership).

Flexible Auth Resolution

If your User model implies tenancy differently (e.g. via session or relationships), implement ProvidesTenant:

use Hatchyu\Tenancy\Contracts\ProvidesTenant;
use Hatchyu\Tenancy\Enums\TenantType;

class User extends Authenticatable implements ProvidesTenant
{
    public function getTenantId(TenantType $type): int|string|null
    {
        return match($type) {
            TenantType::Organization => $this->current_org_id,
            TenantType::Branch => session('active_branch_id'),
            default => null,
        };
    }
}

The resolvers will prioritize this interface over standard properties.

Queues & Jobs

This package resolves tenancy runtime per request. Background jobs do not automatically inherit this context. To support tenancy in queues, pass the tenant ID to the job and manually set it:

public function __construct(protected int $organizationId) {}

public function handle()
{
    Tenancy::set(TenantType::Organization, $this->organizationId);
    // ... run logic
}

Super-admin (platform owner)

Add bypass:

use Hatchyu\Tenancy\Contracts\TenancyBypass;

class PlatformTenancyBypass implements TenancyBypass
{
    public function shouldBypass(): bool
    {
        return auth()->user()?->is_platform_admin ?? false;
    }
}

Config:

'bypass' => PlatformTenancyBypass::class,

Philosophy

Tenancy is a runtime concern, not a model concern. This package resolves tenants before queries run and applies isolation automatically via global scopes.

This design:

Scales to enterprise
Fits Hatchyu code generation
Avoids coupling
Is extensible without inheritance hell

hatchyu / laravel-tenancy

Maintainers

Details