Tenancy

Dokumentasi ini merupakan referensi untuk seluruh class yang membentuk mekanisme tenancy di PandaBear:

PandaPanel\Tenancy\Tenancy;
dua contract yang diimplementasikan application;
method pada Panel yang mengaktifkan tenancy;
serta property dan method pada Resource yang melakukan tenant scoping terhadap query.

Gunakan halaman ini ketika Anda sudah memahami konsep tenancy dan membutuhkan detail seperti:

signature method;
return type;
failure mode;
lifecycle;
atau behavior pasti dari sebuah call.

Untuk pembahasan konsep seperti:

apa arti tenant di PandaBear;
mengapa identifikasi Tenant menjadi tanggung jawab application;

lihat:

Tenancy Concepts

Ini Bukan Implementasi Multi-Tenancy

Hal ini sangat penting.

PandaBear Tenancy bukan framework multi-tenancy lengkap.

Mekanisme ini tidak:

membuat database per Tenant;
mengganti database connection;
melakukan cache partitioning;
membaca subdomain;
membuat schema database;
atau menentukan bagaimana tenant diisolasi secara infrastruktur.

Tenancy PandaBear hanya menjawab satu pertanyaan per request:

Request ini sedang bekerja untuk Tenant yang mana?

Setelah Tenant ditemukan, jawaban tersebut disimpan pada request-scoped context sehingga seluruh bagian framework dapat membacanya.

Secara konsep:

text

HTTP Request
    ↓
Resolve Tenant
    ↓
Current Tenant
    ↓
PanelContext
    ↓
Resource / Page / Widget / Action

Contoh Minimal yang Berfungsi

Ada tiga bagian yang semuanya diperlukan:

Panel menentukan:
- apa Tenant Model-nya;
- bagaimana Tenant ditemukan dari request.
User Model menentukan:
- Tenant mana yang boleh ditawarkan;
- Tenant mana yang benar-benar boleh dimasuki.
Resource menentukan:
- relation mana yang menghubungkan record dengan Tenant.

1. Panel Mendeklarasikan Tenant

php

<?php

declare(strict_types=1);

namespace App\Panels\App;

use App\Models\Workspace;
use Illuminate\Http\Request;
use PandaPanel\Core\Panel;
use PandaPanel\Core\PanelProvider;

final class AppPanelProvider
    extends PanelProvider
{
    public function panel(
        Panel $panel
    ): Panel {
        return $panel
            ->path('app')
            ->auth()
            ->tenant(
                Workspace::class,

                static fn (
                    Request $request
                ): ?Workspace =>
                    Workspace::query()
                        ->find(
                            $request
                                ->query(
                                    'workspace'
                                )
                        ),
            )
            ->tenantUrlUsing(
                static fn (
                    Workspace $workspace,
                    Panel $panel
                ): string =>
                    '/'
                    . $panel->getPath()
                    . '/documents?workspace='
                    . $workspace
                        ->getKey(),
            );
    }
}

2. User Menentukan Tenant yang Boleh Diakses

php

<?php

declare(strict_types=1);

namespace App\Models;

use Illuminate\Database\Eloquent\Collection;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsToMany;
use Illuminate\Foundation\Auth\User as Authenticatable;
use PandaPanel\Contracts\HasPanelTenants;
use PandaPanel\Core\Panel;

final class User
    extends Authenticatable
    implements HasPanelTenants
{
    /**
     * @return BelongsToMany<Workspace, $this>
     */
    public function workspaces():
        BelongsToMany
    {
        return $this
            ->belongsToMany(
                Workspace::class
            );
    }

    /**
     * @return Collection<int, Model>
     */
    public function getPanelTenants(
        Panel $panel
    ): Collection {
        return $this
            ->workspaces()
            ->orderBy('id')
            ->get();
    }

    public function canAccessPanelTenant(
        Model $tenant,
        Panel $panel
    ): bool {
        return $this
            ->workspaces()
            ->whereKey(
                $tenant->getKey()
            )
            ->exists();
    }
}

3. Resource Menentukan Tenant Relationship

php

<?php

declare(strict_types=1);

namespace App\Panels\App\Resources\Documents;

use App\Models\Document;
use PandaPanel\Resources\Resource;

final class DocumentResource
    extends Resource
{
    protected static string $model =
        Document::class;

    /**
     * Relationship pada Document
     * yang mengarah ke Tenant.
     */
    protected static ?string
        $tenantRelationship =
            'workspace';
}

Sekarang request:

text

GET /app/documents?workspace=1

akan:

text

Resolve workspace 1
        ↓
Check user boleh masuk?
        ↓
Bind workspace sebagai current Tenant
        ↓
DocumentResource::query()
        ↓
Scope documents ke workspace tersebut

Semua read terhadap DocumentResource menggunakan Tenant yang sama.

`PandaPanel\Tenancy\Tenancy`

Tenancy merupakan:

php

final class Tenancy

yang berisi static methods.

Namun current Tenant tidak disimpan pada static property.

Tenant disimpan di:

php

PandaPanel\Support\PanelContext

yang diregistrasikan sebagai:

php

scoped()

pada Laravel container.

Artinya current Tenant hidup sepanjang satu request saja.

Ini mencegah Tenant bocor antara:

dua HTTP request;
dua test;
dua job;
atau dua request dalam satu Octane worker.

API `Tenancy`

