# tenancy/multi-tenant: One Laravel Codebase, Many Independent Websites

> The hyn/multi-tenant package lets a single Laravel installation serve multiple hostnames with separate databases, assets and per-tenant logic. It fits agencies and SaaS teams that want isolation without forking the codebase.

**tenancy/multi-tenant** — Run multiple websites using the same Laravel installation while keeping tenant specific data separated for fully independent multi-domain setups, previously github.com/hyn/multi-tenant

- Repository: https://github.com/tenancy/multi-tenant
- Website: https://tenancy.dev
- Stars: 2,604 · Forks: 397
- Language: PHP
- License: MIT
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/tenancy-multi-tenant

## The problem tenancy/multi-tenant solves for Laravel teams

A Laravel application normally assumes one database and one hostname. When a marketing agency takes on a second client, or a startup wants to onboard a second customer, the usual answers are a second deployment or a shared database with a tenant_id column on every table. The first duplicates maintenance; the second weakens data separation and forces every query to be tenant-aware.

tenancy/multi-tenant targets the middle ground. The README describes it as "the unobtrusive Laravel package that makes your app multi tenant", serving "multiple websites, each with one or more hostnames from the same codebase" while keeping "clear separation of assets, database and the ability to override logic per tenant". The stated audience is explicit: marketing companies reusing functionality across clients, and startups building a software as a service. The package name on Packagist remains hyn/multi-tenant even though the repository moved to the tenancy organisation, so both names appear in dependency files and documentation.

## Event driven tenancy and the three database strategies

The architecture is event driven rather than middleware driven. Rather than wrapping every request in a filter that rewrites queries, the package hooks into the request lifecycle and fires events that your application can listen to. The README calls this an "Event driven, extensible architecture" and lists tenant specific configs, code and routes as things you can add per tenant.

The interesting part is that database separation is a strategy, not a fixed design. The README lists three methods. The default is one system database plus separated tenant databases. The second is table prefixes inside the system database, which keeps everything on one MySQL or PostgreSQL server. The third is described bluntly as "manually, the way you want, by listening to an event". That last option is the honest one: if your isolation model does not match the first two, you write the listener yourself. The system database holds the mapping from hostname to tenant, which is why the installation step migrates a specific connection rather than the default one.

There is also optional webserver integration. The README frames it as "Close - optional - integration into the web server", and the manual registration instructions separate Hyn\Tenancy\Providers\TenancyProvider from Hyn\Tenancy\Providers\WebserverProvider, which confirms that the webserver layer is a distinct component you can leave out.

## Installing tenancy/multi-tenant and running the first migration

The package installs through Composer. The README gives the package name as hyn/multi-tenant, and the requirements section states Laravel 9.0+, PHP 8.0+, Apache or Nginx, and MySQL, MariaDB or PostgreSQL.

```bash
composer require hyn/multi-tenant
```

Laravel's package auto discovery picks the service providers up without further work. If you want to disable webserver integration or register providers yourself, the README shows a dont-discover entry in the application composer.json:

```json
{
    "extra": {
        "laravel": {
            "dont-discover": [
                "hyn/multi-tenant"
            ]
        }
    }
}
```

With auto discovery disabled, you register the providers manually in config/app.php. The README lists two, and the second one is the webserver integration you can omit:

```php
    'providers' => [
        // [..]
        // Hyn multi tenancy.
        Hyn\Tenancy\Providers\TenancyProvider::class,
        // Hyn multi tenancy webserver integration.
        Hyn\Tenancy\Providers\WebserverProvider::class,
    ],
```

Next you publish the configuration and migration files. The README warns that you should then open config/tenancy.php and config/webserver.php and modify them, and that the system connection must already exist in database.php. If you did not override the system connection name, the default connection is used.

```bash
php artisan vendor:publish --tag tenancy
```

The migration command names the system connection explicitly, which is the detail that trips people up. Running a plain php artisan migrate here would target the wrong database.

```bash
php artisan migrate --database=system
```

After that you have the system tables the package needs. Tenant provisioning, hostname mapping and per-tenant configuration are covered in the documentation at tenancy.dev rather than in the README.

## Where tenancy/multi-tenant is the wrong tool

The package does not isolate resources. Every tenant shares one PHP process pool, one set of environment variables and one filesystem unless you build separation yourself. A tenant that triggers a heavy query or consumes memory affects the others. If your customers require dedicated CPU, memory or network boundaries, a container or server per tenant is the correct shape, and this package will not get you there.

The default database strategy also means one database server holds every tenant's data. Separate schemas reduce accidental cross-tenant queries, but they are not a security boundary against a compromised application process. A bug that lets a request switch the active tenant is a bug that exposes another customer's rows.

