laravel-multi-tenancy

Laravel マルチテナンシー

マルチテナンシーでは、アプリケーションのロジックをセントラル（非テナント）コンテキストとテナント（テナント固有）コンテキストに分離します。

関連ガイド：

• tenancy-testing.md - マルチテナント機能のテスト
• Actions - セントラルとテナントのアクションの整理
• Models - モデルの整理
• structure.md - ディレクトリの整理

基本方針

マルチテナンシーを使用すると、次のことが可能になります。

• セントラルとテナントのコンテキストを明確に分離
• テナントごとに別々のデータベースを使用したデータベースの分離
• 現在のテナントに対するクエリの自動スコープ設定
• ヘルパークラスによるコンテキストの認識
• テナントコンテキストを保持したキューとの連携

使用する場面

次の場合にマルチテナンシーを使用します。

• 完全なデータ分離を備えた SaaS アプリケーションを構築する場合
• 各顧客が独自のデータベースを必要とする場合
• コンプライアンス上、厳格なデータ分離が求められる場合

次の場合は使用しないでください。

• ユーザーのセグメント分けで十分な場合（user_id によるスコープ設定を使用します）
• すべての顧客が同じスキーマを共有する場合
• アプリケーションの複雑さに対して、追加の負荷に見合うメリットがない場合

ディレクトリ構成

app/
├── Actions/
│   ├── Central/          # Non-tenant actions
│   │   ├── Tenant/
│   │   │   ├── CreateTenantAction.php
│   │   │   └── DeleteTenantAction.php
│   │   └── User/
│   │       └── CreateCentralUserAction.php
│   └── Tenanted/         # Tenant-specific actions
│       ├── Order/
│       │   └── CreateOrderAction.php
│       └── Customer/
│           └── CreateCustomerAction.php
├── Data/
│   ├── Central/          # Central DTOs
│   └── Tenanted/         # Tenant DTOs
├── Http/
│   ├── Central/          # Central routes (tenant management)
│   ├── Web/              # Tenant application routes
│   └── Api/              # Public API (tenant-scoped)
├── Models/               # All models in standard location
│   ├── Tenant.php        # Central model
│   ├── Order.php         # Tenanted model
│   └── Customer.php
└── Support/
    └── TenantContext.php

セントラルアクション

セントラルアクションは、テナントの管理やテナントをまたぐ操作を行います。

<?php

declare(strict_types=1);

namespace App\Actions\Central\Tenant;

use App\Data\Central\CreateTenantData;
use App\Models\Tenant;
use Illuminate\Support\Facades\DB;

class CreateTenantAction
{
    public function __construct(
        private readonly CreateTenantDatabaseAction $createDatabase,
    ) {}

    public function __invoke(CreateTenantData $data): Tenant
    {
        return DB::transaction(function () use ($data): Tenant {
            $this->guard($data);
            $tenant = $this->createTenant($data);
            ($this->createDatabase)($tenant);
            return $tenant;
        });
    }

    private function guard(CreateTenantData $data): void
    {
        throw_if(
            Tenant::where('domain', $data->domain)->exists(),
            TenantDomainAlreadyExistsException::forDomain($data->domain)
        );
    }

    private function createTenant(CreateTenantData $data): Tenant
    {
        return Tenant::create([
            'id' => $data->tenantId,
            'name' => $data->name,
            'domain' => $data->domain,
        ]);
    }
}

テナントアクション

テナントアクションは、特定のテナントのコンテキスト内で動作します。すべてのクエリは自動的にスコープ設定されます。

<?php

declare(strict_types=1);

namespace App\Actions\Tenanted\Order;

use App\Data\Tenanted\CreateOrderData;
use App\Models\Order;
use App\Models\User;
use Illuminate\Support\Facades\DB;

class CreateOrderAction
{
    public function __invoke(User $user, CreateOrderData $data): Order
    {
        return DB::transaction(function () use ($user, $data): Order {
            // Automatically scoped to current tenant
            $order = $user->orders()->create([
                'status' => $data->status,
                'total' => $data->total,
            ]);

            $this->createOrderItems($order, $data->items);
            return $order;
        });
    }

    private function createOrderItems(Order $order, array $items): void
    {
        foreach ($items as $item) {
            $order->items()->create([
                'product_id' => $item->productId,
                'quantity' => $item->quantity,
                'price' => $item->price,
            ]);
        }
    }
}

テナントコンテキストヘルパー

<?php

declare(strict_types=1);

namespace App\Support;

use App\Models\Tenant;
use Stancl\Tenancy\Facades\Tenancy;

class TenantContext
{
    public static function current(): ?Tenant
    {
        return Tenancy::tenant();
    }

    public static function id(): ?string
    {
        return Tenancy::tenant()?->getTenantKey();
    }

    public static function isActive(): bool
    {
        return Tenancy::tenant() !== null;
    }

    public static function run(Tenant $tenant, callable $callback): mixed
    {
        return tenancy()->runForMultiple([$tenant], $callback);
    }