Method	Return	Kegunaan
`bind(Model $tenant)`	`void`	Bind Tenant untuk request saat ini
`current()`	`?Model`	Current Tenant atau `null`
`require()`	`Model`	Current Tenant atau throw exception
`key()`	`int\|string\|null`	Identifier current Tenant
`keyOf(Model $tenant)`	`int\|string`	Identifier dari Tenant tertentu
`nameOf(Model $tenant)`	`string`	Nama Tenant untuk UI
`describe(Model $tenant)`	`array{key, name}`	Representasi Tenant untuk frontend
`availableTo(?Authenticatable $user, Panel $panel)`	`list<Model>`	Tenant yang boleh ditawarkan kepada user
`allows(?Authenticatable $user, Model $tenant, Panel $panel)`	`bool`	Apakah user boleh memasuki Tenant
`for(Model $tenant, callable $callback)`	`mixed`	Menjalankan callback dalam context Tenant tertentu

`bind()`

Signature:

php

public static function bind(
    Model $tenant
): void;

Method ini menyimpan Tenant ke request-scoped context dengan key:

text

panel.tenant

Contoh:

php

use PandaPanel\Tenancy\Tenancy;

Tenancy::bind(
    $workspace
);

Siapa yang Seharusnya Memanggil `bind()`

Dalam penggunaan normal hanya:

php

PandaPanel\Http\Middleware\ResolveTenant

dan test framework yang seharusnya memanggil method ini secara langsung.

Application code sebaiknya tidak menggunakan bind() sebagai entry point.

Mengapa?

Karena jika Tenant baru di-bind di tengah request:

text

Query A
→ belum scoped

Tenancy::bind()

Query B
→ scoped

maka satu request memiliki dua tenant boundary berbeda.

Untuk application code yang perlu masuk sementara ke Tenant tertentu, gunakan:

php

Tenancy::for()

karena method tersebut memulihkan Tenant sebelumnya setelah callback selesai.

`current()`

Signature:

php

public static function current():
    ?Model;

Mengembalikan:

php

Model

jika Tenant telah di-bind.

Mengembalikan:

php

null

jika:

Panel tidak menggunakan tenancy;
request tidak melewati ResolveTenant;
dipanggil di luar request;
value pada context bukan Eloquent Model.

Contoh:

php

use PandaPanel\Tenancy\Tenancy;

$workspace =
    Tenancy::current();

if (
    $workspace !== null
) {
    // ...
}

`require()`

Signature:

php

/**
 * @throws
 * \PandaPanel\Exceptions\PanelRegistrationException
 */
public static function require():
    Model;

require() dapat dianggap sebagai:

text

current()
+
Tenant wajib ada

Jika Tenant tidak tersedia:

php

PanelRegistrationException

dilempar.

Method ini digunakan oleh:

php

Resource::applyTenantScope()

Hal ini disengaja.

Resource yang sudah menyatakan dirinya tenant-scoped tetapi tidak memiliki Tenant tidak boleh fallback ke query tanpa scope.

Contoh:

php

use PandaPanel\Tenancy\Tenancy;

$tenant =
    Tenancy::require();

Invoice::query()
    ->where(
        'workspace_id',
        $tenant->getKey()
    )
    ->sum('total');

Mengapa Missing Tenant Harus Throw

Bayangkan:

text

DocumentResource
$tenantRelationship = workspace

tetapi current Tenant tidak tersedia.

Behavior yang berbahaya:

text

tenant tidak ada
↓
skip scope
↓
SELECT * FROM documents
↓
semua Tenant terlihat

PandaBear memilih:

text

tenant tidak ada
↓
exception

daripada silent data leak.

`key()`

Signature:

php

public static function key():
    int|string|null;

Mengembalikan identifying value dari current Tenant.

Jika tidak ada Tenant:

php

null

Contoh:

php

use PandaPanel\Tenancy\Tenancy;

Document::query()
    ->where(
        'workspace_id',
        Tenancy::key()
    )
    ->count();

Untuk sebagian besar query sederhana, method ini sudah cukup.

`keyOf()`

Signature:

php

public static function keyOf(
    Model $tenant
): int|string;

Jika Tenant Model mengimplementasikan:

php

PanelTenant

framework menggunakan:

php

$tenant->getTenantKey()

Jika tidak:

php

$tenant->getKey()

digunakan.

Jika primary key bukan int atau string, value di-cast ke string.

Contoh:

php

use PandaPanel\Tenancy\Tenancy;

Tenancy::keyOf(
    $workspace
);
// 41

Dengan PanelTenant yang menggunakan slug:

text

acme

`nameOf()`

Signature:

php

public static function nameOf(
    Model $tenant
): string;

Prioritas:

text

PanelTenant::getTenantName()
        ↓
non-empty 'name' attribute
        ↓
Tenant key sebagai string

Contoh:

php

use PandaPanel\Tenancy\Tenancy;

Tenancy::nameOf(
    $workspace
);
// 'Acme'

Framework memilih fallback ke key daripada empty string.

Alasannya Tenant Switcher dengan row kosong tidak dapat digunakan dengan baik.

`describe()`

Signature:

php

/**
 * @return array{
 *     key: int|string,
 *     name: string
 * }
 */
public static function describe(
    Model $tenant
): array;

Contoh:

php

use PandaPanel\Tenancy\Tenancy;

Tenancy::describe(
    $workspace
);

Hasil:

php

[
    'key' => 41,
    'name' => 'Acme',
]

SharePanelData nantinya menambahkan:

text

url
current

sebelum payload mencapai Vue.

`availableTo()`

Signature:

php

/**
 * @return list<Model>
 */
public static function availableTo(
    ?Authenticatable $user,
    Panel $panel
): array;

Method ini membangun daftar Tenant untuk Tenant Switcher.

Sumbernya:

php

HasPanelTenants::getPanelTenants()

Jika User Model tidak mengimplementasikan:

php

HasPanelTenants

hasilnya:

php

[]

Framework menganggap user tidak memiliki Tenant.

Contoh:

php

use PandaPanel\Tenancy\Tenancy;

$tenants =
    Tenancy::availableTo(
        $request->user(),
        panel('app')
    );

`allows()`

Signature:

php

