README

Multi-tenant support for Laravel applications with flexible tenant resolution, database isolation, and service scoping.

Installation

Step 1: Install the Package

Install from Packagist:

composer require quvel/tenant

Step 2: Publish Configuration

Publish the configuration file to config/tenant.php:

php artisan vendor:publish --tag=tenant-config

Step 3: Publish and Run Migrations

Publish the migrations:

php artisan vendor:publish --tag=tenant-migrations

This publishes:

2024_01_01_000000_create_tenants_table - Main tenants table
2024_01_02_000000_add_tenant_id_to_tables - Adds tenant_id to existing tables

Run the migrations:

php artisan migrate

Step 4: Configure Environment Variables

Add to your .env file:

# Tenant Resolver
TENANT_RESOLVER=Quvel\Tenant\Resolvers\DomainResolver
TENANT_RESOLVER_ENABLE_CACHE=false
TENANT_RESOLVER_CACHE_TTL=300

# Tenant Configuration
TENANT_AUTO_MIDDLEWARE=true
TENANT_DEFAULT_PIPELINE=config,database,mail,filesystem

# Database per Tenant (optional)
# Set to true if each tenant has its own database
TENANT_SEPARATE_DATABASES=false

# Admin UI (optional)
TENANT_ADMIN_ENABLED=false

Step 5: Update User Model

Add the tenant relationship to your User model:

use Quvel\Tenant\Concerns\BelongsToTenant;

class User extends Authenticatable
{
    use BelongsToTenant;

    // Your existing code...
}

Step 6: Verify Installation

Check that the package is discovered:

php artisan package:discover

You should see quvel/tenant in the list.

Test tenant functionality:

php artisan tinker
>>> Quvel\Tenant\Models\Tenant::count()
>>> Quvel\Tenant\Facades\TenantContext::isActive()

Optional: Publish Additional Assets

# Publish language files
php artisan vendor:publish --tag=tenant-lang

Advanced: Custom Route Files

By default, routes are autoloaded from the package. For advanced customization, you can publish and customize route files:

# Publish tenant config API routes (tenant-info endpoints)
php artisan vendor:publish --tag=tenant-config-routes

# Publish tenant admin routes
php artisan vendor:publish --tag=tenant-admin-routes

To use your published routes instead of the package defaults:

Publish the route file(s) you want to customize (commands above)

Disable auto-loading in config/tenant.php:

// For tenant config API routes
'api' => [
    'enabled' => false, // Disable autoloading
    // ... other settings
],

// For tenant admin routes
'admin' => [
    'enabled' => false, // Disable autoloading
    // ... other settings
],

Customize your published route files in routes/tenant-info.php or routes/tenant-admin.php

Note: Most users don't need to publish routes. Use config settings to customize prefixes, middleware, and route names.

Troubleshooting

Package isn't discovered:

