DEV Community: Abderrahim El Ouariachi

Keep Tenancy Out of Your Laravel App: Structuring stancl/tenancy v4 as a Module

Abderrahim El Ouariachi — Wed, 21 Oct 2026 21:22:35 +0000

When you develop a multi-tenant application, it's easy for the code of your central application to get entangled with the tenant code. Or you start splitting everything into Central and Tenant folders.

Models
  |-> Central
  |-> Tenant

but there is a better way: modules.

In this post, we will talk about how to do that.

The stack I'm using:

Laravel 13
stancl/tenancy v4
Pest 4

How a module is usually structured

First, we need to decide on a structure. Most developers structure their modules like this:

Modules/Billing/
├── src/
│   ├── Domain/
│   ├── Application/
│   └── Http/
├── config/
├── database/
├── routes/
└── tests/

I decided to structure it differently, using the structure you are already used to working with: the default Laravel structure.

modules/
└── Tenancy/
    ├── app/
    │   ├── Http/
    │   │   └── Controllers/
    │   │       └── Controller.php
    │   ├── Models/
    │   │   ├── SomeModel.php
    │   │   └── AnotherModel.php
    │   └── Providers/
    │       ├── TenancyModuleServiceProvider.php
    │       └── TenancyServiceProvider.php
    ├── config/
    │   └── tenancy.php
    ├── database/
    │   ├── factories/
    │   ├── migrations/
    │   └── seeders/
    └── routes/
        └── tenant.php

With this structure, you can easily reason about where to put your code. And if you use PHPStorm, you can use its scopes feature to list only the module code:

The feature is located in Settings -> Appearance & Behavior -> Scopes.

This way, the code of the central application won't bother you.

I decided to leave the frontend code and the tests in there normal folders resources and tests. The tenancy code will never be separated from the central application, because one cannot live without the other, so I like to keep my frontend and my tests in a single place. You can still include those folders in the scope, so only the tests and resources related to Tenancy are shown.

Now that the structure is ready, we need to register the module.

How to register the Tenancy module

The stancl/tenancy v4 package comes with a TenancyServiceProvider and a config file named tenancy.php. We will move them to modules/Tenancy/app/Providers and modules/Tenancy/config respectively. We also need to create our own service provider to register the routes, config files, and providers. It will look something like this:

<?php

declare(strict_types=1);

namespace Modules\Tenancy\App\Providers;

use Illuminate\Support\ServiceProvider;

final class TenancyModuleServiceProvider extends ServiceProvider
{
    protected string $moduleRoot = __DIR__.'/../../';

    /**
     * @var array<int, class-string<TenancyServiceProvider>>
     */
    private array $providers = [
        TenancyServiceProvider::class,
        // Other service providers...
    ];

    public function register(): void
    {
        $this->registerConfigFiles();

        foreach ($this->providers as $provider) {
            $this->app->register($provider);
        }

        $this->loadRoutesFrom($this->moduleRoot.'routes/tenant.php');
    }

    private function registerConfigFiles(): void
    {
        $files = glob($this->moduleRoot.'config/*.php') ?: [];

        // use set to register the config files
        foreach ($files as $file) {
            config()->set(basename($file, '.php'), require $file);
        }
    }
}

Then register the module's provider in bootstrap/providers.php, and remove the old App\Providers\TenancyServiceProvider and config/tenancy.php from the central app:

return [
    App\Providers\AppServiceProvider::class,
   Modules\Tenancy\App\Providers\TenancyModuleServiceProvider::class,
];

After moving the config file, set the migration paths in it to the following:

'migration_parameters' => [
    '--force' => true, // This needs to be true to run migrations in production.
    '--path' => [base_path('modules/Tenancy/database/migrations')],
    '--schema-path' => base_path('modules/Tenancy/database/schema/tenant-schema.dump'),
    '--realpath' => true,
],

Also make sure you set CACHE_STORE in phpunit.xml to file if you're using the RedisTenancyBootstrapper, because it does not work otherwise.

Now we can move on to Composer. After making these updates, you need to register the namespaces in composer.json and run composer dump-autoload:

"autoload": {
    "psr-4": {
        "App\\": "app/",
        "Database\\Factories\\": "database/factories/",
        "Database\\Seeders\\": "database/seeders/",
        "Modules\\Tenancy\\App\\": "modules/Tenancy/app/",
        "Modules\\Tenancy\\Database\\Factories\\": "modules/Tenancy/database/factories/",
        "Modules\\Tenancy\\Database\\Seeders\\": "modules/Tenancy/database/seeders/"
    }
},