public static function allows(
    ?Authenticatable $user,
    Model $tenant,
    Panel $panel
): bool;

Method ini memanggil:

php

HasPanelTenants::canAccessPanelTenant()

secara langsung.

Ia tidak mencari Tenant di dalam hasil availableTo().

Hal tersebut penting untuk security.

Daftar Tenant dari availableTo() dibuat untuk kebutuhan UI.

Daftar tersebut suatu saat dapat:

dipaginate;
dibatasi;
disortir;
hanya menampilkan Tenant terbaru.

Authorization tidak boleh berubah karena keputusan UI.

Prinsipnya:

text

availableTo()
→ apa yang ditawarkan

allows()
→ apa yang diizinkan

Jika:

user null;
User Model tidak mengimplementasikan HasPanelTenants;

hasilnya:

php

false

Contoh:

php

use PandaPanel\Tenancy\Tenancy;

abort_unless(
    Tenancy::allows(
        $request->user(),
        $workspace,
        panel('app')
    ),
    403
);

`for()`

Signature:

php

/**
 * @template TReturn
 *
 * @param callable(): TReturn $callback
 * @return TReturn
 */
public static function for(
    Model $tenant,
    callable $callback
): mixed;

Flow:

text

Simpan Tenant sebelumnya
        ↓
Bind Tenant baru
        ↓
Jalankan callback
        ↓
finally
        ↓
Pulihkan Tenant sebelumnya

Restoration tetap dilakukan jika callback melempar exception.

Itulah tujuan utama method ini.

Kapan Menggunakan `for()`

Gunakan untuk pekerjaan yang secara sah melewati Tenant boundary.

Contohnya:

console command yang looping Tenant;
queued job yang harus kembali ke Tenant asal;
test yang membandingkan visibility antar-Tenant.

Contoh:

php

use PandaPanel\Tenancy\Tenancy;

foreach (
    Workspace::query()
        ->cursor()
    as $workspace
) {
    Tenancy::for(
        $workspace,
        function () use (
            $workspace
        ): void {
            $this->info(
                $workspace->name
                . ': '
                . DocumentResource::query()
                    ->count()
            );
        }
    );
}

Jika sebelum callback tidak ada Tenant yang di-bind:

text

setelah callback
→ tidak ada Tenant lagi

`PandaPanel\Contracts\PanelTenant`

Contract ini optional pada Tenant Model.

Contract hanya memiliki dua method karena seluruh business meaning dari Tenant tetap menjadi milik application.

Panel hanya membutuhkan dua informasi:

apa identifier Tenant;
apa nama Tenant yang ditampilkan.

Contract:

php

interface PanelTenant
{
    public function getTenantKey():
        int|string;

    public function getTenantName():
        string;
}

Contoh:

php

<?php

declare(strict_types=1);

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use PandaPanel\Contracts\PanelTenant;

final class Workspace
    extends Model
    implements PanelTenant
{
    public function getTenantKey():
        int|string
    {
        return (string)
            $this->slug;
    }

    public function getTenantName():
        string
    {
        return (string)
            $this->name;
    }
}

Dengan configuration tersebut Tenant dapat direpresentasikan sebagai:

text

acme

di URL.

Misalnya:

text

/app?workspace=acme

Tanpa `PanelTenant`

Jika Tenant Model tidak mengimplementasikan contract:

php

Tenancy::keyOf()

fallback ke:

php

getKey()

sedangkan:

php

Tenancy::nameOf()

fallback ke attribute:

text

name

kemudian ke key.

Lihat:

PanelTenant

`PandaPanel\Contracts\HasPanelTenants`

Contract ini wajib pada User Model untuk Panel yang mendeklarasikan:

php

tenant()

Contract:

php

use Illuminate\Database\Eloquent\Collection;
use Illuminate\Database\Eloquent\Model;
use PandaPanel\Core\Panel;

interface HasPanelTenants
{
    /**
     * @return Collection<int, Model>
     */
    public function getPanelTenants(
        Panel $panel
    ): Collection;

    public function canAccessPanelTenant(
        Model $tenant,
        Panel $panel
    ): bool;
}

Dua Pertanyaan yang Berbeda

Method	Dipanggil oleh	Kapan
`getPanelTenants()`	`Tenancy::availableTo()`	Ketika membuat daftar Tenant Switcher
`canAccessPanelTenant()`	`Tenancy::allows()` melalui `ResolveTenant`	Setiap request sebelum query dijalankan

Argument:

php

Panel $panel

diberikan agar User Model dapat memberikan jawaban berbeda untuk Panel yang berbeda.

Contohnya:

text

Admin Panel
→ boleh mengakses semua Workspace

Customer Panel
→ hanya Workspace sendiri

User Tanpa `HasPanelTenants`

Jika tenant-scoped Panel digunakan tetapi User Model tidak mengimplementasikan interface ini:

text

request
→ 403

Ini merupakan failure mode yang disengaja.

Framework memilih:

text

deny

daripada menebak akses.

Lihat:

HasPanelTenants

`PandaPanel\Core\Panel`

Tenancy API pada Panel:

Method	Signature
`tenant()`	`tenant(string $model, Closure $resolver): self`
`tenantUrlUsing()`	`tenantUrlUsing(Closure $url): self`
`getTenantUrl()`	`getTenantUrl(Model $tenant): ?string`
`hasTenancy()`	`hasTenancy(): bool`
`getTenantModel()`	`getTenantModel(): ?string`
`resolveTenant()`	`resolveTenant(Request $request, ?Authenticatable $user): ?Model`

`tenant()`

Signature:

php

/**
 * @param class-string<Model> $model
 * @param Closure(
 *     Request,
 *     ?Authenticatable
 * ): ?Model $resolver
 */
public function tenant(
    string $model,
    Closure $resolver
): self;