Clear bootstrap cache: rm bootstrap/cache/*.php
Run: php artisan package:discover

Migration conflicts: If you get "table already exists" errors, the tables may have been created by another package (like quvel/core). Mark them as migrated:

php artisan tinker
DB::table('migrations')->insert([
    ['migration' => '2024_01_01_000000_create_platform_settings_table', 'batch' => 2],
    ['migration' => '2024_01_01_000001_create_user_devices_table', 'batch' => 2],
]);

Tenant not resolving:

Check TENANT_RESOLVER class is correct
Verify middleware is enabled: TENANT_AUTO_MIDDLEWARE=true
Check domain configuration in tenants table

Configuration

Tenant Model

'model' => \Quvel\Tenant\Models\Tenant::class,

Configures which model class to use for tenant operations. This allows you to extend the base tenant model with custom functionality while keeping the package code model-agnostic.

How it works:

Used by tenant_model() helper function to create new tenant instances
Used by TenantFactory for testing and seeding
Used by resolvers when querying tenants from the database
Enables model customization without modifying package code

Usage example:

// Custom tenant model
class CustomTenant extends \Quvel\Tenant\Models\Tenant
{
    public function customMethod() {
        // Your custom logic
    }
}

// In config/tenant.php
'model' => \App\Models\CustomTenant::class,

The tenant_model() helper function returns a new instance of the configured model:

$tenant = tenant_model(); // Returns new instance of configured model class
$tenant->name = 'New Tenant';
$tenant->save();

Middleware Configuration

'middleware' => [
    'auto_register' => env('TENANT_AUTO_MIDDLEWARE', true),
    'internal_request' => 'tenant.is-internal',
],

auto_register: Controls automatic tenant middleware registration on ALL HTTP requests.

true (default): TenantMiddleware is automatically prepended to the global middleware stack, running on every request
false: Manual middleware registration required - add 'tenant' middleware to specific routes/groups

How it works:

// When auto_register = true
// Middleware runs automatically on all requests

// When auto_register = false, manually add middleware:
Route::middleware(['tenant'])->group(function () {
    Route::get('/dashboard', [DashboardController::class, 'index']);
});

internal_request: Middleware alias for protecting internal/admin endpoints.

Default value: 'tenant.is-internal'
Maps to RequireInternalTenant::class middleware
Used by admin routes to ensure only internal tenants can access admin functionality
Applied automatically to tenant admin UI routes when enabled

Usage in the package:

// Admin routes automatically protected with internal_request middleware
Route::middleware(config('tenant.middleware.internal_request'))
    ->group(__DIR__.'/../routes/tenant-admin.php');

Tenant Resolver Configuration

'resolver' => [
    'class' => env('TENANT_RESOLVER', \Quvel\Tenant\Resolvers\DomainResolver::class),
    'config' => [
        'cache_enabled' => env('TENANT_RESOLVER_ENABLE_CACHE', false),
        'cache_ttl' => env('TENANT_RESOLVER_CACHE_TTL', 300),
    ],
],

class: The resolver class that determines how tenants are identified from HTTP requests.

Default: DomainResolver - resolves tenants by domain name (tenant.example.com)
Must implement TenantResolver interface
Receives config array in constructor

How it works:

// DomainResolver extracts host from request
$identifier = $request->getHost(); // e.g., "tenant.example.com"
$tenant = TenantModel::findByIdentifier($identifier);

config.cache_enabled: Controls whether resolved tenants are cached.

false (default): No caching - resolver called on every request
true: Enables caching using resolver's getCacheKey() method

config.cache_ttl: Cache time-to-live in seconds.

300 (default): Cache resolved tenants for 5 minutes
0: Cache forever (until manually cleared)
Only used when cache_enabled = true

Caching behavior:

// When cache_enabled = true
Cache::remember("tenant.{$cacheKey}", $cacheTtl, function() {
    return $resolver->resolve($request);
});

Available Resolvers:

DomainResolver: Resolve by full domain (tenant.example.com)

Custom Resolver Example:

class SubdomainResolver implements TenantResolver
{
    public function resolve(Request $request)
    {
        $host = $request->getHost();
        $subdomain = explode('.', $host)[0];
        return TenantModel::findByIdentifier($subdomain);
    }

    public function getCacheKey(Request $request): ?string
    {
        return explode('.', $request->getHost())[0];
    }
}

Tenant Not Found Handling

'not_found' => [
    'strategy' => env('TENANT_NOT_FOUND_STRATEGY', 'abort'),
    'config' => [
        // For 'redirect' strategy
        'redirect_url' => env('TENANT_NOT_FOUND_REDIRECT', '/'),

        // For 'custom' strategy
        'handler' => null, // Invokable class name
    ],
],

strategy: Defines what happens when no tenant is found for a request.

'abort' (default): Throws NotFoundHttpException (returns 404 Not Found)
'redirect': Redirects to a specified URL
'custom': Calls a custom handler class or callable

How it works in TenantMiddleware:

protected function handleTenantNotFound(Request $request): never
{
    $strategy = config('tenant.not_found.strategy');
    $config = config('tenant.not_found.config', []);

    match ($strategy) {
        'redirect' => redirect($config['redirect_url'] ?? '/')->send(),
        'custom' => $this->callCustomHandler($config['handler'] ?? null, $request),
        default => throw new NotFoundHttpException('Tenant not found'),
    };
}

config.redirect_url: URL for redirect strategy.

Default: '/' - redirects to homepage
Environment: TENANT_NOT_FOUND_REDIRECT
Only used when strategy = 'redirect'

config.handler: Custom handler for 'custom' strategy.

Must be an invokable class name or callable
Receives the Request object
Example: \App\Handlers\TenantNotFoundHandler::class

Custom Handler Example:

class TenantNotFoundHandler
{
    public function __invoke(Request $request)
    {
        // Custom logic - log, redirect, show special page, etc.
        return response()->view('tenant-not-found', [], 404);
    }
}

// In config
'not_found' => [
    'strategy' => 'custom',
    'config' => [
        'handler' => \App\Handlers\TenantNotFoundHandler::class,
    ],
],

Tenant Config API

'api' => [
    'allow_public_config' => env('TENANT_ALLOW_PUBLIC_CONFIG', false),
    'allow_protected_config' => env('TENANT_ALLOW_PROTECTED_CONFIG', false),
],

Controls access to tenant configuration API endpoints. These endpoints expose tenant config for frontend applications and SSR.

allow_public_config: Enables the public config API endpoint.

false (default): Public config API disabled - throws 404
true: Enables /tenant-info/public endpoint
Returns only config marked with ConfigVisibility::PUBLIC
No authentication required

allow_protected_config: Enables the protected config API endpoint.

false (default): Protected config API disabled - throws 404
true: Enables /tenant-info/protected endpoint
Returns config marked with ConfigVisibility::PUBLIC and ConfigVisibility::PROTECTED
Protected by internal_request middleware

Available API Endpoints:

// Public config (when allow_public_config = true)
GET /tenant-info/public
// Returns: { data: { config: { /* public config only */ } } }