Structuring the tests

As I said before, I like to keep the tests in the root tests folder. An easy way to structure them is to split them like this:

tests
├── Central
│   ├── Browser
│   ├── Feature
│   └── Unit
└── Tenant
    ├── Browser
    ├── Feature
    └── Unit

Using PHPStorm's scopes feature, you can include the Tenant folder, so when we select the scope, the modules/Tenancy folder and its tests will be the only ones shown.

If you decide to do this, update the test suites in the phpunit.xml file:

<testsuites>
    <testsuite name="Central">
        <directory>tests/Central</directory>
    </testsuite>
    <testsuite name="Tenant">
        <directory>tests/Tenant</directory>
    </testsuite>
</testsuites>
<source>
    <include>
        <directory>app</directory>
        <directory>modules/Tenancy/app</directory>
    </include>
</source>

Making your tools aware of the module

Laravel Idea

If you use the Laravel Idea plugin, you can make it module-aware. In my case, I'm using PHPStorm.

First, configure how you are using modules. You can find it in Languages & Frameworks -> Laravel Idea -> Module System. Configure it like below:

Next, go to Languages & Frameworks -> Laravel Idea -> Code Generation -> Standard Generation. Set the "Available in modules" flag to true for all the code generation types, and include the path where you want the code to be generated.

Now, just use the shortcut and you will be able to generate code really fast for the Tenancy module. When generating some code, you will be prompted to choose between generating it for the central application or for a specific module.

You can also change the templates used for the generated code, which gives you a lot of freedom when it comes to customization.

Octane

If you're using Octane, you need to set the --watch flag in the server command, like this:

/usr/bin/php -d variables_order=EGPCS /var/www/html/artisan octane:start --watch --server=swoole --host=0.0.0.0 --port='${APP_PORT:-80}'

and add the paths of the module files to the Octane config, like below:

'watch' => [
    'app',
    'bootstrap',
    'config/**/*.php',
    'database/**/*.php',
    'public/**/*.php',
    'resources/**/*.php',
    'routes',
    'modules/Tenancy/routes',
    'modules/Tenancy/app',
    'modules/Tenancy/database/**/*.php',
    'composer.lock',
    '.env',
],

This way, the workers get reloaded when you change the routes or the tenant code.

PHPStan

If you're using PHPStan, you also need to include the Tenancy code. You can do that in the phpstan.neon file in the root of your project:

parameters:
    paths:
        - app/
        - bootstrap/app.php
        - config/
        - database/
        - routes/
        - tests/
        - modules/Tenancy/app
        - modules/Tenancy/database
        - modules/Tenancy/routes

Rector

Like the other tools, Rector needs to know about the module files. You can add the paths to the withPaths method in the rector.php file in the root of your project, like below:

return RectorConfig::configure()
    ->withPaths([
        __DIR__.'/app',
        __DIR__.'/routes',
        __DIR__.'/database',
        __DIR__.'/config',
        __DIR__.'/tests',
        __DIR__.'/modules/Tenancy/app',
        __DIR__.'/modules/Tenancy/routes',
        __DIR__.'/modules/Tenancy/database',
    ])
    ->withComposerBased(laravel: true)
    ->withImportNames()
    ->withPhpSets(php85: true)
    ->withPreparedSets(
        deadCode: true,
        codeQuality: true,
        codingStyle: true,
        typeDeclarations: true,
        typeDeclarationDocblocks: true,
    )
    ->withRules([
        SortTraitUsesByLengthRector::class,
        SortAttributesByLengthRector::class,
    ]);

Conclusion

I think that's all. If I missed something, please let me know in the comments.

Structuring the tenancy code this way makes development easier and faster, because you avoid splitting everything into Central and Tenant folders:

Models
├── Central
├── Tenant
Http
├── Central
├── Tenant
Providers
├── Central
├── Tenant

If this post was useful, please like it, and leave a comment.

Thanks,
www.itsabderrahimel.com

How to Set Up an SSL VPN on a FortiGate 40F (Step-by-Step)

Abderrahim El Ouariachi — Tue, 06 Oct 2026 14:37:29 +0000

Want to reach your local network from anywhere in the world? In this guide, I'll show you how, using a FortiGate 40F and SSL VPN, configured entirely from the command line. Every step is a block you can copy, review and keep in version control.

Heads up: SSL VPN was removed from FortiOS 7.6.3 and later on lower-end models (including the 40F), which are pushed toward IPsec instead. The commands in this guide apply to FortiOS 7.2 and 7.4. Syntax can differ on other branches, so check with ? and tab completion on your own build.