Method ini menyatakan bahwa Panel merupakan tenant-scoped Panel.

Empat hal terjadi.

Dan hanya empat hal tersebut:

ResolveTenant ditambahkan ke route group Panel;
Tenancy::current() tersedia sepanjang request;
Resource yang memiliki tenantRelationship() otomatis di-scope;
daftar Tenant dibagikan ke frontend.

tenant() tidak otomatis mengubah database connection.

Tenant Resolver

Resolver menerima:

php

Request $request

dan:

php

?Authenticatable $user

lalu mengembalikan:

php

?Model

Resolver wajib diberikan.

Tidak ada default resolver karena setiap default yang mungkin benar untuk satu arsitektur bisa menjadi data leak untuk arsitektur lain.

Contoh Database per Tenant

Jika menggunakan package seperti stancl/tenancy yang sudah mengganti connection:

php

use App\Models\Tenant;

->tenant(
    Tenant::class,
    static fn () =>
        tenant()
)

PandaBear hanya membaca current Tenant.

Database switching tetap dilakukan oleh package tenancy tersebut.

Contoh Single Database dengan Path Segment

php

use App\Models\Team;
use Illuminate\Http\Request;

->tenant(
    Team::class,

    static fn (
        Request $request
    ) =>
        Team::query()
            ->where(
                'slug',
                $request
                    ->route('team')
            )
            ->first()
)

Contoh Satu Tenant per User

php

use App\Models\Workspace;

->tenant(
    Workspace::class,

    static fn (
        $request,
        $user
    ) =>
        $user?->workspace
)

Tidak ada Tenant identifier di URL.

`tenantUrlUsing()`

Signature:

php

/**
 * @param Closure(
 *     Model,
 *     self
 * ): string $url
 */
public function tenantUrlUsing(
    Closure $url
): self;

Resolver menjawab:

URL ini Tenant mana?

Sedangkan tenantUrlUsing() menjawab kebalikannya:

Tenant ini URL-nya apa?

Hanya application yang dapat mengetahui bagaimana resolver dibalik.

Contoh Subdomain Tenant

php

use PandaPanel\Core\Panel;

->tenantUrlUsing(
    static fn (
        Team $team
    ): string =>
        "https://{$team->slug}.example.com/app"
)

Contoh Path Tenant

php

->tenantUrlUsing(
    static fn (
        Team $team,
        Panel $panel
    ): string =>
        "/{$panel->getPath()}/{$team->slug}"
)

Jika `tenantUrlUsing()` Tidak Ada

Tenant Switcher tidak dirender.

Alasannya:

text

Switcher menampilkan Tenant
↓
user klik
↓
tidak ada destination

lebih buruk daripada tidak menampilkan Switcher sama sekali.

Lihat:

Tenant URLs

`getTenantUrl()`

Signature:

php

public function getTenantUrl(
    Model $tenant
): ?string;

Mengembalikan:

php

null

jika Panel belum menentukan:

php

tenantUrlUsing()

Contoh:

php

panel('app')
    ->getTenantUrl(
        $workspace
    );

// '/app/documents?workspace=41'

`hasTenancy()`

Signature:

php

public function hasTenancy():
    bool;

Digunakan framework untuk mengetahui apakah Panel menggunakan Tenant.

Contohnya oleh:

php

PanelRouteRegistrar

untuk menentukan apakah ResolveTenant perlu ditambahkan.

Juga digunakan oleh:

php

Resource::applyTenantScope()

`getTenantModel()`

Signature:

php

/**
 * @return class-string<Model>|null
 */
public function getTenantModel():
    ?string;

Contoh:

php

$panel =
    panel('app');

$panel->hasTenancy();
// true

$panel->getTenantModel();
// 'App\Models\Workspace'

`resolveTenant()`

Signature:

php

public function resolveTenant(
    Request $request,
    ?Authenticatable $user
): ?Model;

Method menjalankan resolver yang diberikan pada:

php

tenant()

Method ini digunakan oleh:

php

ResolveTenant

dan bukan API umum yang perlu dipanggil dari berbagai tempat.

Contoh:

php

$tenant =
    panel('app')
        ->resolveTenant(
            request(),
            request()->user()
        );

Resolver Harus Mengembalikan Model yang Benar

Jika Panel mendeklarasikan:

php

Workspace::class

tetapi resolver secara tidak sengaja mengembalikan:

php

User

framework menganggap hasilnya:

php

null

atau:

text

Tenant tidak ditemukan

Ini lebih aman daripada menggunakan object salah sebagai Tenant lalu membuat query terlihat seolah-olah berhasil di-scope.

`PandaPanel\Resources\Resource`

Tenant configuration pada Resource:

php

/**
 * Relationship yang mengarah
 * ke Tenant.
 *
 * null berarti tenancy tidak
 * diterapkan pada Resource.
 */
protected static ?string
    $tenantRelationship =
        null;

public static function tenantRelationship():
    ?string;

/**
 * @param Builder<covariant Model> $query
 * @return Builder<covariant Model>
 */
protected static function applyTenantScope(
    Builder $query
): Builder;

Resource Tenancy adalah Opt-In

Resource::query() memanggil:

php

applyTenantScope()

untuk setiap read:

index;
view;
edit;
delete;
bulk;
Action lookup;
Global Search.

Karena itu cukup menentukan relationship:

php

protected static ?string
    $tenantRelationship =
        'workspace';

Contoh:

php

<?php

declare(strict_types=1);

namespace App\Panels\App\Resources\Documents;

use App\Models\Document;
use PandaPanel\Resources\Resource;

final class DocumentResource
    extends Resource
{
    protected static string $model =
        Document::class;

    protected static ?string
        $tenantRelationship =
            'workspace';
}

Dynamic Tenant Relationship

