Skip to content

Latest commit

 

History

History
235 lines (175 loc) · 8.58 KB

installation.md

File metadata and controls

235 lines (175 loc) · 8.58 KB
Raw
section title position slug description
Getting Started
Installation
0
index
A great place to start with Sprout is its installation. In fact, installation is the number one most recommended place to start when using a package.

Requirements

Sprout has three requirements.

Note

The flysystem path prefixing package is only there for tenant-aware storage disks that prefix the path. The decision was made to include it by default to avoid additional installation steps.

Install with Composer

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

composer require sprout/sprout

Warning

You may have to adjust your composer.json if you attempt to install Sprout before its release.

Publish Config

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

php 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:

Warning

Some service overrides will have limitations, restrictions or possibly additional configuration steps. Please read the documentation of your choice in full.

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.

Tip

If there's an additional part of Laravel that isn't covered here, you can look at creating a custom one.

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 resolvers which allows you to configure multiple identity resolvers. By default, this 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:

Warning

Some identity resolvers will have limitations and restrictions regarding other features within Sprout or Laravel itself. Please read the documentation of your choice in full.

Tip

For simplicity, it is recommended that you remove any that you don't currently need.

Configure your Tenant Provider

In the same multitenancy.php config file, there's an option called provider which allows you to configure multiple tenant providers. Tenant providers are used to retrieve instances of your tenant, whether it's an Eloquent model, simply entity, or something else.

Tip

The tenant provider functionality is mirrored from Laravel's auth user provider functionality.

The default drivers are as follows:

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

Tip

Should you wish to use something else as your tenant, you can look into creating a custom tenant provider.

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.

Tip

The tenancies' functionality is mirrored on Laravel's auth guard functionality.

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.

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

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

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

Warning

Both the resolver and tenancy name are nullable and will default to null. If you wish to provide the tenancy name, but not the resolver, you must use null for the resolver.

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!