README

Standalone Laravel multi-tenancy package for the Artflow CRM platform.

• Domain-based database isolation — each subdomain gets its own MySQL database
• No stancl/tenancy dependency — fully self-contained since v0.8.4.0
• Redis optional — auto-fallback to database store keeps TTFB below 200ms
• Built for Laravel 12, PHP 8.2+, Livewire 3

Requirements

Quick Start

# 1. Install
composer require artflow-studio/tenancy

# 2. Configure and migrate
php artisan af-tenancy:install --no-interaction

# 3. Create a tenant
php artisan tenant:create

# 4. Verify
php artisan tenant:health

Add to .env:

APP_DOMAIN=yourdomain.com
AF_TENANCY_CACHE_STORE=database

How It Works

Every HTTP request to {tenant}.yourdomain.com passes through InitializeTenancyByDomain (auto-prepended to the web group). The middleware resolves the hostname against the central domains table — result cached for 1 hour — and switches Laravel's DB connection to the tenant's database. The connection is restored when the request ends.

Request → InitializeTenancyByDomain
  ↓
  DomainResolver.resolve($host)  ← cache hit (~1ms) or DB JOIN (~3ms)
  ↓
  Tenancy::initialize($tenant)
  ↓
  DatabaseBootstrapper → switch DB
  CacheBootstrapper    → prefix cache keys
  SessionBootstrapper  → scope sessions
  ↓
  [Request handled in tenant context]
  ↓
  Tenancy::end() → restore central DB

Tenant Routes

// Tenant-scoped routes
Route::middleware(['auth', 'tenant.web'])->prefix('business')->group(function () {
    Route::get('/dashboard', BusinessDashboard::class);
});

// Central-only admin routes
Route::middleware(['central.web', 'auth'])->prefix('admin')->group(function () {
    Route::get('/tenants', TenantsIndex::class);
});

// Both central and tenant
Route::middleware(['universal.web'])->group(function () {
    Route::get('/login', LoginPage::class)->name('login');
});

Configuration

config/artflow-tenancy.php key sections:

'central_domains' => [env('APP_DOMAIN', 'localhost')],

'bootstrappers' => [
    \ArtflowStudio\Tenancy\Bootstrappers\DatabaseBootstrapper::class,  // required, first
    // \ArtflowStudio\Tenancy\Bootstrappers\CacheBootstrapper::class,
    // \ArtflowStudio\Tenancy\Bootstrappers\SessionBootstrapper::class,
    // \ArtflowStudio\Tenancy\Bootstrappers\FilesystemBootstrapper::class,
],

'cache' => [
    'resolver_store'          => env('AF_TENANCY_CACHE_STORE', 'database'),
    'resolver_fallback_store' => env('AF_TENANCY_CACHE_FALLBACK_STORE', 'database'),
    'resolver_ttl'            => env('AF_TENANCY_CACHE_TTL', 3600),
],

Helpers

tenancy()               // Tenancy singleton
tenant()                // Active Tenant model or null
get_current_domain()    // Current hostname
tenant_pwa_asset($path) // URL to tenant PWA asset

Artisan Commands

# Tenant lifecycle
php artisan tenant:create
php artisan tenant:list
php artisan tenant:delete {uuid}
php artisan tenant:health

# Database
php artisan tenant:db migrate
php artisan tenant:db migrate --tenant={uuid}
php artisan tenant:connection-test

# SEO & PWA
php artisan tenant:seo:enable --tenant={uuid}
php artisan tenant:pwa:enable --tenant={uuid}

# Diagnostics
php artisan tenancy:performance
php artisan tenant:tinker {uuid}

Testing

$tenant = Tenant::factory()->create();

$tenant->run(function () {
    User::create(['name' => 'Alice', 'email' => 'alice@example.com', 'password' => bcrypt('x')]);
    expect(User::count())->toBe(1);
});

php artisan test tests/Feature/Tenancy/

Documentation

Open docs/index.html in your browser for the full interactive documentation.

Changelog

See CHANGELOG.md.

License

Proprietary — Artflow Studio. Internal use only.