Installation

• Requirements
• Install with Composer
• Publish Config
• Next Steps
  • Configure Sprouts Core
    • Enable Service Overrides
  • Configure your Multitenancy
    • Configure your Identity Resolver
    • Configure your Tenant Provider
    • Configure your Tenancy
    • Set the defaults
  • Setting up Routes
  • Start Building

#Requirements

Sprout has three requirements.

• PHP — 8.2 (^8.2)
• Laravel — 11.31 (^11.31)
• Flysystem Path Prefixing — 3.0 (^3.0)

#Install with Composer

Sprout is available on packagist and can be installed through Composer.

1composer require sprout/sprout

#Publish Config

Once you have Sprout installed, you'll want to publish the config.

1php artisan vendor:publish --provider="Sprout\SproutServiceProvider"

#Next Steps

Now that you have Sprout installed, and the config files published, you can start configuring and implementing Sprout. Before you move on though, you'll want to figure out your answers to the following questions:

• Which of Laravel's default services/features do I want to be tenant-aware?
• How do I want tenants to be identified? Using a subdomain? HTTP header? Session? Etc…
• What are my tenants? Are they Eloquent models or something else?

Your answers to these questions will help point you in the right direction for not only using Sprout, but building your application.

The following are the recommended next steps that will work in most cases. It's possible that your particular use-case and requirements will require additional steps, but will most likely include these.

#Configure Sprouts Core

Sprout comes with two config files, and the best one to start with is the one that configures Sprout itself. There are three options in here, though there's only really one that you should care about at this point.

#Enable Service Overrides

Within the sprout.php config file, right at the bottom, is an option called services. This is an array that contains the service override classes that should be enabled. Sprout ships with the following service overrides:

• Storage
• Jobs
• Cache
• Auth
• Cookies
• Sessions

By default, all are enabled and in an appropriate order. Since you've already asked yourself which parts of Laravel need to be made tenant-aware, you'll know which to comment out/delete, if any.

#Configure your Multitenancy

The second config file that comes with Sprout is the multitenancy config, which lets you configure your implementation.

#Configure your Identity Resolver

Within the multitenancy.php config file, there is an option resolver, which, by default, contains a resolver for all the default drivers. These resolvers are used to resolve a tenant's identifier from a route or request, with each driver's name reflecting where in the request it expects to find it.

The default drivers are as follows:

• Subdomain
• Path
• Header
• Cookie
• Session

#Configure your Tenant Provider

In the same multitenancy.php config file, there's an option called provider, which contains the configuration for each default tenant provider driver that Sprout comes with. Tenant providers are used to retrieve instances of your tenant, whether it's an Eloquent model, simply entity, or something else.

The default drivers are as follows:

• Eloquent
• Database

For most people, their tenant will be an Eloquent model.

#Configure your Tenancy

Once you have your resolver and provider configured, you can finally configure your tenancy within the tenancies option inside the multitenancy.php config file. Tenancies are the different types of tenants your application has, and for most people, there will be only one.

For your tenancy, you'll want to set the provider you're using, which will be the one from the previous step, as well as the tenancy options. The tenancy options configure some base functionality and behaviour of a tenancy. You can read more about those in the configuration part of the documentation, but for most people, the default ones you see should suffice.

#Set the defaults

Finally, you'll want to go to the defaults option within the multitenancy.php file, and update each with the name of the resolver, provider, and tenancy you just configured. This step is entirely optional, but, like with Laravel's auth functionality, this allows you to skip the manual providing of configuration names.

#Setting up Routes

Now that you're all configured, and you have your tenant, whether that's an Eloquent model or something else, you're almost ready to start building. Whatever you're building, you're most likely going to need some routes that require a tenant.

Fortunately, Sprout adds a helper method to the Route facade that makes creating tenanted routes simple.

1Route::tenanted(function () {
2    // Define tenant routes here
3});

This method does also allow you to specify the name of the resolver and the tenancy, in that order.

1Route::tenanted(function () {
2    // Define tenant routes here
3}, 'subdomain', 'tenancy');

The particular identity resolver that you are using may have additional limitations, restrictions or requirements, so please read its documentation in full.

An example of this is that the subdomain driver will require the non-tenanted routes to be wrapped in a route group that explicitly sets the domain name. This is to avoid non-tenanted routes being made available within tenancies.

#Start Building

Now you're all configured, and you've got a place to define your routes, so you can start building your application!

You don't need to write your application in a particular way to make Sprout work, outside anything required by the resolver or provider, though those are mostly architectural limitations. There are only two additional things to be aware of beyond this.

1. If you're using Eloquent for your tenant, your tenant-owned models will require the usage of a trait to hook into the automation.
2. The storage and cache service overrides will require you to create a tenant disk and store, respectively. The specifics of this can be found in their documentation.

Happy building!