manggala/tenancy

Universal Multi-Tenancy Engine for Laravel supporting Single-DB (Row-Level), Multi-DB & Hybrid Isolation Modes.

v1.0.0 2026-08-13 17:39 UTC

Requires

• php: ^8.2 || ^8.3 || ^8.4
• illuminate/database: ^10.0 || ^11.0 || ^12.0 || ^13.0
• illuminate/http: ^10.0 || ^11.0 || ^12.0 || ^13.0
• illuminate/support: ^10.0 || ^11.0 || ^12.0 || ^13.0

Requires (Dev)

• larastan/larastan: ^2.0 || ^3.0
• orchestra/testbench: ^8.0 || ^9.0 || ^10.0
• pestphp/pest: ^2.0 || ^3.0
• pestphp/pest-plugin-laravel: ^2.0 || ^3.0
• phpstan/phpstan: ^1.10 || ^2.0

MIT

• Ilham Hatta Manggala

• laravel
• subdomain
• saas
• tenant
• tenancy
• multi-tenancy
• multi-db
• row-level-security
• manggala
• single-db

Published on Packagist.org on 2026-08-13 17:42 UTC

README

manggala/tenancy adalah Headless Multi-Tenancy Engine serbaguna dan fleksibel untuk aplikasi SaaS Laravel.

Package ini mendukung 3 mode isolasi (Single-DB Row Scoping, Multi-DB Database-per-Tenant, dan Hybrid Mode) dengan 4 metode resolusi tenant otomatis (Subdomain, Custom Domain, HTTP Header, & Path).

🌟 Fitur Utama

1. Dual & Hybrid Isolation Engine:
   • Single-DB Mode (Row-Level Security): Trait BelongsToTenant & TenantScope otomatis menyuntikkan WHERE tenant_id = 'xxx' dan mengisi tenant_id secara transparan.
   • Multi-DB Mode (Database-per-Tenant): Mengubah koneksi PDO & mereset database connection secara runtime.
   • Hybrid Mode: Single-DB untuk Tier Standard, Multi-DB terpisah untuk Tier Enterprise.
2. 4 Resolusi Tenant Automatic:
   • Subdomain (acme.app.com)
   • Custom Domain (portal.acmecorp.com)
   • HTTP Header (X-Tenant-ID: acme — untuk REST API & Mobile Apps)
   • Path (app.com/t/acme)
3. Runtime Resource Bootstrappers:
   • Isolasi Storage (storage/app/tenants/{tenant_id}/)
   • Isolasi Cache & Redis (tenant:{tenant_id}:)
   • Isolasi File Log (storage/logs/tenant-{tenant_id}.log)
4. Safe Context Switcher (Tenancy::runFor()):
   • Jalankan logika di dalam konteks tenant lain dengan aman, lalu otomatis kembali ke tenant asal.
5. Tenant Quota & Feature Gates:
   • Sistem bawaan untuk membatasi kuota (max_users, max_storage) dan fitur tiering SaaS.
6. 7 Artisan CLI Commands:
   • Suite perintah terminal lengkap (tenancy:install, tenant:create, tenant:migrate, tenant:seed, tenant:list, tenant:run, tenant:doctor).

📋 Matriks Kompatibilitas Framework & Stack

Parameter	Dukungan Versi & Framework
Package Name	manggala/tenancy
PHP Version	`^8.2
Laravel Version (4 Major Versions)	`^10.0
Frontend Stack Support	Blade, Livewire (v2/v3), Inertia React, Inertia Vue, REST API / Mobile Apps
Testing Suite	Pest PHP (pestphp/pest)
Static Analysis	PHPStan Level 5+ (larastan/larastan)

📦 Instalasi

Pasang package via Composer:

composer require manggala/tenancy

Jalankan perintah instalasi otomatis untuk mempublikasikan file konfigurasi dan migrasi tabel central tenants:

php artisan tenancy:install