A note on values: every address, name and secret below is an example. Replace anything in <ANGLE_BRACKETS> and change the example subnets to match your network. Never publish or reuse real credentials, public IPs or certificate fingerprints.

What is an SSL VPN?

An SSL VPN lets you connect to a private network that isn't directly reachable from the internet. Traffic is encrypted with TLS (the successor to SSL) and carried over HTTPS, so it usually passes through firewalls that block other VPN protocols.

Why the CLI instead of the web UI?

Repeatable: paste the same blocks on a second firewall or after a factory reset.
Reviewable: you can diff and comment a text file. You can't diff a series of screenshots.
Precise: the CLI shows every option, including the ones the GUI hides.

Prerequisites

A FortiGate 40F with admin access
A Linux machine, or any device with FortiClient, to test the connection
A free TCP port for the VPN (we'll use 10443)
(If behind a router) access to the router to configure port forwarding

Example values used in this guide

Item	Example value
WAN interface	`wan`
LAN interface	`lan`
LAN subnet	`10.20.0.0/24`
VPN client pool	`10.10.10.2` – `10.10.10.254`
VPN listen port	`10443`
User group	`SSL-VPN-GROUP`
Portal	`SSL-VPN-PORTAL`
Example user	`alice`

Step 0: Open the console and back up

You can reach the CLI in three ways:

the CLI Console (>_ icon) in the top bar of the web UI
SSH to the FortiGate's management address
the serial console cable

Back up the current configuration before changing anything:

execute backup config flash "before-ssl-vpn"

Some basics for the rest of the guide:

Each config ... end block opens and closes a configuration section.
Press Tab to complete a command and ? to list options.
show prints the changes you made in a section, and show full-configuration includes defaults.

Step 1: Create the user and group

Create one account per person. Shared accounts make it impossible to tell who did what, or to revoke one person's access.

config user local
    edit "alice"
        set type password
        set passwd "<STRONG_PASSWORD>"
    next
end

config user group
    edit "SSL-VPN-GROUP"
        set member "alice"
    next
end

To add a user to an existing group later without removing the other members, use append:

config user group
    edit "SSL-VPN-GROUP"
        append member "bob"
    next
end

Two-factor authentication. This guide leaves it off to keep the demo short. In production, turn it on. For example, with a FortiToken (mobile or hardware):

config user local
    edit "alice"
        set two-factor fortitoken
        set fortitoken "<TOKEN_SERIAL>"
        set email-to "<USER_EMAIL>"
    next
end

Check your build's options with set two-factor ?.

Step 2: Create the tunnel IP pool

Clients that connect receive an address from this range. Pick a subnet that doesn't overlap any network the FortiGate already knows about.

config firewall address
    edit "SSL-VPN-RANGE"
        set type iprange
        set start-ip 10.10.10.2
        set end-ip 10.10.10.254
    next
end

Step 3: Create the SSL VPN portal

The portal defines what a connected user gets. Here we want tunnel mode with no split tunneling, so all client traffic goes through the firewall.

config vpn ssl web portal
    edit "SSL-VPN-PORTAL"
        set tunnel-mode enable
        set web-mode disable
        set ip-pools "SSL-VPN-RANGE"
        set split-tunneling disable
        set limit-user-logins enable
    next
end

Option	Value	Why
`tunnel-mode`	`enable`	Gives the client a full VPN tunnel
`web-mode`	`disable`	Removes the browser portal and its extra attack surface. Enable it only if you use bookmarks.
`split-tunneling`	`disable`	All client traffic is sent through the tunnel and your firewall policies
`limit-user-logins`	`enable`	One session per user
`ip-pools`	`SSL-VPN-RANGE`	Where clients get their address

The portal also leaves "save password", "auto-connect" and "keep-alive" off by default. Leave them that way.

Step 4: Configure the SSL VPN settings

config vpn ssl settings
    set status enable
    set port 10443
    set source-interface "wan"
    set source-address "all"
    set servercert "Fortinet_Factory"
    set https-redirect enable
    set tunnel-ip-pools "SSL-VPN-RANGE"
    set idle-timeout 300
    config authentication-rule
        edit 1
            set groups "SSL-VPN-GROUP"
            set portal "SSL-VPN-PORTAL"
        next
    end
end

Option	Value	Notes
`port`	`10443`	Avoid 443, which can conflict with the management interface
`source-interface`	`wan`	The interface that listens for VPN connections
`source-address`	`all`	Fine for a lab. Restrict it in production (see below).
`servercert`	`Fortinet_Factory`	The built-in default. Clients will see a certificate warning. Replace it in production.
`https-redirect`	`enable`	Redirects plain HTTP to the SSL VPN
`idle-timeout`	`300`	Logs out idle users after 300 seconds. `0` means never.
`authentication-rule`	group → portal	Only `SSL-VPN-GROUP` members get `SSL-VPN-PORTAL`

Check the fallback mappings

FortiOS ships with default portal mappings, and users who don't match your rule may still be mapped to a default portal. List them:

show vpn ssl settings

Review the authentication-rule entries and the default-portal value. Remove any mapping you don't need, or point unmatched users at a portal that gives no access if your build has one (show vpn ssl web portal lists what exists).

Restrict who can reach the VPN

Allowing any host to reach a login page on the internet invites scanning and brute-force attempts. Limit the source, either to known addresses:

config firewall address
    edit "VPN-ALLOWED-SOURCES"
        set type iprange
        set start-ip <ALLOWED_START_IP>
        set end-ip <ALLOWED_END_IP>
    next
end

config vpn ssl settings
    set source-address "VPN-ALLOWED-SOURCES"
end

or to specific countries:

config firewall address
    edit "VPN-ALLOWED-COUNTRIES"
        set type geography
        set country "<TWO_LETTER_COUNTRY_CODE>"
    next
end

config vpn ssl settings
    set source-address "VPN-ALLOWED-COUNTRIES"
end

Step 5: Create the firewall policies

You need two policies, both coming in from the tunnel interface ssl.root:

one for traffic to the local network behind the firewall
one for traffic going out through the WAN (internet access for clients, because split tunneling is off)

First, create an address object for the LAN you want to expose, so the first policy doesn't have to use all:

config firewall address
    edit "LAN-SUBNET"
        set type ipmask
        set subnet 10.20.0.0 255.255.255.0
    next
end

Then the policies:

config firewall policy
    edit 0
        set name "SSL-VPN-LAN-ACCESS"
        set srcintf "ssl.root"
        set dstintf "lan"
        set srcaddr "all"
        set dstaddr "LAN-SUBNET"
        set groups "SSL-VPN-GROUP"
        set action accept
        set schedule "always"
        set service "ALL"
        set nat enable
        set logtraffic all
    next
    edit 0
        set name "SSL-VPN-WAN-ACCESS"
        set srcintf "ssl.root"
        set dstintf "wan"
        set srcaddr "all"
        set dstaddr "all"
        set groups "SSL-VPN-GROUP"
        set action accept
        set schedule "always"
        set service "ALL"
        set nat enable
        set logtraffic all
    next
end

Why srcaddr "all" plus a group? In a user-based policy the group does the real filtering. all just means "from any address in the tunnel".

About NAT on the LAN policy: with nat enable, LAN hosts see the firewall's own address instead of the VPN client's. That keeps routing simple. If you disable NAT, your LAN hosts need a return route to the VPN pool.

Don't leave `service "ALL"` in production

ALL services to a whole subnet is convenient for a lab and dangerous if a password leaks. Allow only what each user needs:

config firewall policy
    edit <POLICY_ID>
        set service "HTTPS" "SSH"
        set dstaddr "<SPECIFIC_SERVER>"
    next
end

Create one policy per role (admins, developers, contractors), each with its own group and destinations. This is the principle of least privilege. It matters even more here because the demo has two-factor authentication off.

Check the routing

Tunnel clients need the FortiGate to know how to reach the internet and the LAN. Confirm there is a default route out of wan:

get router info routing-table all

Step 6: Verify the configuration

Before testing from a client, review what you entered:

show vpn ssl settings
show vpn ssl web portal SSL-VPN-PORTAL
show firewall policy

Confirm that the SSL VPN is listening:

diagnose sys tcpsock | grep 10443

Step 7: Connect with a client

FortiClient (Windows, macOS, iOS, Android)

Create an SSL-VPN connection with:

Field	Value
Remote gateway	`<ROUTER_PUBLIC_IP_OR_DDNS_NAME>`
Customize port	`10443`
Username	your own account

You'll be prompted for the password each time, because the portal doesn't allow saving it.

Linux with `openfortivpn`

sudo apt install openfortivpn

The first time, you need to trust the firewall's certificate. Run the command with a wrong or missing --trusted-cert and it will print the certificate's hash:

openfortivpn <VPN_ADDRESS>:10443 -u alice 2>&1 | grep trusted-cert

# Output:
# ERROR:      --trusted-cert <SHA256_FINGERPRINT>

Verify that this hash matches your firewall's certificate before trusting it (for example, by viewing the certificate on the FortiGate). Then connect:

sudo openfortivpn <VPN_ADDRESS>:10443 \
  -u alice \
  --trusted-cert <SHA256_FINGERPRINT>

You'll be prompted for the password. Avoid -p 'PASSWORD' on the command line, since it ends up in your shell history and is visible in the process list. If you use /etc/openfortivpn/config to store settings, keep the password out of it and restrict the file:

sudo chmod 600 /etc/openfortivpn/config

Check the session on the firewall

get vpn ssl monitor

You should see the user, the source address and an address from your pool.

Step 8: Forward the port (if the firewall is behind a router)

If your FortiGate sits behind a router (for example, a home or ISP router) instead of having a public IP directly on its WAN interface, the router has to pass the VPN traffic through. Create a port forwarding rule on the router:

Setting	Value
Protocol	TCP
External port	`10443`
Internal IP	The FortiGate's WAN interface IP
Internal port	`10443`

Then connect using the router's public IP (or a domain name pointing to it) instead of the firewall's internal IP.

Note: port forwarding won't work if your ISP uses CGNAT (you don't have a real public IP). If your public IP changes often, use a dynamic DNS name. FortiGate can update a FortiGuard DDNS name itself, so you don't have to publish an IP address anywhere.