// Protected config (when allow_protected_config = true)
GET /tenant-info/protected
// Returns: { data: { config: { /* public + protected config */ } } }

// Cache endpoint (always requires internal middleware)
GET /tenant-info/cache
// Returns: Collection of all tenant configs for SSR

How it works:

// In TenantPublicConfig action
public function __invoke($tenant): TenantConfigResource
{
    $allowPublicConfig = config('tenant.api.allow_public_config', false);

    if ($allowPublicConfig !== true) {
        throw new NotFoundHttpException('API not enabled for this tenant');
    }

    return new TenantConfigResource($tenant)->setVisibilityLevel('public');
}

Config Visibility Levels:

ConfigVisibility::PRIVATE: Never exposed via API
ConfigVisibility::PROTECTED: Exposed in protected endpoint only
ConfigVisibility::PUBLIC: Exposed in both public and protected endpoints

Use Cases:

allow_public_config: Frontend needs app name, theme colors, public settings
allow_protected_config: SSR needs database config, mail settings, API keys

Configuration Pipes

'pipes' => [
    \Quvel\Tenant\Pipes\CoreConfigPipe::class,
    \Quvel\Tenant\Pipes\BroadcastingConfigPipe::class,
    \Quvel\Tenant\Pipes\CacheConfigPipe::class,
    \Quvel\Tenant\Pipes\DatabaseConfigPipe::class,
    \Quvel\Tenant\Pipes\FilesystemConfigPipe::class,
    \Quvel\Tenant\Pipes\LoggingConfigPipe::class,
    \Quvel\Tenant\Pipes\MailConfigPipe::class,
    \Quvel\Tenant\Pipes\QueueConfigPipe::class,
    \Quvel\Tenant\Pipes\RedisConfigPipe::class,
    \Quvel\Tenant\Pipes\SessionConfigPipe::class,
    \Quvel\Tenant\Pipes\ServicesConfigPipe::class,
    \Quvel\Tenant\Pipes\QuvelCoreConfigPipe::class,

    // Add your custom pipes here
],