Jalankan migrasi database:

php artisan migrate

⚙️ Cara Penggunaan

1. Memilih Mode Isolasi (config/tenancy.php)

return [
    // Mode: 'single-db', 'multi-db', atau 'hybrid'
    'mode' => env('TENANCY_MODE', 'single-db'),

    // Kolom ID tenant untuk Single-DB mode
    'tenant_column' => 'tenant_id',

    // Central domain yang diabaikan dari resolusi tenant
    'central_domains' => [
        'app.test',
        'localhost',
        '127.0.0.1',
    ],
];

2. Memasang Trait pada Model (Single-DB Mode)

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Manggala\Tenancy\Traits\BelongsToTenant;

class Invoice extends Model
{
    use BelongsToTenant; // Auto-inject WHERE tenant_id = 'xxx' & auto-fill tenant_id on create
}

3. Mendaftarkan Middleware Resolusi Tenant

Daftarkan middleware pada grup route yang membutuhkan isolasi tenant:

use Manggala\Tenancy\Http\Middleware\IdentifyTenantBySubdomain;

Route::middleware(['web', IdentifyTenantBySubdomain::class])->group(function () {
    Route::get('/dashboard', [DashboardController::class, 'index']);
});

Untuk REST API & Mobile Apps:

use Manggala\Tenancy\Http\Middleware\IdentifyTenantByHeader;

Route::middleware(['api', IdentifyTenantByHeader::class])->group(function () {
    Route::get('/v1/orders', [OrderApiController::class, 'index']);
});

4. Menjalankan Kode dalam Konteks Tenant Lain

use Manggala\Tenancy\Facades\Tenancy;

// Dapatkan tenant aktif saat ini
$current = Tenancy::current();

// Jalankan closure dalam konteks tenant lain sementara waktu
Tenancy::runFor($targetTenant, function () {
    // Semua query Eloquent & storage path di sini mengacu ke $targetTenant
    Invoice::create([
        'title' => 'Cross-tenant Invoice',
        'amount' => 500000,
    ]);
});
// Setelah block ini selesai, konteks otomatis kembali ke $current

5. Memeriksa Fitur & Kuota Tenant

$tenant = Tenancy::current();

if ($tenant->canUseFeature('export_pdf')) {
    // Fitur diperbolehkan
}

if ($tenant->hasExceededQuota('max_users', User::count())) {
    return response()->json(['error' => 'Quota user telah penuh.'], 403);
}

🖥️ Perintah Artisan CLI Suite (10 Perintah)

Package ini menyediakan 10 perintah terminal untuk mengelola tenant:

Perintah	Deskripsi
php artisan tenancy:install	Mempublikasikan config tenancy.php & file migrasi tenants.
php artisan tenant:create {name} --domain= --db=	Membuat tenant baru (dan opsional DB terpisah).
php artisan tenant:delete {id} --drop-db --force	Menghapus tenant dan opsional drop database.
php artisan tenant:migrate {--tenant=}	Menjalankan migrate pada seluruh database tenant (Multi-DB).
php artisan tenant:rollback {--step=1}	Rollback migrasi database pada seluruh database tenant.
php artisan tenant:seed {--class=DatabaseSeeder}	Menjalankan database seeder ke seluruh tenant.
php artisan tenant:list	Menampilkan daftar tenant terdaftar dalam tabel terminal.
php artisan tenant:run {tenant_id} "{command}"	Menjalankan perintah artisan pada konteks tenant spesifik.
php artisan tenant:toggle {tenant_id}	Mengaktifkan atau mensuspensi (suspend / activate) tenant.
php artisan tenant:doctor	Tool diagnostik integritas koneksi DB, isolasi cache, & memory leaks.

🧪 Pengujian (Testing)

Jalankan pengujian menggunakan Pest PHP:

composer test

Jalankan analisis statis PHPStan:

composer analyse

📄 Lisensi

Package ini berlisensi MIT License.