Troubleshooting from the CLI

If the client can't connect, watch what the firewall sees. The first command shows whether traffic arrives at all:

diagnose sniffer packet wan 'tcp port 10443' 4

For authentication and tunnel problems, enable the SSL VPN debug, reproduce the problem, then switch it off:

diagnose debug application sslvpn -1
diagnose debug enable
# ...try to connect...
diagnose debug disable
diagnose debug reset

Symptom	Likely cause	What to check
Timeout or "server unreachable"	Port forward missing, CGNAT, wrong port, stale DDNS	The sniffer shows no packets: check the router and DNS
Certificate warning	Default certificate in use	Expected until you install a trusted certificate
Login rejected	Wrong password, user disabled, user not in the group	`show user local`, `show user group`
Connects but reaches nothing	Policy or route missing	`show firewall policy`, `get router info routing-table all`
Redirect warning	Admin HTTP port conflicts with the redirect	Keep the VPN on `10443` and review the admin HTTP port

Rollback

If something goes wrong, undo the changes in this order. Take a backup first if you made changes since Step 0.

config firewall policy
    delete "SSL-VPN-LAN-ACCESS"
    delete "SSL-VPN-WAN-ACCESS"
end

config vpn ssl settings
    set status disable
end

Or restore the backup you took at the start from the web UI (System → Configuration → Revisions).