Jika relationship bergantung pada configuration, override:

php

tenantRelationship()

Contoh:

php

public static function tenantRelationship():
    ?string
{
    return config(
        'app.single_database'
    )
        ? 'workspace'
        : null;
}

Urutan Pemeriksaan Tenant Scope

Tiga kondisi diperiksa:

Kondisi	Jika False
`panel()?->hasTenancy()`	Query dikembalikan tanpa perubahan
`static::tenantRelationship() !== null`	Query dikembalikan tanpa perubahan
Tenant sudah di-bind	`PanelRegistrationException` dari `Tenancy::require()`

Kondisi terakhir berbeda.

Jika Resource sudah menyatakan dirinya tenant-scoped tetapi Tenant tidak di-bind:

text

throw

bukan:

text

skip

karena skip dapat membuat seluruh data Tenant terlihat.

Scope Menggunakan `whereHas()`

Secara konsep:

php

$query->whereHas(
    'workspace',

    fn (
        Builder $related
    ) =>
        $related->whereKey(
            $tenant->getKey()
        )
);

Karena menggunakan relationship, beberapa tipe relation dapat bekerja.

Contohnya:

belongsTo;
belongsToMany;
hasOneThrough.

Definition relationship menentukan arti:

Record ini termasuk Tenant tersebut melalui jalur apa?

Resource Tanpa Tenant Relationship

Resource yang memiliki:

php

tenantRelationship() === null

tidak di-scope oleh PandaBear.

Ini benar untuk dua kasus umum.

Database per Tenant

Database connection sudah menjadi tenant boundary.

Tidak diperlukan:

text

WHERE tenant_id = ...

tambahan.

Global Table

Beberapa table memang global.

Contohnya:

countries;
subscription plans;
currencies;
feature definitions.

Semua Tenant membaca data yang sama.

Lihat:

Resource Tenant Scoping

`PandaPanel\Http\Middleware\ResolveTenant`

Signature:

php

/**
 * @param Closure(Request): Response $next
 */
public function handle(
    Request $request,
    Closure $next,
    string $panelId
): Response;

Middleware ini hanya diregistrasikan untuk Panel yang mendeklarasikan:

php

tenant()

Placement-nya berada di bagian akhir middleware Panel.

Secara konsep:

text

Resolve Panel
    ↓
Authentication
    ↓
User diketahui
    ↓
2FA / Email Code
    ↓
Resolve Tenant
    ↓
Controller

Tenant di-resolve setelah user diketahui tetapi sebelum controller dapat melakukan query.

Panel tanpa tenancy tidak mendapatkan middleware ini.

Tiga Langkah Resolve Tenant

Seluruhnya harus berhasil.

1. Resolve Tenant

php

Panel::resolveTenant()

digunakan untuk mengidentifikasi Tenant.

Jika hasilnya null:

php

abort(
    404,
    'No such tenant.'
);

2. Authorize User

php

Tenancy::allows()

memeriksa user.

Jika false:

php

abort(403);

3. Bind Tenant

Jika Tenant ada dan user boleh mengakses:

php

Tenancy::bind(
    $tenant
);

dijalankan satu kali.

Flow:

text

ResolveTenant
    ↓
resolveTenant()
    ↓
Tenant ditemukan?
├── no
│   ↓
│   404
│
└── yes
    ↓
Tenancy::allows()
    ↓
allowed?
├── no
│   ↓
│   403
│
└── yes
    ↓
Tenancy::bind()
    ↓
Continue request

Tidak Ada Middleware Alias untuk `ResolveTenant`

Alias middleware yang diregistrasikan:

text

panel
panel.two-factor
panel.email-code
panel.parent

ResolveTenant tidak memiliki alias.

Jika Anda mendaftarkan route tenant-aware secara manual di luar route group PandaBear, gunakan class secara langsung.

Contoh:

php

use Illuminate\Support\Facades\Route;
use PandaPanel\Http\Middleware\ResolvePanel;
use PandaPanel\Http\Middleware\ResolveTenant;

Route::middleware([
    'web',

    'auth',

    ResolvePanel::class
        . ':app',

    ResolveTenant::class
        . ':app',
])
    ->get(
        '/app/report',
        ReportController::class
    );

Apa yang Diterima Frontend

Middleware:

php

PandaPanel\Http\Middleware\SharePanelData

membagikan prop:

text

tenancy

pada setiap Panel response.

Prop ini menggunakan Closure.

Dengan begitu jika screen tidak membutuhkan Tenant Switcher, query untuk mendapatkan available Tenant dapat tetap lazy.

Type frontend:

type PanelTenant = {
    key: number | string
    name: string
    url: string | null
    current: boolean
}

type Tenancy = {
    current: PanelTenant | null
    available: PanelTenant[]
} | null

Panel Tanpa Tenancy

Untuk Panel yang tidak menggunakan tenancy:

tenancy === null

Bukan:

{
    current: null,
    available: [],
}

Ini membuat frontend dapat memeriksa dengan jelas:

if (tenancy === null) {
    // Panel tidak menggunakan tenancy.
}

`available`

List:

text

available

berasal dari:

php

Tenancy::availableTo()

Jadi Tenant Switcher tidak menawarkan Tenant yang menurut application memang tidak tersedia untuk user.

Contoh test:

php

$this
    ->get(
        '/app/documents?workspace=1'
    )
    ->assertInertia(
        fn (
            AssertableInertia $page
        ) =>
            $page
                ->where(
                    'tenancy.current.name',
                    'Acme'
                )
                ->where(
                    'tenancy.available.0.current',
                    true
                )
    );

Lihat:

Tenant Switcher

Exceptions

Ketiga exception tenancy berikut menggunakan:

php

PandaPanel\Exceptions\PanelRegistrationException