    public static function runCentral(callable $callback): mixed
    {
        return tenancy()->runForMultiple([], $callback);
    }
}

使用方法：

use App\Support\TenantContext;

$tenant = TenantContext::current();
$tenantId = TenantContext::id();

if (TenantContext::isActive()) {
    // Tenant-specific logic
}

TenantContext::run($tenant, function () {
    Order::create([...]);
});

TenantContext::runCentral(function () {
    Tenant::create([...]);
});

テナント識別ミドルウェア

ドメインベース

use Stancl\Tenancy\Middleware\InitializeTenancyByDomain;

class IdentifyTenant extends InitializeTenancyByDomain
{
    // Tenant identified by domain (e.g., tenant1.myapp.com)
}

サブドメインベース

use Stancl\Tenancy\Middleware\InitializeTenancyBySubdomain;

class IdentifyTenant extends InitializeTenancyBySubdomain
{
    // Tenant identified by subdomain
}

ヘッダーベース

use Stancl\Tenancy\Middleware\InitializeTenancyByRequestData;

class IdentifyTenant extends InitializeTenancyByRequestData
{
    public static string $header = 'X-Tenant';
}

ルートの設定

テナントルート

// routes/tenant.php
Route::middleware(['tenant'])->group(function () {
    Route::get('/orders', [OrderController::class, 'index']);
    Route::post('/orders', [OrderController::class, 'store']);
});

セントラルルート

// routes/central.php
Route::middleware(['central'])->prefix('central')->group(function () {
    Route::get('/tenants', [TenantController::class, 'index']);
    Route::post('/tenants', [TenantController::class, 'store']);
});

ブートストラップ設定

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(function () {
        Route::middleware('web')
            ->prefix('central')
            ->name('central.')
            ->group(base_path('routes/central.php'));

        Route::middleware(['web', 'tenant'])
            ->group(base_path('routes/tenant.php'));
    })
    ->create();

モデル

すべてのモデルは app/Models/ に配置します。セントラルモデルとテナントモデルは、サブディレクトリではなくトレイトやインターフェースによって区別します。

セントラルモデル

<?php

declare(strict_types=1);

namespace App\Models;

use Stancl\Tenancy\Database\Models\Tenant as BaseTenant;

class Tenant extends BaseTenant
{
    public function users(): HasMany
    {
        return $this->hasMany(User::class);
    }
}

テナントモデル

<?php

declare(strict_types=1);

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Order extends Model
{
    // Automatically scoped to current tenant
    // No tenant_id needed in queries

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

テナントコンテキストを使ったキュージョブ

キューに追加する際は、ジョブでテナントコンテキストを保持する必要があります。

<?php

declare(strict_types=1);

namespace App\Jobs\Tenanted;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Stancl\Tenancy\Contracts\TenantWithDatabase;
use Stancl\Tenancy\Jobs\TenantAwareJob;

class ProcessOrderJob implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, TenantAwareJob;

    public function __construct(
        public TenantWithDatabase $tenant,
        public OrderData $orderData,
    ) {
        $this->onQueue('orders');
    }

    public function handle(ProcessOrderAction $action): void
    {
        // Runs in tenant context automatically
        $action($this->orderData);
    }
}

ディスパッチ：

ProcessOrderJob::dispatch(TenantContext::current(), $orderData);

よくあるパターン

複数のテナントでコードを実行する

$tenants = Tenant::all();

foreach ($tenants as $tenant) {
    TenantContext::run($tenant, function () use ($tenant) {
        Order::where('status', 'pending')->update(['processed' => true]);
    });
}

テナントコンテキストからセントラルデータにアクセスする

TenantContext::runCentral(function () {
    $allTenants = Tenant::all();
});

テナントに基づく条件分岐

if (TenantContext::isActive()) {
    $orders = Order::all(); // Scoped to tenant
} else {
    $tenants = Tenant::all(); // Central
}

テスト

→ テストの完全ガイド：tenancy-testing.md

以下を含みます。

• セントラルアクションとテナントアクションのテスト
• ManagesTenants および RefreshDatabaseWithTenant トレイト
• TenantTestCase のセットアップ
• マルチテナンシー向けの Pest 設定
• テストディレクトリの構成

まとめ

マルチテナンシーで実現できること：

1. 明確な分離 - セントラルとテナントの名前空間を分離
2. データベースの分離 - 各テナント専用のデータベースを用意
3. 自動スコープ設定 - クエリにテナントのスコープを自動設定
4. コンテキストヘルパー - テナントコンテキストに簡単にアクセス
5. キューとの連携 - ジョブでテナントコンテキストを保持

ベストプラクティス：

• ディレクトリ構成を使って、セントラルとテナントのアクション／DTO を分離します
• Laravel の規約に従い、モデルを app/Models/ に配置します
• テナントにアクセスする際は、必ず TenantContext ヘルパーを使用します
• セントラルとテナントのコンテキストをそれぞれ個別にテストします
• キューに追加したジョブではテナントコンテキストを保持します