Configuration pipes apply tenant config to Laravel's runtime configuration. Pipes are executed in array order during tenant resolution.

How it works:

// In TenantMiddleware, after tenant is resolved:
$this->configPipeline->apply($tenant, config());

// ConfigurationPipeManager loads pipes from config and executes them:
foreach ($this->pipes as $pipe) {
    $pipe->handle($tenant, $config);
}

Available Pipes:

CoreConfigPipe: App settings (app.name, app.url, app.timezone, frontend.url, CORS)
BroadcastingConfigPipe: Pusher, Reverb, broadcasting drivers and credentials
CacheConfigPipe: Cache drivers, Redis configuration, prefixes
DatabaseConfigPipe: Database connections, credentials, isolated databases
FilesystemConfigPipe: Storage disks, S3 configuration, CDN settings
LoggingConfigPipe: Log channels, Sentry configuration, log levels
MailConfigPipe: SMTP settings, mail drivers, from addresses
QueueConfigPipe: Queue drivers (database, Redis, SQS), worker configuration
RedisConfigPipe: Redis connections with tenant prefixing
SessionConfigPipe: Session drivers and tenant isolation
ServicesConfigPipe: Third-party APIs (Stripe, PayPal, payment gateways)
QuvelCoreConfigPipe: Enable tenant scoping for the Quvel Core package

Pipe Implementation:

class CoreConfigPipe extends BasePipe
{
    public function apply(): void
    {
        $this->setMany([
            'app.name',      // Direct 1:1 mapping
            'app.url',
            'frontend.url',
        ]);
    }
}

Custom Pipe Example:

class CustomConfigPipe extends BasePipe
{
    public function apply(): void
    {
        // Set config if tenant has the value
        $this->setIfExists('custom.api_key', 'services.custom.key');

        // Set multiple configs at once
        $this->setMany([
            'custom.endpoint',           // Direct mapping
            'tenant_theme' => 'app.theme', // Custom mapping
        ]);
    }
}

Execution Context:

Executed on every request after tenant resolution
Receives current tenant and Laravel config repository
Can modify any Laravel configuration at runtime
Order matters - later pipes can override earlier ones

Tenant Tables Configuration

'tables' => [
    // Users table with proper tenant isolation
    'users' => [
        'after' => 'id',
        'cascade_delete' => true,
        'drop_uniques' => [['email']],
        'tenant_unique_constraints' => [['email']]
    ],
    'posts' => true, // Simple registration with defaults
    // 'orders' => \App\Tenant\Tables\OrdersTableConfig::class,
],

Defines which application tables should have tenant_id columns added. These tables get automatically modified by TenantTableManager to support tenant isolation.

How it works:

// Process configured tables to add tenant_id columns
$manager = app(\Quvel\Tenant\Managers\TenantTableManager::class);
$results = $manager->processTables();

// Result: ['users' => 'processed', 'posts' => 'skipped_exists']

Configuration Options:

Simple Registration:

'table_name' => true, // Uses default settings

Advanced Configuration:

'users' => [
    'after' => 'id',                           // Insert tenant_id after this column
    'cascade_delete' => true,                  // Cascade delete when tenant is deleted
    'drop_uniques' => [['email']],             // Drop these unique constraints
    'tenant_unique_constraints' => [['email']] // Create tenant-scoped unique constraints
],

Custom Configuration Class:

'orders' => \App\Tenant\Tables\OrdersTableConfig::class,

// OrdersTableConfig.php
class OrdersTableConfig
{
    public function getConfig(): TenantTableConfig
    {
        return new TenantTableConfig(
            after: 'id',
            cascadeDelete: true,
            dropUniques: [['order_number']],
            tenantUniqueConstraints: [['order_number']]
        );
    }
}