Conclusion

You now have a working SSL VPN on your FortiGate 40F, configured and verified from the console. Before using it in production, I recommend:

enabling two-factor authentication for every user
restricting access by source address or country, and by destination subnet and service
using a certificate from a trusted CA instead of the factory default
adding security profiles (antivirus, IPS, web filter) to the policies, since the demo uses none
reviewing the default portal mappings so unmatched users get nothing
planning your move to IPsec, because SSL VPN is gone from the 40F on FortiOS 7.6.3 and later

Questions or suggestions? Leave a comment below!

Making stancl/tenancy tests 3x faster in Laravel

Abderrahim El Ouariachi — Thu, 01 Oct 2026 14:15:29 +0000

If you are using tenancy with a Laravel application, this post is for you.

In this post, I will talk about the method I found to speed up a tenancy test suite by 3x.

Tools: Laravel 13, Pest 5, stancl/tenancy v4

TL;DR

Create one tenant (and its database) per test file instead of one per test, wrap each test in transactions on the central and tenant connections, roll back and disconnect after each test, and drop the tenant and its database in a shutdown function once the run is over.

Why running tenancy tests becomes a nightmare

In an application that uses tenancy, the test suite usually gets very slow very quickly. This happens because each tenant needs its own database, and that database must be migrated with all the tenant tables. This happens automatically, of course, if you are using a package like stancl/tenancy. So when you do:

Tenant::factory()->create();

you are not just creating a tenant row, but also building its database and running its migrations.

How does this happen under the hood?

When you create a tenant, a TenantCreated event is dispatched, and multiple jobs are registered for that event. This is evident in the TenancyServiceProvider.php file, where every event and its respective jobs are listed:

        Events\TenantCreated::class => [
                JobPipeline::make([
                    Jobs\CreateDatabase::class,
                    Jobs\MigrateDatabase::class,
                               ])->send(function (Events\TenantCreated $event) {
                    return $event->tenant;
                })->shouldBeQueued(),
            ],