Factory	Dilempar oleh	Arti
`noCurrentTenant()`	`Tenancy::require()`	Tenant-scoped read dijalankan tetapi tidak ada Tenant yang di-bind
`unknownTenantRelationship(string $resource, string $model, string $relation)`	`Resource::applyTenantScope()`	`$tenantRelationship` menunjuk method yang tidak ada pada model
`tenantRelationshipIsNotARelation(string $resource, string $model, string $relation)`	`Resource::applyTenantScope()`	Method ada tetapi return-nya bukan Eloquent `Relation`

Testing Missing Tenant

Contoh:

php

use PandaPanel\Exceptions\PanelRegistrationException;
use PandaPanel\Tenancy\Tenancy;

expect(
    fn () =>
        DocumentResource::query()
            ->get()
)
    ->toThrow(
        PanelRegistrationException::class
    );

Dengan Tenant:

php

expect(
    Tenancy::for(
        $workspace,

        fn () =>
            DocumentResource::query()
                ->count()
    )
)
    ->toBe(2);

Mengapa Relationship Error Memiliki Exception Khusus

Tanpa validation, Eloquent whereHas() terhadap method yang bukan relation dapat menghasilkan error seperti:

text

Call to a member function getRelated() on null

Pesan tersebut hanya menjelaskan internal Eloquent.

Tidak memberi tahu:

Resource mana;
model mana;
property $tenantRelationship mana;

yang menyebabkan masalah.

PandaBear menggantinya dengan exception yang lebih actionable.

Gotchas

Tenant Scope Menggunakan Primary Key, Bukan `getTenantKey()`

Ini detail penting.

Resource scoping menggunakan:

php

$tenant->getKey()

melalui:

php

whereKey()

Sedangkan:

php

Tenancy::keyOf()

Tenancy::describe()

dan Tenant Switcher dapat menggunakan:

php

PanelTenant::getTenantKey()

Contohnya Tenant:

text

database primary key:
41

public Tenant key:
acme

URL dapat menggunakan:

text

workspace=acme

Switcher dapat menampilkan identifier:

text

acme

tetapi Resource scope tetap menggunakan:

text

id = 41

Ini behavior yang disengaja.

Jadi jangan heran jika query log menggunakan numeric primary key walaupun URL menggunakan slug.

`Tenancy::bind()` Bukan Entry Point Application

Jangan:

php

foreach (
    $tenants as $tenant
) {
    Tenancy::bind(
        $tenant
    );

    // ...
}

Karena setelah loop, Tenant terakhir tetap ter-bind selama scoped context tersebut belum dibersihkan.

Gunakan:

php

Tenancy::for()

karena Tenant sebelumnya selalu dipulihkan, termasuk jika callback melempar exception.

Queued Job Tidak Memiliki Tenant Secara Otomatis

PanelContext merupakan:

php

scoped()

Queue worker membersihkan scoped instances di antara job.

Artinya queued job tidak mewarisi current Tenant dari HTTP request.

Job harus membawa Tenant identifier di payload.

Kemudian worker harus masuk kembali ke Tenant tersebut menggunakan:

php

Tenancy::for()

Secara konsep:

text

HTTP Request
Tenant = Acme
    ↓
Dispatch Job
payload tenant_id = 41
    ↓
Worker
current Tenant = null
    ↓
Resolve Tenant 41
    ↓
Tenancy::for($tenant)
    ↓
Run tenant-aware work

Lihat:

Queues and Tenant Context

Resolver dengan Wrong Class Menghasilkan 404

Misalnya:

php

->tenant(
    Workspace::class,
    fn () =>
        auth()->user()
)

Resolver menghasilkan:

php

User

padahal model yang dideklarasikan:

php

Workspace

Framework memeriksa:

php

$tenant instanceof $model

Jika salah:

text

resolveTenant() → null

kemudian middleware menghasilkan:

text

Bukan runtime type confusion.

Perbedaan 404 dan 403

Tenancy membedakan dua kondisi.

404

text

Tenant tidak dapat diidentifikasi

Contohnya:

text

workspace=does-not-exist

hasil:

text

403

Tenant berhasil ditemukan tetapi user tidak boleh memasukinya.

Contoh:

text

workspace=2 exists
+
user hanya memiliki workspace=1

hasil:

text

PandaBear sengaja tidak menyamarkan semuanya sebagai 404.

Menurut desain sumber:

User sudah harus mengetahui/menyebut Tenant identifier untuk mencapai kondisi tersebut, sehingga menyembunyikan keberadaan Tenant tidak memberikan manfaat yang sebanding dengan hilangnya error yang jelas.

Tenancy adalah Property Panel, Bukan Resource

Resource yang sama dapat memiliki behavior berbeda berdasarkan Panel.

Contoh:

text

Admin Panel
→ no tenancy
→ DocumentResource melihat semua records

App Panel
→ tenancy enabled
→ DocumentResource scoped ke current Workspace

Karena:

php

Resource::applyTenantScope()

memeriksa current Panel terlebih dahulu.

Artinya Anda tidak harus membuat:

text

AdminDocumentResource
TenantDocumentResource

hanya untuk perbedaan tenancy tersebut.

Panel Diregistrasikan saat Boot, Tenant Di-resolve per Request

Panel registration terjadi ketika application boot.

Tenant baru diketahui ketika request datang.

Karena itu jangan mencoba membuat:

text

satu Panel per Tenant

secara dinamis.

Contoh yang tidak sesuai konsep:

text

AdminPanelForTenant1
AdminPanelForTenant2
AdminPanelForTenant3

Gunakan satu Panel.

Perbedaan per-Tenant dapat dinyatakan melalui mekanisme seperti:

php

Resource::canViewAny()

Panel::canAccess()

atau runtime configuration yang memang request-aware.

Ringkasan Arsitektur Tenancy

text

