Skip to content
Tenancy for Laravel

Introduction

Tenancy for Laravel is package for making Laravel applications multi-tenant.

It supports both single-database and multi-database tenancy.

Main features include:

  • Automatic mode (automatically scoping Laravel components to the current tenant)
  • Multiple identification methods out of the box (domains, subdomains, path, request data)
  • Event-based architecture (lets you hook into tenant creation, tenancy initialization, and dozens of other events)

The package was originally released in February 2019. Version 2 was released in October 2019 and version 3 was released in June 2020. This documentation is for version 4 which was released in 2024.

At the time of writing, the package has over 3,300 stars on GitHub and 2 million downloads on Packagist.

The main idea behind this package is automatic multi-tenancy. My motivation for building this package back in 2019 was that I had a large Laravel application that I wanted to turn into a SaaS. Looking into the existing solutions for multi-tenancy, all of them were overly complex and would require that I rewrite significant parts of my codebase just to add multi-tenancy (which seemed more like a feature that I should be able to simply add to an existing application).

With that philosophy in mind, the package was built all around:

  1. Identifying a tenant (generally done using request middleware)
  2. Making Laravel components scope everything to that tenant’s context
  3. The actual application requiring very few changes to be made multi-tenant, ideally zero changes to the core logic being used on tenant pages

This ended up being a popular approach to multi-tenancy, with both Tenancy v3 and the Multi-tenant SaaS boilerplate (released alongside Tenancy v3) being very popular and Tenancy for Laravel becoming the de-facto standard library for implementing multi-tenancy in Laravel.

Important notes

While this package abstracts most of the complexity that comes with multi-tenancy away, it’s important to fully understand a few key concepts before using the package in a real application.

It is not required that you read the entire documentation first, but there are a few pages you should read in full. The rest of the documentation can be read as needed. In other words, you only need to understand a few concepts to get started with the package, and then you can read pages for individual features as you need them.

To make your experience with this package as smooth as possible, the section below which explains the ideal order in which you should go through the pages of this documentation.

How to read this documentation

To understand the fundamental ideas behind this package, read the following pages in full:

  1. What is multi-tenancy: How multi-tenancy differs from applications that simply have user-specific data, and how it’s different to multi-instance applications
  2. How the package works: An explanation of the key mechanisms used by the package to make your application multi-tenant
  3. Getting started: An installation guide accompanied by a quick-start example for having a multi-tenant multi-database application with domain identification in a few simple steps

These three pages are enough to get you up to speed and capable of using the package.

After reading these and setting up the package in your application, you may want to make some configuration changes to use a different tenancy-setup. For that, make sure you read the pages in the Basics and Concepts sections of the documentation.