As you can see, two jobs are dispatched: CreateDatabase and MigrateDatabase. You can infer each one's role from its name: one creates the database and the other migrates it. This is the part that takes time to run. If you create a tenant for each test, you will be creating and migrating a database for every test, so if you have 50 tests, that becomes 50 databases.

Note: the jobs are marked with shouldBeQueued(), but in the test environment the queue runs synchronously (QUEUE_CONNECTION=sync), so the test waits for the database to be created and migrated before it continues.

The result

Measured on 111 tests, using an i5 processor with 8GB RAM.

	Before	After	Speedup	Time saved
Sequential	87s	26s	3.35x	61s (70% less)
Parallel (8 processes)	45s	16s	2.81x	29s (64% less)

That is roughly a 3x speedup, or 70% less time spent running the suite. The rest of this post explains how to get there.

How to prepare the database for each test

An example with Pest would be:

beforeEach(function () {
    $this->tenant = Tenant::factory()->create();

    tenancy()->initialize($this->tenant);
});

afterEach(function () {
    tenancy()->end();

    $this->tenant->delete();
});

test('Test One', function () {});

test('Test Two', function () {});

In this case, two databases will be created. First, we will improve the code a little so we can reuse it across all our tenant tests. For that, we will use a trait, like the following:


namespace Tests;

use App\Models\Tenant;
use Illuminate\Support\Facades\DB;

trait HandleTenancy
{
    public Tenant $tenant;

    public function setUpTenancy(): void
    {
        $this->tenant = Tenant::factory()->create();

        tenancy()->initialize($this->tenant);
    }

    public function tearDownTenancy(): void
    {
        tenancy()->end();

        $this->tenant->delete();

        DB::purge('tenant');
        DB::purge('pgsql');
    }
}


pest()->extend(TestCase::class)
    ->use(HandleTenancy::class)
    ->in('Tenant');

Make sure your tests are separated from your central application tests. In my case, I use a Tenant directory where I put all tests related to tenancy. Also make sure you are not using the RefreshDatabase trait, as it would delete the tenant without deleting its database.

Then you can do the following in your tests:


beforeEach(function () {
    $this->setUpTenancy();

   // Prepare some other model
});

afterEach(function () {
    $this->tearDownTenancy();
});

test('Test One', function () {});

test('Test Two', function () {});

Two databases are still being created, but now we have a unified place to make changes: the HandleTenancy trait.

If you want to improve this further, you can call the methods in the Pest file for each test, like this:

pest()->extend(TestCase::class)
    ->use(HandleTenancy::class)
    ->beforeEach(fn () => $this->setUpTenancy())
    ->afterEach(fn () => $this->tearDownTenancy())
    ->in('Tenant');

With this, you no longer need to call them in each test file.

How to improve the speed

As we said earlier, the problem arises because creating a tenant also creates its database and runs the migrations, which slows us down.

So, what should we do?

Reuse the tenant and its database.

But how?

It's easy, really. The Laravel framework already allows for this through transactions.

So we need to solve the following problems:

Instead of creating a tenant for each test, reuse the first tenant created.
Manage connections, because if we don't, multiple database errors will arise, especially if we are using parallelization.
If we reuse the tenant, we need a way to delete the tenant and its database at the end, once all the tests have completed.

Reusing the tenant

In a normal Laravel tenancy application, we have two connections: the central application connection (in my case, PostgreSQL, pgsql) and another for the tenant connection, named tenant. For each test, the framework creates new connections. If we run the tests sequentially, this is not a problem, but when running them in parallel, multiple connections are created and quickly exhaust the number of simultaneous connections we can make to the database. In my case, with PostgreSQL, the limit is set at 97 for regular users, and three connections are reserved for administrators, which we cannot normally use.

So we need to take this into account when we create the tearDownTenancy method.

At the beginning, our HandleTenancy trait will look like this:


namespace Tests;

use App\Models\Tenant;
use Illuminate\Support\Facades\DB;


trait HandleTenancy
{
    public function setUpTenancy(): void
    {
    }

    public function tearDownTenancy(): void
    {
        DB::connection('tenant')->rollBack();
        DB::connection('tenant')->disconnect();

        tenancy()->end();

        DB::connection('pgsql')->rollBack();
        DB::connection('pgsql')->disconnect();
    }
}