What gets added to tables:

tenant_id foreign key column referencing tenants.id
Index on tenant_id for query performance
Optional cascade delete constraint
Tenant-scoped unique constraints (e.g., tenant_id + email unique)

Automatic Service Table Registration: The manager automatically adds system tables when service isolation is enabled:

// When 'queue.auto_tenant_id' = true
'jobs', 'failed_jobs', 'job_batches'

// When 'sessions.auto_tenant_id' = true
'sessions'

// When 'cache.auto_tenant_id' = true
'cache', 'cache_locks'

// When 'password_reset_tokens.auto_tenant_id' = true
'password_reset_tokens'

Processing Results:

'processed': Table successfully updated with tenant_id
'skipped_exists': Table already has tenant_id column
'skipped_missing': Table doesn't exist in database
'error: message': Processing failed with error details

Usage Example:

// Process all configured tables
$manager = app(\Quvel\Tenant\Managers\TenantTableManager::class);
$results = $manager->processTables();

// Process specific tables only
$results = $manager->processTables(['users', 'posts']);

// Remove tenant support
$results = $manager->removeTenantSupport(['old_table']);

Scoped Models Configuration

'scoped_models' => [
    // Add your application models here
    // \App\Models\Post::class,
    // \App\Models\Order::class,

    // Laravel's built-in models
    // \Illuminate\Notifications\DatabaseNotification::class,

    // Sanctum tokens (for API authentication per tenant)
    // \Laravel\Sanctum\PersonalAccessToken::class,

    // Spatie permissions (enable if roles should be tenant-scoped)
    // \Spatie\Permission\Models\Role::class,
    // \Spatie\Permission\Models\Permission::class,
],

Models that should have tenant scoping automatically applied. The package adds global scopes and model events to enforce tenant isolation without requiring code changes.

How it works:

// In TenantServiceProvider::bootExternalModelScoping()
foreach ($models as $modelClass) {
    // Add global scope for automatic WHERE tenant_id filtering
    $modelClass::addGlobalScope(new Scopes\TenantScope());

    // Add model events for automatic tenant_id assignment and validation
    $modelClass::creating(function ($model) {
        if (!isset($model->tenant_id) && !tenant_bypassed()) {
            $model->tenant_id = tenant_id();
        }
    });

    $modelClass::updating(function ($model) {
        $this->validateTenantMatch($model); // Prevent cross-tenant updates
    });

    $modelClass::deleting(function ($model) {
        $this->validateTenantMatch($model); // Prevent cross-tenant deletes
    });
}

Automatic Scoping Behavior:

Query Filtering:

// Automatically scoped to current tenant
$posts = Post::all(); // WHERE tenant_id = current_tenant_id

// Available query macros
$posts = Post::forAllTenants()->get();    // Remove tenant filtering
$posts = Post::withoutTenantScope()->get(); // Same as forAllTenants()
$posts = Post::forTenant(123)->get();       // Filter for specific tenant ID

Model Creation:

// tenant_id automatically assigned
$post = Post::create(['title' => 'New Post']);
// Results in: INSERT ... (title, tenant_id) VALUES ('New Post', current_tenant_id)

Cross-Tenant Protection:

// Prevents updating/deleting models from different tenants
$otherTenantPost = Post::forAllTenants()->where('tenant_id', 999)->first();
$otherTenantPost->update(['title' => 'Hacked']); // Throws TenantMismatchException

Isolated Database Behavior: For tenants using isolated databases, tenant_id scoping is automatically disabled since database-level isolation provides the separation.

No-Tenant Handling: When no tenant context exists:

throw_no_tenant_exception = true: Throws NoTenantException
throw_no_tenant_exception = false: Returns empty results (WHERE 1 = 0)

Bypass Mode:

// Admin operations can bypass tenant scoping
without_tenant(function () {
    return Post::all(); // Returns all posts across all tenants
});

// Or using TenantContext
TenantContext::bypass();
$allPosts = Post::all();

