Download the PHP package worldesports/laravel-auto-tenancy without Composer

Laravel Auto Tenancy

Post-authentication multi-tenancy for Laravel applications with runtime tenant connection resolution and automatic database switching after login.

What makes this package different?

Most Laravel multi-tenancy packages are commonly used in domain-first or subdomain-first workflows, where the tenant is identified from the request before or independently of user authentication.

worldesports/laravel-auto-tenancy is built for a different workflow:

1. The user logs in or registers first.
2. The application determines the tenant from the authenticated user.
3. The package chooses or builds the correct database connection at runtime for that tenant.
4. The application is automatically switched into the correct tenant database/context.

This makes it a strong fit for Laravel applications where tenancy is resolved after authentication rather than solely from the incoming request host.

Example use case

Your app has a shared login screen for all users.

After authentication:

• user ID 1 should use the tenant/database provisioned for user ID 1
• user ID 2 should use the tenant/database provisioned for user ID 2
• tenant context is determined from the authenticated user by default
• the package switches the application into the correct tenant database/context

Good Fit for This Package

Use this package if your app needs to:

• resolve tenancy after login or registration
• determine the tenant from the authenticated user
• choose or build the correct tenant database connection at runtime
• switch tenant databases automatically
• add tenancy to an existing Laravel auth flow without redesigning the app around domain-first tenancy
• integrate with existing multi-tenant systems

When This May Not Be the Right Fit

If your application is primarily domain-first or subdomain-first and you need broader tenant bootstrapping beyond authenticated-user-driven database switching, another tenancy approach may be a better fit.

Features

• Post-authentication multi-tenancy: Tenants are resolved from authenticated user mappings and switched after login/request authentication
• Runtime connection resolution: The package chooses or builds the correct tenant connection for the authenticated user
• Multiple database support: Each tenant can use a separate database connection
• Minimal configuration: Install quickly with sensible defaults
• Automatic tenant switching: Middleware automatically resolves and switches tenant context
• Model scoping: Traits for tenant-aware model queries
• Database isolation: Complete separation between tenant data
• Multi-driver support: MySQL, PostgreSQL, SQLite, and SQL Server
• Connection caching: Optimized database connection management
• Encryption support: Optional encryption for sensitive connection details
• Comprehensive commands: Full set of Artisan commands for tenant management
• Event listeners: Automatic tenant creation and cleanup
• Security features: Access control and validation
• Testing suite: Comprehensive test coverage

Installation

You can install the package via composer:

Quick installation with setup:

If authentication is missing, the installer will prompt you to install Jetstream:

Or manual installation:

The published config file (config/multi-tenancy.php) contains:

Basic Usage

How the package decides which tenant database to use

The package does not scan existing databases to guess where a user belongs. It uses the central/default Laravel database as the source of truth.

Default mapping:

That means tenant:create is the provisioning step that tells the package which tenant and database belong to a user:

After that, when user ID 123 authenticates and reaches a route using the tenant middleware, the package finds tenants.user_id = 123, chooses that tenant's database, builds the Laravel database connection at runtime, and switches the request to that connection.

Tenant database selection order:

Existing Laravel apps must create these tenant mappings for existing users. The package intentionally does not auto-discover tenant databases by searching every database for matching users.

1. User Model Configuration

The package automatically works with your existing User model. If you're using a custom User model or different namespace:

2. Authentication System Compatibility

Laravel Breeze

Laravel Jetstream

Laravel Sanctum API

Social Authentication

Setup and Usage

1. Register the middleware (optional)

Add the tenant middleware after authentication on routes that need tenant database context:

Use tenant.required when a route must fail if no tenant was resolved:

The login listener can set tenant context during the login request, but middleware is what resolves tenant context on later web/API requests.

2. Add traits to your models

For models that should be automatically scoped to the current tenant database:

For models that have a tenant_id column and need tenant-based scoping:

Usage

Package Status and Management

Creating Tenants

Use the artisan command to create a new tenant. The package supports all major database drivers:

If the database already exists, pass the tenant database credentials and omit --create-db. If you want the command to create the database, pass --create-db plus root/admin credentials. Root/admin credentials are used only by the command and are not stored for runtime tenant switching.

MySQL Tenant (Default)

To create the database too:

PostgreSQL Tenant

SQLite Tenant

SQL Server Tenant

Multi-Driver Support

Your Laravel application can have tenants using different database drivers simultaneously:

• Tenant 1: Uses MySQL on server A
• Tenant 2: Uses PostgreSQL on server B
• Tenant 3: Uses SQLite local file
• Tenant 4: Uses SQL Server on server C

The package automatically handles driver-specific configurations and optimizations.

Database Management

Tenant migrations must live separately from central Laravel/package migrations. By default the package expects:

This prevents central tables like tenants and tenant_databases from being created inside tenant databases.

Tenant Cleanup

Working with Tenants in Code

Querying for a specific tenant (and database) without changing the global context

Note: The package keeps one active tenant database at a time per request/context. You can pick which tenant DB to use, but queries execute against a single selected database, not multiple concurrently.

Tenant Resolution

By default, the package resolves tenants after authentication by matching the authenticated user's primary key to tenants.user_id. That is the recommended production path because it does not trust hostnames or email domains for tenant membership.

When user ID 123 logs in and the tenant middleware runs, the package loads that user's tenant, builds the tenant database connection from the stored tenant_databases.connection_details, and switches the request to that connection.

For existing applications, installing the package does not automatically assign existing users to tenant databases. Create tenant mappings with tenant:create for each user, organization, store, workspace, or customer that should receive a tenant database.

Optional Strategy: Email Domain Detection

Email-domain detection is available, but it is disabled by default. Enable it only if your application treats matching email domains as authorized tenant membership:

Configuration:

Also enable domain-based access if non-owner users should be authorized by exact email-domain match:

Optional Strategy: Subdomain Detection

Subdomain detection is available, but disabled by default and should be paired with Laravel trusted-host protection:

Configuration:

Optional Strategy: Auto-Create Tenants

Auto-create is disabled by default. For production v1 usage, prefer tenant:create because it explicitly provisions the tenant database credentials used for runtime switching:

Configuration:

tenant:create remains the provisioning path for database credentials. Runtime requests do not use root/admin credentials.

Using the Middleware

The SetTenant middleware resolves tenant context for authenticated users. It is non-enforcing by default; use tenant.required on routes that must have tenant context.

Middleware options:

• ignore (default): Continue when no tenant exists
• error: Return JSON error response when no tenant exists
• redirect: Redirect to multi-tenancy.tenant_setup_route when configured

Advanced Configuration

Common Configuration

After publishing config/multi-tenancy.php, common production settings include:

Event Listeners

The package automatically registers these event listeners:

Security Features

Model Scoping Examples

Multi-User & Concurrent Session Support

✅ Multiple Users, Different Tenants

Each authenticated request resolves its own tenant context:

✅ Request Isolation

• Each request receives a fresh tenant context from the authenticated user
• No interference between concurrent users
• Tenant context is reset after the request to support long-lived workers
• Use the tenant middleware on authenticated web/API routes that need tenant data

✅ API & Web Support

Example 1: Social Media Authentication with Multi-Tenancy

Example 2: API Authentication with Sanctum

Example 3: Custom Authentication Guard

Example 4: Multi-Guard Authentication

Example 5: Automated Tenant Creation for New Users

Testing

Changelog

Please see CHANGELOG for more information on what has changed recently.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• worldesports
• All Contributors

License

The MIT License (MIT). Please see License File for more information.