This is how we should manage the teardown of the tenancy. Instead of deleting the tenant, we roll back the database and close the connections after each test, so they don't build up and cause the problems we talked about before.

Next, we will reuse the tenant. We need to create a static variable that stores the tenant's ID so we can reuse it in each test. If $sharedTenantId is not null, that means we are not in the first test and the tenant should not be created. Otherwise, we create the tenant.

Note: a static property declared in a trait belongs to each class that uses the trait, not to the whole PHP process. Pest compiles each test file into its own class, so you get one shared tenant per test file rather than one for the entire suite. That is still a big win. If you want a single tenant per process, keep the static property in a separate class and read it from the trait.


namespace Tests;

use App\Models\Tenant;
use Illuminate\Support\Facades\DB;


trait HandleTenancy
{
    protected static ?string $sharedTenantId = null;


    public function setUpTenancy(): void
    {
        if (static::$sharedTenantId !== null) {
            return;
        }

        $tenant = Tenant::factory()->create();

        static::$sharedTenantId = $tenant->id;
    }

    public function tearDownTenancy(): void
    {
        DB::connection('tenant')->rollBack();
        DB::connection('tenant')->disconnect();

        tenancy()->end();

        DB::connection('pgsql')->rollBack();
        DB::connection('pgsql')->disconnect();
    }
}

Now we should think about how to use transactions with all this logic. We can do it very simply: make sure you create the tenant before beginning the transaction.


namespace Tests;

use App\Models\Tenant;
use Illuminate\Support\Facades\DB;


trait HandleTenancy
{
    protected static ?string $sharedTenantId = null;


    public function setUpTenancy(): void
    {
        if (static::$sharedTenantId === null) {
            $tenant = Tenant::factory()->create();

            static::$sharedTenantId = $tenant->id;
        }

        DB::connection('pgsql')->beginTransaction();

        tenancy()->initialize(
            Tenant::query()->findOrFail(static::$sharedTenantId)
        );

        DB::connection('tenant')->beginTransaction();
    }

    public function tearDownTenancy(): void
    {
        DB::connection('tenant')->rollBack();
        DB::connection('tenant')->disconnect();

        tenancy()->end();

        DB::connection('pgsql')->rollBack();
        DB::connection('pgsql')->disconnect();
    }
}

Now we are using transactions and managing the connections well, but we have another issue to take care of: the tenant and its database are not deleted after each test suite run. We reuse a single database per test file, but that same database is not deleted at the end, which will cause databases to build up after multiple test runs. To resolve this, PHP provides a special function called register_shutdown_function, which allows us to define a function that is called before the PHP process shuts down.

We will call it inside the if clause in the setUpTenancy method. When the function runs, the Laravel container will not be available, so we need to pass all the required values as parameters.

    public function setUpTenancy(): void
    {
        if (static::$sharedTenantId === null) {
            $tenant = Tenant::factory()->create();

            static::$sharedTenantId = $tenant->id;

            register_shutdown_function(
                self::dropTenant(...),
                $tenant->id,
                $tenant->database()->getName(),
                config('database.connections.pgsql'),
            );
        }

        DB::connection('pgsql')->beginTransaction();

        tenancy()->initialize(
            Tenant::query()->findOrFail(static::$sharedTenantId)
        );

        DB::connection('tenant')->beginTransaction();
    }

    private static function dropTenant(string $tenantId, string $databaseName, array $config): void
    {
        try {
            $pdo = new PDO(
                "pgsql:host={$config['host']};port={$config['port']};dbname={$config['database']}",
                $config['username'],
                $config['password'],
            );

            $pdo->exec('DELETE FROM tenants WHERE id = '.$pdo->quote($tenantId));
            $pdo->exec('DROP DATABASE IF EXISTS "'.$databaseName.'"');
        } catch (Throwable $e) {
            fwrite(STDERR, "Tenant cleanup failed: {$e->getMessage()}\n");
        }
    }

Now the database gets deleted after each run.

After refactoring, you should end up with the following piece of code:

<?php

namespace Tests;

use App\Models\Tenant;
use Illuminate\Support\Facades\DB;
use PDO;
use Throwable;

trait HandleTenancy
{
    private const string CENTRAL_CONNECTION = 'pgsql';

    private const string TENANT_CONNECTION = 'tenant';

    protected static ?string $sharedTenantId = null;

    public function setUpTenancy(): void
    {
        $this->ensureSharedTenantExists();

        DB::connection(self::CENTRAL_CONNECTION)->beginTransaction();

        tenancy()->initialize(
            Tenant::query()->findOrFail(static::$sharedTenantId)
        );

        DB::connection(self::TENANT_CONNECTION)->beginTransaction();
    }