Panel
│
├── Tenant Model
│
├── Tenant Resolver
│
└── Tenant URL Builder
│
└───────────────┐
                │
HTTP Request    │
    ↓           │
ResolvePanel    │
    ↓           │
Authentication  │
    ↓           │
ResolveTenant ←─┘
    ↓
Tenant exists?
    ↓
User allowed?
    ↓
Tenancy::bind()
    ↓
PanelContext
    ↓
Resource::query()
    ↓
applyTenantScope()

Ringkasan Three-Part Contract

text

PANEL
─────
Menjawab:
"Tenant request ini siapa?"

tenant(
    Workspace::class,
    resolver
)


USER
────
Menjawab:
"Tenant mana yang ditawarkan?"
"Tenant ini boleh dimasuki?"

HasPanelTenants


RESOURCE
────────
Menjawab:
"Record terhubung ke Tenant
 lewat relationship apa?"

$tenantRelationship

Ketiganya memiliki tanggung jawab berbeda.

Ringkasan Tenant Resolution

text

Request
    ↓
Panel::resolveTenant()
    ↓
Tenant Model?
├── no
│   ↓
│   404
│
└── yes
    ↓
Tenancy::allows()
    ↓
allowed?
├── no
│   ↓
│   403
│
└── yes
    ↓
Tenancy::bind()
    ↓
Controller

Ringkasan Resource Scoping

text

Resource::query()
        ↓
Panel has tenancy?
├── no
│   ↓
│   unchanged
│
└── yes
    ↓
tenantRelationship?
├── no
│   ↓
│   unchanged
│
└── yes
    ↓
Tenancy::require()
    ↓
Tenant exists?
├── no
│   ↓
│   exception
│
└── yes
    ↓
whereHas(
    relationship,
    whereKey(
        tenant primary key
    )
)

Ringkasan `availableTo()` vs `allows()`

text

getPanelTenants()
        ↓
availableTo()
        ↓
Tenant Switcher
        ↓
DISPLAY CONCERN

Berbeda dengan:

text

canAccessPanelTenant()
        ↓
allows()
        ↓
ResolveTenant
        ↓
403 / Continue
        ↓
SECURITY CONCERN

Jangan menyamakan kedua mekanisme tersebut.

Ringkasan `Tenancy::for()`

text

Tenant sebelum:
A
    ↓
Tenancy::for(B)
    ↓
Bind B
    ↓
Run callback
    ↓
callback selesai
atau exception
    ↓
finally
    ↓
Restore A

Jika awalnya tidak ada Tenant:

text

null
→ B
→ null

Ringkasan Database-per-Tenant

Jika database connection sudah di-switch oleh infrastructure lain:

text

Request
    ↓
stancl/tenancy
    ↓
DB connection = Tenant A
    ↓
PandaBear ResolveTenant
    ↓
Current Tenant = Tenant A
    ↓
Resource tenantRelationship = null
    ↓
No additional whereHas scope

Ini valid.

PandaBear tidak harus menambahkan tenant foreign-key scope jika database itu sendiri sudah menjadi boundary.

Ringkasan Single-Database Tenancy

text

Shared Database
    ↓
Workspace 1
Workspace 2
Workspace 3
    ↓
Document
belongsTo Workspace
    ↓
$tenantRelationship =
    'workspace'
    ↓
Resource::query()
    ↓
whereHas workspace = current Tenant

Ringkasan Frontend Payload

tenancy = {
    current: {
        key: 41,
        name: 'Acme',
        url: '/app/documents?workspace=41',
        current: true,
    },

    available: [
        // ...
    ],
}

Panel tanpa tenancy:

tenancy = null

Ringkasan Failure Modes

text

Tenant identifier tidak ditemukan
→ 404

Tenant ditemukan tetapi user ditolak
→ 403

Resource membutuhkan Tenant tetapi
current Tenant tidak di-bind
→ PanelRegistrationException

tenantRelationship tidak ada pada model
→ PanelRegistrationException

tenantRelationship method ada tetapi
bukan Eloquent Relation
→ PanelRegistrationException

resolver mengembalikan model type salah
→ dianggap null
→ 404

Prinsip Utama Tenancy

PandaBear memisahkan tenancy menjadi tiga concern:

text

Identification
→ Panel::tenant()

Authorization
→ HasPanelTenants

Data Scoping
→ Resource::$tenantRelationship

Framework tidak mencoba menentukan bagaimana application Anda menjalankan multi-tenancy.

Application dapat menggunakan:

text

single database
database per tenant
subdomain
path
query string
user-owned workspace
stancl/tenancy
custom tenancy package

selama Panel dapat menjawab:

Tenant request ini siapa?

dan User dapat menjawab:

Apakah Tenant tersebut boleh diakses?

serta Resource dapat menjawab, jika diperlukan:

Bagaimana record ini terhubung dengan Tenant?

Prinsip security terpentingnya:

Resource yang mendeklarasikan tenant scope tidak pernah fallback ke query tanpa Tenant. Jika Tenant seharusnya ada tetapi tidak di-bind, framework gagal dengan keras daripada mengembalikan data seluruh Tenant.

Prinsip lifecycle terpentingnya:

Panel diregistrasikan saat application boot, tetapi Tenant di-resolve per request dan disimpan dalam request-scoped PanelContext, sehingga context Tenant tidak menjadi global mutable state.

Dan untuk background processing:

Queue, console, dan process di luar HTTP request harus membawa Tenant context secara eksplisit dan memasuki Tenant melalui Tenancy::for().

Tenancy ​

Ini Bukan Implementasi Multi-Tenancy ​

Contoh Minimal yang Berfungsi ​

1. Panel Mendeklarasikan Tenant ​

2. User Menentukan Tenant yang Boleh Diakses ​

3. Resource Menentukan Tenant Relationship ​