Events Dispatched:

TenantScopeApplied: When scope is applied to a query
TenantScopeNoTenantFound: When no tenant context exists
TenantMismatchDetected: When cross-tenant operation is blocked

Scoping Behavior Configuration

'scoping' => [
    // Whether to throw NoTenantException when no tenant is found
    // When false, returns empty results instead of throwing
    'throw_no_tenant_exception' => env('TENANT_THROW_NO_TENANT_EXCEPTION', true),

    // Whether to automatically add tenant_id to model $fillable arrays
    'auto_fillable' => env('TENANT_AUTO_FILLABLE', true),

    // Whether to automatically add tenant_id to model $hidden arrays
    'auto_hidden' => env('TENANT_AUTO_HIDDEN', true),

    // Skip tenant_id scoping for tenants using isolated databases
    // When true, skip tenant_id scoping for tenants using isolated databases.
    // When false, always use tenant_id scoping for consistency.
    'skip_tenant_id_in_isolated_databases' => env('TENANT_SKIP_WHEN_ISOLATED', false),
],

Configures how tenant scoping behaves across the application.

throw_no_tenant_exception: Controls behavior when no tenant context exists.

true (default): Throws NoTenantException when trying to query tenant-scoped models without tenant context
false: Returns empty results by applying WHERE 1 = 0 condition

How it works:

// In TenantScope::apply()
if (!$tenant) {
    if (config('tenant.scoping.throw_no_tenant_exception', true)) {
        throw new NoTenantException('No tenant context found for model...');
    }

    // Return empty results
    $builder->whereRaw('1 = 0');
}

auto_fillable: Automatically adds tenant_id to model $fillable arrays.

true (default): Models using TenantScoped trait get tenant_id added to $fillable
false: Manual fillable management required

auto_hidden: Automatically adds tenant_id to model $hidden arrays.

true (default): Models using TenantScoped trait get tenant_id added to $hidden (excludes from JSON serialization)
false: Manual hidden management required

How it works:

// In TenantScoped::initializeTenantScoped()
if (config('tenant.scoping.auto_fillable', true) && !in_array('tenant_id', $this->getFillable(), true)) {
    $this->fillable[] = 'tenant_id';
}

if (config('tenant.scoping.auto_hidden', true) && !in_array('tenant_id', $this->getHidden(), true)) {
    $this->hidden[] = 'tenant_id';
}

skip_tenant_id_in_isolated_databases: Controls tenant_id scoping for isolated database tenants.

false (default): Always use tenant_id scoping for consistency across all isolation strategies
true: Skip tenant_id scoping for tenants using isolated databases since database-level isolation provides separation

How it works:

// In TenantScope and model events
if ($this->tenantUsesIsolatedDatabase($tenant)) {
    return; // Skip tenant_id logic - database isolation handles it
}

// Otherwise apply tenant_id scoping
$builder->where('tenant_id', $tenant->id);

Configuration Trade-offs:

throw_no_tenant_exception = false:

Pros: Prevents exceptions during development/testing
Cons: Can hide bugs where tenant context is missing

skip_tenant_id_in_isolated_databases = true:

Pros: Better performance, cleaner database schema for isolated tenants
Cons: Inconsistent behavior between isolation strategies

auto_fillable/auto_hidden = false:

Pros: Full control over model configuration
Cons: Manual configuration required for every tenant-scoped model

Context Preservation

'preserve_context' => env('TENANT_PRESERVE_CONTEXT', true),

Enables automatic tenant context preservation across async operations using Laravel's Context feature. This ensures tenant context is maintained in queued jobs, HTTP requests, and other async operations.

How it works:

// In TenantServiceProvider::registerContextPreservation()
Context::dehydrating(static function ($context): void {
    $tenant = TenantContextFacade::current();

    if ($tenant) {
        $context->addHidden('tenant', $tenant);
    }
});