    public function tearDownTenancy(): void
    {
        $this->rollBackAndDisconnect(self::TENANT_CONNECTION);

        tenancy()->end();

        $this->rollBackAndDisconnect(self::CENTRAL_CONNECTION);
    }

    private function ensureSharedTenantExists(): void
    {
        if (static::$sharedTenantId !== null) {
            return;
        }

        $tenant = Tenant::factory()->create();

        static::$sharedTenantId = $tenant->id;

        // stancl only needs this connection while creating the database.
        DB::purge(config('tenancy.database.tenant_host_connection_name'));

        // Pass plain values only: the container is already gone at shutdown.
        register_shutdown_function(
            self::dropTenant(...),
            $tenant->id,
            $tenant->database()->getName(),
            config('database.connections.'.self::CENTRAL_CONNECTION),
        );
    }

    private function rollBackAndDisconnect(string $connection): void
    {
        DB::connection($connection)->rollBack();
        DB::connection($connection)->disconnect();
    }

    private static function dropTenant(string $tenantId, string $databaseName, array $config): void
    {
        try {
            $pdo = new PDO(
                "pgsql:host={$config['host']};port={$config['port']};dbname={$config['database']}",
                $config['username'],
                $config['password'],
            );

            $pdo->exec('DELETE FROM tenants WHERE id = '.$pdo->quote($tenantId));
            $pdo->exec('DROP DATABASE IF EXISTS "'.$databaseName.'"');
        } catch (Throwable $e) {
            fwrite(STDERR, "Tenant cleanup failed: {$e->getMessage()}\n");
        }
    }
}

What about parallel runs?

When you run the tests in parallel, each worker is its own PHP process. This means each worker creates its own shared tenant (and database), runs its tests against it, and registers its own shutdown function to clean up. Since we roll back and disconnect after every test, the number of open connections stays low, and workers never share a tenant or step on each other's data.

Caveats

This approach is not a fit for every test, so keep these in mind:

Tests that depend on committed data. Everything runs inside a transaction that is rolled back, so anything that needs data to be actually committed will not work.
Multiple connections and queued jobs. If your code uses a different connection, or a queued job runs on another connection, it will not see the uncommitted data from the transaction.
Tests for tenant creation itself. If you are testing the creation or deletion of a tenant, you still need the old per-test approach, so keep those tests outside of this trait.
Sequences do not roll back in PostgreSQL. Auto-increment IDs will keep growing between tests, so never assert on a specific ID.
The shutdown function is not bulletproof. If the process is killed (kill -9, a CI timeout, and so on), register_shutdown_function will not run, and a database can be left behind from time to time. It is worth cleaning those up occasionally.
DROP DATABASE fails if connections are still open. If you run into this, PostgreSQL 13 and later supports forcing the drop:

$pdo->exec('DROP DATABASE IF EXISTS "'.$databaseName.'" WITH (FORCE)');

DEV Community: Abderrahim El Ouariachi

Keep Tenancy Out of Your Laravel App: Structuring stancl/tenancy v4 as a Module

How a module is usually structured

Now that the structure is ready, we need to register the module.

How to register the Tenancy module

Structuring the tests

Making your tools aware of the module

Laravel Idea

Octane

PHPStan

Rector

Conclusion

How to Set Up an SSL VPN on a FortiGate 40F (Step-by-Step)

What is an SSL VPN?

Why the CLI instead of the web UI?

Prerequisites

Example values used in this guide

Step 0: Open the console and back up

Step 1: Create the user and group

Step 2: Create the tunnel IP pool

Step 3: Create the SSL VPN portal

Step 4: Configure the SSL VPN settings

Check the fallback mappings

Restrict who can reach the VPN

Step 5: Create the firewall policies

Don't leave service "ALL" in production

Check the routing

Step 6: Verify the configuration

Step 7: Connect with a client

FortiClient (Windows, macOS, iOS, Android)

Linux with openfortivpn

Check the session on the firewall

Step 8: Forward the port (if the firewall is behind a router)

Troubleshooting from the CLI

Rollback

Conclusion

Making stancl/tenancy tests 3x faster in Laravel

TL;DR

Why running tenancy tests becomes a nightmare

The result

How to prepare the database for each test

How to improve the speed

Reusing the tenant

What about parallel runs?

Caveats

Don't leave `service "ALL"` in production

Linux with `openfortivpn`