PandaPanel\Tenancy\Tenancy ​

API Tenancy ​

bind() ​

Siapa yang Seharusnya Memanggil bind() ​

current() ​

require() ​

Mengapa Missing Tenant Harus Throw ​

key() ​

keyOf() ​

nameOf() ​

describe() ​

availableTo() ​

allows() ​

for() ​

Kapan Menggunakan for() ​

PandaPanel\Contracts\PanelTenant ​

Tanpa PanelTenant ​

PandaPanel\Contracts\HasPanelTenants ​

Dua Pertanyaan yang Berbeda ​

User Tanpa HasPanelTenants ​

PandaPanel\Core\Panel ​

tenant() ​

Tenant Resolver ​

Contoh Database per Tenant ​

Contoh Single Database dengan Path Segment ​

Contoh Satu Tenant per User ​

tenantUrlUsing() ​

Contoh Subdomain Tenant ​

Contoh Path Tenant ​

Jika tenantUrlUsing() Tidak Ada ​

getTenantUrl() ​

hasTenancy() ​

getTenantModel() ​

resolveTenant() ​

Resolver Harus Mengembalikan Model yang Benar ​

PandaPanel\Resources\Resource ​

Resource Tenancy adalah Opt-In ​

Dynamic Tenant Relationship ​

Urutan Pemeriksaan Tenant Scope ​

Scope Menggunakan whereHas() ​

Resource Tanpa Tenant Relationship ​

Database per Tenant ​

Global Table ​

PandaPanel\Http\Middleware\ResolveTenant ​

Tiga Langkah Resolve Tenant ​

1. Resolve Tenant ​

2. Authorize User ​

3. Bind Tenant ​

Tidak Ada Middleware Alias untuk ResolveTenant ​

Apa yang Diterima Frontend ​

Panel Tanpa Tenancy ​

available ​

Exceptions ​

Testing Missing Tenant ​

Mengapa Relationship Error Memiliki Exception Khusus ​

Gotchas ​

Tenant Scope Menggunakan Primary Key, Bukan getTenantKey() ​

Tenancy::bind() Bukan Entry Point Application ​

Queued Job Tidak Memiliki Tenant Secara Otomatis ​

Resolver dengan Wrong Class Menghasilkan 404 ​

Perbedaan 404 dan 403 ​

404 ​

403 ​

Tenancy adalah Property Panel, Bukan Resource ​

Panel Diregistrasikan saat Boot, Tenant Di-resolve per Request ​

Ringkasan Arsitektur Tenancy ​

Ringkasan Three-Part Contract ​

Ringkasan Tenant Resolution ​

Ringkasan Resource Scoping ​

Ringkasan availableTo() vs allows() ​

Ringkasan Tenancy::for() ​

Ringkasan Database-per-Tenant ​

Ringkasan Single-Database Tenancy ​

Ringkasan Frontend Payload ​

Tenancy

Ini Bukan Implementasi Multi-Tenancy

Contoh Minimal yang Berfungsi

1. Panel Mendeklarasikan Tenant

2. User Menentukan Tenant yang Boleh Diakses

3. Resource Menentukan Tenant Relationship

`PandaPanel\Tenancy\Tenancy`

API `Tenancy`

`bind()`

Siapa yang Seharusnya Memanggil `bind()`

`current()`

`require()`

Mengapa Missing Tenant Harus Throw

`key()`

`keyOf()`

`nameOf()`

`describe()`

`availableTo()`

`allows()`

`for()`

Kapan Menggunakan `for()`

`PandaPanel\Contracts\PanelTenant`

Tanpa `PanelTenant`

`PandaPanel\Contracts\HasPanelTenants`

Dua Pertanyaan yang Berbeda

User Tanpa `HasPanelTenants`

`PandaPanel\Core\Panel`

`tenant()`

Tenant Resolver

Contoh Database per Tenant

Contoh Single Database dengan Path Segment

Contoh Satu Tenant per User

`tenantUrlUsing()`

Contoh Subdomain Tenant

Contoh Path Tenant

Jika `tenantUrlUsing()` Tidak Ada

`getTenantUrl()`

`hasTenancy()`

`getTenantModel()`

`resolveTenant()`

Resolver Harus Mengembalikan Model yang Benar

`PandaPanel\Resources\Resource`

Resource Tenancy adalah Opt-In

Dynamic Tenant Relationship

Urutan Pemeriksaan Tenant Scope

Scope Menggunakan `whereHas()`

Resource Tanpa Tenant Relationship

Database per Tenant

Global Table

`PandaPanel\Http\Middleware\ResolveTenant`

Tiga Langkah Resolve Tenant

1. Resolve Tenant

2. Authorize User

3. Bind Tenant

Tidak Ada Middleware Alias untuk `ResolveTenant`

Apa yang Diterima Frontend

Panel Tanpa Tenancy

`available`

Exceptions

Testing Missing Tenant

Mengapa Relationship Error Memiliki Exception Khusus

Gotchas

Tenant Scope Menggunakan Primary Key, Bukan `getTenantKey()`

`Tenancy::bind()` Bukan Entry Point Application

Queued Job Tidak Memiliki Tenant Secara Otomatis

Resolver dengan Wrong Class Menghasilkan 404

Perbedaan 404 dan 403

404

403

Tenancy adalah Property Panel, Bukan Resource

Panel Diregistrasikan saat Boot, Tenant Di-resolve per Request

Ringkasan Arsitektur Tenancy

Ringkasan Three-Part Contract

Ringkasan Tenant Resolution

Ringkasan Resource Scoping

Ringkasan `availableTo()` vs `allows()`

Ringkasan `Tenancy::for()`

Ringkasan Database-per-Tenant

Ringkasan Single-Database Tenancy

Ringkasan Frontend Payload