Context::hydrated(function ($context): void {
    if ($context->hasHidden('tenant')) {
        $tenant = $context->getHidden('tenant');

        TenantContextFacade::setCurrent($tenant);

        app(ConfigurationPipeManager::class)->apply(
            $tenant,
            $this->app->make(ConfigRepository::class)
        );
    }
});

When enabled (true, default):

Tenant context is automatically serialized when Laravel dehydrates context (queued jobs, etc.)
Tenant context is restored when Laravel hydrates context in the worker/async process
Configuration pipes are re-applied to restore tenant-specific settings
Works across queue drivers (database, Redis, SQS, etc.)

When disabled (false):

No automatic context preservation
Async operations lose tenant context
Manual tenant context management required for jobs

Use Cases:

Queued Jobs:

// With preserve_context = true
dispatch(new ProcessOrderJob($order));
// Job automatically has tenant context and config

// With preserve_context = false
dispatch(new ProcessOrderJob($order, tenant_id()));
// Must manually pass tenant_id and restore context

Event Listeners:

// With preserve_context = true
event(new OrderCreated($order));
// Event listeners have tenant context

// With preserve_context = false
// Listeners lose tenant context if queued

HTTP Client Requests:

// With preserve_context = true
Http::post('https://api.service.com', $data);
// Outbound requests can include tenant context via middleware

// With preserve_context = false
// Manual context management for external requests

Performance Considerations:

Minimal overhead - tenant object is serialized/deserialized
Context data travels with async operations
Configuration pipes re-run on context restoration

Requirements:

Laravel 11+ Context feature
Works with all queue drivers that support Laravel Context
No additional setup required

Queue Configuration

'queue' => [
    // Enable tenant-aware database queue with automatic tenant_id column management
    'auto_tenant_id' => env('TENANT_QUEUE_AUTO_TENANT_ID', false),
],

Enables tenant-aware queue behavior for Laravel's database queue driver. When enabled, this automatically adds tenant_id columns to queue tables and scopes queue operations per tenant.

How it works:

// In TenantServiceProvider
if (config('tenant.queue.auto_tenant_id', true)) {
    // Override database queue connector
    $manager->addConnector('database', function () {
        return new TenantDatabaseConnector($this->app['db']);
    });

    // Override failed job provider
    return new TenantDatabaseUuidFailedJobProvider($app['db'], ...);

    // Override batch repository
    return new TenantDatabaseBatchRepository(...);
}

What gets modified:

Queue Tables (jobs):

// In TenantDatabaseQueue::buildDatabaseRecord()
$record = [
    'queue' => $queue,
    'payload' => $payload,
    'tenant_id' => TenantContext::current()?->id, // Added automatically
];

Failed Jobs Table (failed_jobs):

// TenantDatabaseUuidFailedJobProvider adds tenant_id when jobs fail
$failedJob['tenant_id'] = TenantContext::current()?->id;

Job Batches Table (job_batches):

// TenantDatabaseBatchRepository adds tenant_id to batches
$batch['tenant_id'] = TenantContext::current()?->id;

Automatic Table Registration: When enabled, these tables are automatically added to the tables config for TenantTableManager:

// Automatically added tables when auto_tenant_id = true
'jobs' => [
    'after' => 'id',
    'cascade_delete' => true,
],
'failed_jobs' => [
    'after' => 'id',
    'cascade_delete' => true,
],
'job_batches' => [
    'after' => 'id',
    'cascade_delete' => true,
],

Usage Example:

// Jobs automatically get tenant_id when dispatched
dispatch(new ProcessOrderJob($order));

// Failed jobs include tenant_id for isolation
// Batches are tenant-scoped automatically

// Process tables to add tenant_id columns
$manager = app(\Quvel\Tenant\Managers\TenantTableManager::class);
$results = $manager->processTables(['jobs', 'failed_jobs', 'job_batches']);

Requirements:

Database queue driver must be configured in config/queue.php
Queue tables must exist (run queue:table and migrate)
Only affects the database queue driver
Other drivers (Redis, SQS) rely on context preservation