Release cadence is the other constraint. The most recent release listed is 5.9.1 from 2023-08-18, described as Laravel 9 backward compatibility, following 5.9.0 for Laravel 10 in July 2023. The repository's last push was on 2026-05-30, so work continues on the 5.x branch, but the published tags lag well behind current Laravel releases. If your application tracks the newest Laravel version closely, verify compatibility before you plan around this package.

Finally, the README carries a warning about the test suite: running the tests resets the current application, dropping tenant and system data. Do not run vendor/bin/phpunit on a database you care about. The README suggests LIMIT_UUID_LENGTH_32=1 vendor/bin/phpunit when using MySQL.

```bash
LIMIT_UUID_LENGTH_32=1 vendor/bin/phpunit
```

## How this differs from stancl/tenancy and single-database tenancy

The obvious alternative in the Laravel ecosystem is stancl/tenancy, which also targets multi-database tenancy but is built around a different set of primitives. The practical difference is in how tenancy is entered. This package leans on events and optional webserver integration, so the hostname resolution can happen before the request reaches PHP, and your listeners decide what a tenant switch means. stancl/tenancy centres on a tenant object with methods that boot and end tenancy explicitly in application code, plus a job and cache pipeline that carries the tenant context across queued work.

Neither approach is free. With an event driven model you get flexibility and you own the wiring: the README's third database strategy, "manually, the way you want, by listening to an event", is the honest description of what that flexibility costs. With an explicit boot model you get predictability and you pay in code that has to call the right methods at the right time.

The other alternative is not a package at all. A single database with a tenant_id column on every table and a global scope is simpler to deploy and simpler to back up, and it is the right answer when tenants are small, numerous, and never need their data extracted. It becomes the wrong answer the moment a customer asks for a database dump of their own data, which is exactly the request that pushes teams toward separated tenant databases in the first place.

## Maintenance cost, upgrade path and the MIT licence

The repository is not archived, and the last push was on 2026-05-30, so the 5.x branch is receiving commits. That is not the same as a steady release stream. The most recent tagged release is 5.9.1 from 2023-08-18, and 5.9.0 before it added Laravel 10 support in July 2023. Anyone running this in production should track the 5.x branch and the changelog.md file rather than assuming a tag will arrive for each new Laravel major version.

Upgrade cost concentrates in two places. The first is Laravel itself: because the package reaches into service providers, the request lifecycle and the database connection layer, a Laravel major upgrade is a real integration test, not a composer update. The second is your own tenancy listeners. Every migration you write has to run against every tenant database, and the package does not remove that operational burden. Budget for a migration runner that iterates tenants and reports failures per tenant.

The licence is MIT, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is a permissive licence with no copyleft obligation and no warranty. It says nothing about your own application's licence, and nothing here should be read as legal advice; check how the notice is preserved in your distribution with whoever handles that for your organisation.

## Conclusion

Adopt tenancy/multi-tenant if you run a Laravel application that must serve several client domains from one codebase and you are prepared to keep the system database and tenant databases in sync yourself. Do not adopt it if you need per-tenant resource isolation, a hosted control plane, or a package whose release cadence matches current Laravel versions. Before committing, verify that your Laravel version is covered by the 5.x branch, that the system connection in config/database.php is the one you intend, and that you can run php artisan migrate --database=system against a staging database without touching tenant data.

## FAQ

### What is tenancy/multi-tenant in Laravel?

It is a Laravel package, published as hyn/multi-tenant, that lets one installation serve multiple websites with one or more hostnames each, while separating assets, database and per-tenant logic. The README describes it as the unobtrusive package that makes your app multi tenant.

### How do I install tenancy/multi-tenant?

Run composer require hyn/multi-tenant, publish the configuration with php artisan vendor:publish --tag tenancy, then run php artisan migrate --database=system. Laravel auto discovery registers the service providers unless you disable it.

### Which database separation methods does tenancy/multi-tenant support?

The README lists three: one system database with separated tenant databases, which is the default; table prefixes inside the system database; or a manual approach implemented by listening to an event.

### What are the disadvantages of multi-tenancy with this package?

Tenants share one PHP process and one filesystem, so there is no resource isolation between them, and the default strategy keeps every tenant's data on one database server. The README also warns that running the test suite resets the application and drops tenant and system data.

### What are some multi-tenant examples?

The README names two: marketing companies that reuse functionality for different clients, and startups building a software as a service. Both map to the same shape, one codebase answering several hostnames.

## Sources

- [License: MIT](https://github.com/tenancy/multi-tenant/blob/5.x/LICENSE)
- [Project website](https://tenancy.dev)
- [README](https://github.com/tenancy/multi-tenant/blob/5.x/README.md)
- [Releases](https://github.com/tenancy/multi-tenant/releases)
- [tenancy/multi-tenant on GitHub](https://github.com/tenancy/multi-tenant)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/tenancy-multi-tenant