Tenant Context in Jobs:

Jobs automatically retain tenant context via preserve_context
Queue isolation works alongside context preservation
Worker processes restore tenant context and apply configuration pipes

Benefits:

Complete job isolation per tenant
Failed job isolation and debugging
Batch operation isolation
Database-level queue security

Admin Interface Configuration

'admin' => [
    'enable' => env('TENANT_ADMIN_ENABLE', false),
],

Controls the optional admin interface for tenant management. When enabled, provides a web UI and API endpoints for creating and managing tenants using preset configurations.

enable: Enables/disables the admin interface.

false (default): Admin interface disabled for security
true: Enables admin routes, views, and API endpoints

How it works:

// In TenantServiceProvider
if (config('tenant.admin.enable', false)) {
    // Register admin routes with internal middleware protection
    Route::middleware(config('tenant.middleware.internal_request'))
        ->group(__DIR__.'/../routes/tenant-admin.php');

    // Register view namespace for Blade templates
    $this->loadViewsFrom(__DIR__.'/../resources/views', 'tenant');
}

Available Routes (when enabled):

// UI Routes
GET  /admin/tenants/ui              - Tenant management interface

// API Routes (protected by internal middleware)
GET  /admin/tenants/presets         - Get available presets
GET  /admin/tenants/presets/{preset}/fields - Get form fields for preset
GET  /admin/tenants                 - List all tenants
POST /admin/tenants                 - Create new tenant

Admin Interface Features:

Tenant Creation with Presets:

Basic Preset: Shared database with minimal configuration
Isolated Database Preset: Dedicated database with connection settings
Dynamic form generation based on preset requirements
Real-time field validation and error handling

Tenant Listing:

View all existing tenants
Display tenant names, identifiers, and creation dates
Sortable and filterable interface

API Integration:

// Get available presets
GET /admin/tenants/presets
// Response: {"presets": {"basic": {...}, "isolated_database": {...}}}

// Get form fields for a preset
GET /admin/tenants/presets/basic/fields
// Response: {"preset": "basic", "fields": [...]}

// Create tenant
POST /admin/tenants
{
    "name": "Acme Corp",
    "identifier": "acme.example.com",
    "preset": "basic",
    "config": {
        "app.name": "Acme Application",
        "frontend.url": "https://acme.example.com"
    }
}

Security Considerations:

Protected by Internal Middleware:

Admin routes require internal_request middleware
Only internal/system tenants can access admin functionality
Prevents external access to tenant management

Default Disabled:

Admin interface is disabled by default
Must be explicitly enabled via environment variable
Recommended to disable in production environments

Environment Configuration:

// Enable admin interface (development/staging only)
TENANT_ADMIN_ENABLE=true

// Disable admin interface (production - default)
TENANT_ADMIN_ENABLE=false

File Structure:

/resources/views/admin/ui.blade.php  - Main admin interface
/routes/tenant-admin.php            - Admin route definitions
/Http/Controllers/TenantController.php - Admin API endpoints

Use Cases:

Development/staging tenant setup
Internal admin panels
Automated tenant provisioning
Tenant configuration management

Production Recommendations:

Keep enable = false in production
Use programmatic tenant creation instead
Implement custom admin interfaces with proper authentication

quvel / tenant

Maintainers

Details

README

Installation

Step 1: Install the Package

Step 2: Publish Configuration

Step 3: Publish and Run Migrations

Step 4: Configure Environment Variables

Step 5: Update User Model

Step 6: Verify Installation

Optional: Publish Additional Assets

Advanced: Custom Route Files

Troubleshooting

Configuration

Tenant Model

Middleware Configuration

Tenant Resolver Configuration

Tenant Not Found Handling

Tenant Config API

Configuration Pipes

Tenant Tables Configuration

Scoped Models Configuration

Scoping Behavior Configuration

Context Preservation

Queue Configuration

Admin Interface Configuration