Forem: Mohamed Said

Asynchronous PHP — Multiprocessing, Multithreading & Coroutines

Mohamed Said — Thu, 01 Apr 2021 11:08:36 +0000

Let's take a look at this typical PHP code:

function names()
{
    $data = Http::get('data.location/products')->json();

    $names = [];

    foreach ($data as $item){
        $names[] = $item['name'];
    }

    return $names;
}

We send an HTTP request that returns an array of items, then we store the name of each item in a $names array.

Executing this function will take time that's equal to the duration of the request plus the time it took to build the array. What if we want to run this function multiple times for different data sources:

$products = names('/products');
$users = names('/users');

Running this code takes time that's equal to the duration of both functions combined:

HTTP request to collect products: 1.5 seconds
Building products names array:    0.01 seconds
HTTP request to collect users:    3.0 seconds
Building users names array:       0.01 seconds
Total:                            4.52 seconds

This is called Synchronous code execution, or executing one thing at a time. To make this code run faster, you may want to execute it asynchronously. So what are our options if we want to achieve that?

Execute in different processes.
Execute in different threads.
Execute in coroutines/fibers/green-threads.

Execute in different processes

Running each of these function calls in a separate process gives the operation System the task of running them in parallel. If you have a multi-core processor, we all have now, and there are 2 idle cores sitting around, the OS will use both cores to execute the processes in parallel (at the same time). However, in most cases there are other processes running on the machine that need to use the available cores. In that case, the OS will share the CPU time between those processes. In other words, the available cores will switch between processing our two processes and other processes. In that case, our processes will be executed concurrently.

The execution time for those two processes will be something like 3.03 seconds (not 100% accurate I know). This conclusion is based on the fact that the slowest request takes 3 seconds, the 2 network calls took 10 milliseconds, and both loops for collecting names each takes 10 milliseconds.

The execution inside the core will look like this:

Switch to process 1
Start HTTP request to collect products
Switch to process 2
Start HTTP request to collect users
Switch to process 1
If a response came, then build products names array
Switch to process 2
If a response came, then build users names array

So while the CPU waits for a response on the first request, it sends the second request. Then waits until any of the requests return before it continues the process.

Multiprocessing is an easy way to achieve asynchronous code execution in PHP. However, it's not the most performant. Because creating processes is relatively expensive and each process requires its own private space in memory. Switching between processes (context switching) also has an overhead.

You could use Laravel queues and start a fixed number of workers (processes) and keep them alive to process your tasks. That way you won't have to create new processes each time you want to run something async. However, the overhead of context switching and memory allocation will still apply. Also with workers, you need to manage how you can receive the results from your code execution inside the workers.

Multiprocessing and Laravel workers have been doing great for millions of apps. So when I say that it's not the most performant I'm speaking relative to the other options. Don't just read this and think that multiprocessing and queues are bad. Ok?

Execute in different threads

A process has its own private space in memory, a process may have multiple threads. All threads live in the same memory space as the process. That makes spawning threads less expensive than spawning processes.

However, context switching still happens. When you have too many threads, as the case with too many processes, everything on your machine will slow down. Because the CPU cores are switching between a lot of contexts.

Also, with the same memory space being accessed by multiple threads at the same time, race conditions may happen.

In addition to all this, multithreading in PHP is not supported anymore.

Execute in coroutines/fibers/green-threads

This "thing" has many names. But let's call it "coroutines" because it's the most used term.

A coroutine is like a thread in that it shares the memory of the process it was created inside, but it's not an actual thread because the OS knows nothing about it. There's no context switching between coroutines on the OS level. The runtime controls when the switching happens, which is less expensive than the OS context switching.

Let's convert our code to using coroutines. This code is for demonstration only, it won't work if you run it:

$products = [];
$users = [];

go(fn() => $products = names('/products'));

go(fn() => $users = names('/users'));

The idea behind coroutines is that the runtime is going to schedule running those callbacks concurrently. Inside each coroutine, the code may explicitly yield control to the runtime so it can run another coroutine. At any given time, only one coroutine is being executed.

So if we break down our code, it comes to this:

go(function(){
    $data = Http::get('data.location/products')->json();
    // yields

    foreach(...)
});

go(function(){
    $data = Http::get('data.location/users')->json();
    // yields

    foreach(...)
});

The runtime will execute the first coroutine until it yields, then execute the second coroutine until it yields, and then go back to where it stopped in the first coroutine. Until all coroutines are executed. And then, it'll continue code execution in the regular synchronous fashion.

Now you may have two question; first, when should the yielding happen? second, how do we make it happen?

Inside each coroutine in our example there are two operations; one I/O bound and one CPU bound. Sending the HTTP request is an I\O bound operation, we're sending a request (input) and waiting for a response (output). The loop, on the other hand, is a CPU bound operation, we are looping over a set of records and calculating results. Calculations are done by the CPU, that's why it's called CPU bound.

CPU bound work will take the same amount of time if it runs in the same process. The only way to make the work take less time is if you execute it in different processes or threads. On the other hand, I\O bound work can run concurrently inside the same process; while one I\O operation is waiting for output, another operation can start.

Looking at our example, the execution inside the runtime will look like this:

Start coroutine 1
Start HTTP request to collect products
Coroutine 1 yields
Switch to coroutine 2
Start HTTP request to collect users
Coroutine 2 yields
Switch to coroutine 1
If a response came, then build products names array
Switch to coroutine 2
If a response came, then build users names array

Using coroutines, we can take the time an I\O operation spends waiting and use it to do other work. By doing so, we are running all the coroutines concurrently.

Now let's move to our second question: how do we make the yielding happen? We don't.

Different frameworks and libraries must support asynchronous execution by yielding control whenever an I\O operation is waiting. There's a popular term for this that you should know "Non-blocking I\O". Libraries that communicate with databases, caches, filesystem, networking, etc... must be adapted to become non-blocking.

If you use a blocking library inside a coroutine, it'll never yield and thus your coroutines will be executed synchronously. The main process will wait until the I\O operations receive the output before continuing with the rest of the program.

Conclusion

There's a lot more to say about coroutines and asynchronous execution. My plan is to explore ways we can make Laravel play nicely with coroutines and share my findings in the process.

Until then, embrace the synchronous code execution of PHP. It worked very well for over 25 years. Send I\O bound work that you need to cut to a queue worker and act on the results later. This should cover many of the use cases.

Features and Changes Coming to Laravel 8's Queue System

Mohamed Said — Fri, 04 Sep 2020 07:02:24 +0000

Laravel 8 ships with cool new features as well as some changes to the queue system. In this post we'll look into these features and changes.

Changes

Backoff

The retryAfter() method and the retryAfter property of queued jobs, mailers, notifications, and listeners has been renamed to backoff.

The --delay option of the php artisan queue:work command has been renamed to --backoff as well.

You should also know that you can now pass an array to the backoff property to instruct the worker to implement an exponential backoff:

public $backoff = [30, 60];

Or return an array from the backoff() method:

public function backoff ()
{
    return [30, 60]; 
}

Using an exponential backoff here, we instructed the worker to delay retrying the job 30 seconds after the first failure, then 60 seconds for each failure after that.

You can also use an exponential backoff on the queue:work command:

php artisan queue:Work --backoff=30,60

Job Expiration

The timeoutAt property of queued jobs, notifications, and listeners has been renamed to retryUntil.

Using $retryUntil instructs the worker to keep retrying the job until a certain time in the future.

You can add retryUntil as a public property on the job class or a retryUntil method:

public function retryUntil()
{
    return now()->addDay();
}

New Features

Queued Closures

You can now chain a catch() method while dispatching a queued closure:

dispatch(function () {
    // Job logic...
})->catch(function (Throwable $e) {
    // Handle Failure...
});

The closure provided to the catch() method will be invoked if the job fails.

Database Driver Reliability

When releasing a job back to the queue while using the database queue driver, Laravel will perform the operation inside a transaction now. That means the job will not be deleted from the queue unless the new—released—instance is added. This decreases the chance of losing jobs significantly.

Redis Driver Efficiency

When dispatching a group of jobs in bulk while using the redis queue driver, Laravel will perform the operation by sending a single command to redis. Previously, Laravel used to send multiple rpush command to redis; one for each job.

Worker Graceful Termination

Starting Laravel 8, workers will exit gracefully and call any terminating callbacks registered by App::terminating().

Worker Self Termination

In order to avoid memory leaks, it's a common practice to terminate your workers every now and then and let your process monitoring tool start new ones. This was usually done by adding a CRON job that runs the queue:restart artisan command.

In Laravel 8, you can instruct workers to exit after processing a certain number of jobs or after running for a specific number of seconds:

php artisan queue:work --max-jobs=1000 --max-time=3600

Naming Workers

You can now add a --name option to the queue:work command:

php artisan queue:work --name=notifications

This feature was mainly added to allow people to customize how the worker picks which queue to process jobs from at runtime:

Worker::popUsing('notifications', function ($pop) {
    $queues = time()->atNight() 
        ? ['mail', 'webhooks'] 
        : ['push-notifications', 'sms', 'mail', 'webhooks'];

    foreach ($queues as $queue) {
        if (! is_null($job = $pop($queue))) {
            return $job;
        }
    }
});

Job Batching

Laravel's job batching allows you to dispatch a number of jobs to be processed in parallel by your workers. You can perform an action after all jobs in the batch are processed or if any of the batch jobs fail:

Bus::batch([
    new ProcessFile(1),
    new ProcessFile(2),
    new ProcessFile(3),
])->dispatch();

You can find more information on Job Batching in the official documentation.

Job Chaining

You can now dispatch a chain of jobs using the Bus facade:

Bus::chain([
    new ExtractReports,
    new GenerateReport,
    new SendResults,
])->dispatch();

You can also add a catch() callback that'll be invoked if any of the jobs in the chain fails:

Bus::chain([
    new ExtractReports,
    new GenerateReport,
    new SendResults,
])->catch(function(){
    // Handle the chain failure.
})
->dispatch();

Horizon Balancing Rate

Two new configuration options were added to Horizon; balanceMaxShift and balanceCooldown.

 'environments' => [
    'environment' => [
        'supervisor-1' => [
            'balanceMaxShift' => 5,
        ],
    ],
],

balanceMaxShift sets the maximum number of worker processes to add or remove each time Horizon scales the workers pool. In previous versions on Horizon, only a single worker was added or removed, now you can control that number.

As for balanceCooldown, it sets the number of seconds to wait between each scaling action. This was hard-coded to 3 seconds in previous versions of Horizon.

 'environments' => [
    'environment' => [
        'supervisor-1' => [
            'balanceCooldown' => 1,
        ],
    ],
],

The Backend-for-frontend Pattern For Monoliths

Mohamed Said — Sun, 24 May 2020 15:44:13 +0000

The majestic monolith is how I build backends since I started. Microservices seemed like too much work for the small teams I worked with. However, some of the patterns used to build and service applications running in a microservice architecture can be useful for monoliths.

One of these patterns is the backend-for-frontend pattern. The idea is to have a dedicated backend for your frontends. It can be a separate backend for each type of frontend or one backend for all frontends.

To understand how this pattern can be useful, let's imagine we're building an online store. We have our backend exposing a public REST API, this API can be consumed by our web UI, mobile apps, and other 3rd party consumers. Authentication to our backend is done using OAuth2.0, all consumers must send a bearer token to protected routes.

Authentication

Storing the authentication token in the mobile app is fine, but there's no way to store the tokens in the browser securely. Using a dedicated backend for our web frontend, we can use that BFF (Backend For Frontend) as a gateway to the actual backend and store the token in it.

So to log the user in to our web frontend, the frontend will make a request to the BFF which will send a login request to the backend, receive the token, and then store it in the session.

Communication between the web frontend and the BFF is authenticated using sessions, while the BFF communicates with the backend using token-based authentication.

Authorization

Roles and permissions for an app that's used to make orders and browser products are different from ones for an app that's used to manage inventory and suppliers.

Using a BFF for each type of client, we can run the authorization checks in the BFF and keep our backend as much open as we want it to be. Allowing us to build more clients in the future without having to change the backend.

Aggregation

To render a screen that displays all products, featured products, and recommended products. A client may need to make 3 requests to 3 different backend endpoints. Even if these requests are made concurrently, the client still has to send 3 requests and wait for the responses.

Using a BFF, the client can make a single request to a /products-list endpoint on the BFF and the BFF will aggregate the response needed by making the 3 requests to the backend.

Server-to-server communication will experience less latency and we can add a caching layer in the BFF which will make things even better.

BFF and Laravel

In the following video, I discuss the BFF pattern and explain how we can implement it using Laravel.

Multi-tenancy in Laravel: Migrations, Testing, and switching tenants

Mohamed Said — Wed, 29 Apr 2020 09:13:39 +0000

In this video, we discuss how we can achieve multitenancy in Laravel using the database-per-tenant approach. We cover:

Managing multiple DB connections
Migrating & seeding tenants & admin databases
Running tests against tenant & admin databases
Connecting to the correct tenant on requests/jobs

Laravel Sanctum - Hitting all the rough edges

Mohamed Said — Sat, 11 Apr 2020 05:59:46 +0000

In this video I'm going to use Laravel Sanctum to authenticate requests to an API using session-based and token-based authentication. While doing so, I'm going to show you all the possible errors that you might get and how to fix them.

When does PHP call __destruct()?

Mohamed Said — Wed, 19 Feb 2020 06:05:20 +0000

In PHP, __construct() is called while creating an object and __destruct() is called while the object is being removed from memory. Using this knowledge, we can create more fluent APIs as demonstrated by Freek Van der Herten in this short video.

Now let's see when PHP calls __destruct() exactly.

An object is removed from memory if you explicitly remove it:

$object = new Object();

unset($object); // __destruct will be called immediately.

$object = null; // __destruct will be called immediately.

It's also called when the scope where the object live is about to be terminated, for example at the end of a controller method:

function store(Request $request)
{
   $object = new Object();

   User::create(...);

   // __destruct will be called here.

   return view('welcome');
}

Even if we're within a long running process, queued job for example, __destruct will be called before the end of the handle method:

function handle()
{
   $object = new Object();

   User::create(...);

   // __destruct will be called here.
}

It'll also be called when the script is being terminated:

function handle()
{
   $object = new Object();

   User::create(...);

   // __destruct will be called here.

   exit(1);
}

Running a task after the response is sent

Mohamed Said — Fri, 07 Feb 2020 11:53:51 +0000

Normally, if you want to run a task and don't want the user to wait until it's done you'd dispatch a queued job. However, sometimes that task is really simple and short that putting it in a queue might be an overkill.

Using Laravel, you can run such tasks after sending the response to the user. It works by keeping the PHP process alive to run the tasks after closing the connection with the browser. You can do that using:

Terminable Middleware.
Terminating callbacks (e.g. App::terminating(function(){ }))
Job::dispatchAfterResponse() using Laravel v6.14.0 or higher.

If you have a job called ClearCache, you can run it after the response is sent like this:

function store(Response $response)
{
 // Do some work

 ClearCache::dispatchAfterResponse();  

 return view('success');
}

Remember, this is only a good idea if the task is really short. For long running tasks, dispatching to queue is recommended.

Where to look when you see "Job has been attempted too many times or run too long"

Mohamed Said — Fri, 31 Jan 2020 16:55:53 +0000

If you've seen this MaxAttemptsExceededException in your error logs or failed_jobs table and you don't have a clue what happened to the job, let me try to explain what may have happened. It's either:

The job timed out and it can't be attempted again.
The job was released back to the queue and it can't be attempted again.

If your job processing time exceeded the timeout configuration, the worker will check the maximum attempts allowed and the expiration date for the job and decide if it can be attempted again. If that's not possible, the worker will just mark the job as failed and throw that MaxAttemptsExceededException.

Also if the job was released back to the queue and a worker picks it up, it'll first check if the maximum attempts allowed was exceeded or the job has expired and throw MaxAttemptsExceededException in that case.

A production-ready database queue diver for Laravel

Mohamed Said — Thu, 30 Jan 2020 12:26:46 +0000

The database queue driver was not recommended to run in production environments due to the problem of deadlocks with Relational database. Let's see how a deadlock happens:

A worker puts a lock on a job to process it.

Another worker finds the same job locked and it waits for the lock to be released.
The first worker is done with the job and wants to delete it, so it requests another lock.
Now we have a deadlock, multiple transactions waiting for each other to release the same locks.

MySQL 8.0.1 and Postgres 9.5 allows skipping a locked record and ignore it. This allowed us to prevents workers from fighting over the same job and thus cause a deadlock.

Starting the next Laravel release, you can use the queue database driver even if your environment is under heavy load. I've tested the changes processing 516,783 jobs by 50 workers and it resulted no deadlocks.

The database driver is easy to setup since you don't need to worry about configuring and maintaining another tool "redis", it also opens the door for complex custom rules like funneling jobs per tenant or ensuring groups of jobs run in a certain order. In addition to this, you can easily configure database backups to ensure you don't lose the jobs in store in case the server crashed.

However, you should know that the database queue driver is not the best driver performance-wise, but it's still pretty efficient as the test results shared above implicate.

If you run MySQL >=8.0.1 or Postgres >=9.5, you don't need to change anything in your app. Just configure the database connection, run php artisan queue:table and php artisan migrate, and set the QUEUE_CONNECTION to database in your .env file.

APP_KEY is a secret. Here's what it's used for & how you can rotate it

Mohamed Said — Sun, 26 Jan 2020 16:42:25 +0000

People often think APP_KEY is used to hash passwords, it isn't. Here's what this key is used for:

Encrypting cookies.
Creating the signature for signed URLs and queued closures.
Encrypting values using the encrypt() and decrypt() helpers.

You should deal with the APP_KEY as a secret. If you think it has been exposed, you MUST change it. However, make sure you re-encrypt any stored encrypted values. Also understand that there'll be some side effects:

All previously queued closures won't be able to run.
All users will be logged out and all token values will be lost.
All previously created signed routes won't work.

You can override the encrypter in your app to use an old key if it failed to decrypt a value with the new key. That way you can keep your app running fully after rotation until all the values are re-encrypted.

<?php

namespace App\Providers;

use App\Encrypter;
use Illuminate\Support\Str;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    /**
     * Register any application services.
     *
     * @return void
     */
    public function register()
    {
        $this->app->singleton('encrypter', function($app){
            $config = $app->make('config')->get('app');

            if (Str::startsWith($key = $config['key'], 'base64:')) {
                $key = base64_decode(substr($key, 7));
            }

            return new Encrypter($key, $config['cipher']);
        });
    }
}

<?php

namespace App;

use Illuminate\Support\Str;

class Encrypter extends \Illuminate\Encryption\Encrypter
{
    /**
     * Decrypt the given value.
     *
     * @param  string  $payload
     * @param  bool  $unserialize
     * @return mixed
     *
     * @throws \Illuminate\Contracts\Encryption\DecryptException
     */
    public function decrypt($payload, $unserialize = true)
    {
        try{
            return parent::decrypt($payload, $unserialize);
        }catch(\Throwable $e){
            $currentKey = $this->key;

            $this->key = Str::startsWith(config('app.old_key'), 'base64:')
                            ? base64_decode(substr(config('app.old_key'), 7))
                            : config('app.old_key');

            return tap(parent::decrypt($payload, $unserialize), function () use ($currentKey) {
                $this->key = $currentKey;
            });
        }
    }
}

What is AWS Lambda, and how Laravel Vapor uses it

Mohamed Said — Thu, 23 Jan 2020 07:48:36 +0000

Vapor is a serverless deployment platform for Laravel powered by AWS Lambda. A lot is happening under the hood, some real magic, but the most interesting part of the whole thing is the serverless technology underneath. Let's dive into serverless as I'll try to explain what happens when you run your laravel application serverless.

If you take a look at the index.php file of your laravel app, you'll see this:

$response = $kernel->handle(
  $request = Illuminate\Http\Request::capture()
);

$response->send();

When you send a request to your application, the Kernel::handle method will process that request and send the response back to your browser.

You normally host this application on a server that waits for any incoming requests and calls index.php whenever one comes. Let's say you host it in a small DigitalOcean droplet and paying $5/month for the server.

Imagine if you can just upload that Kernel::handle method to a service, and you only pay when that method runs. You don't worry about provisioning a server, upgrading the different libraries, managing the storage, and all this work. Just upload the function and you only pay when the function runs.

That's basically what running serverless is all about.

Lambda is AWS's FaaS (Function as a service), Laravel Vapor uses it to run your Laravel applications as a function that's only invoked when needed. Upload your app to Vapor, and that's it. Never worry about servers again.

Lambda is mainly used as part of a Microservices architecture, a lambda is meant to be doing only one job:

You upload an image to S3, a lambda gets invoked & generates a thumbnail version of your image.
You send a job to queue, a lambda is invoked & processes that job.
You schedule a job and AWS invokes a lambda each time the alarm goes off.
You send an HTTP request to an endpoint, and a lambda is invoked and generates a response.
You could also invoke a lambda as per your request anytime.

This usually means you have to divide your application code into multiple different services where each service has its own code base, and you deploy these different functions to AWS and instruct it as to when to run which lambda.

A user submits an order, you instruct AWS to run the "new-order" lambda. A user asks for an invoice, you instruct AWS to run the "generate-invoice" lambda. A user asks for a list of products, you instruct AWS to run the "products-list" lambda.

While the Microservices architecture is very beneficial in many cases, it adds a lot of complexity to your project as you need to handle the "wiring" of all these services working together. Laravel Vapor takes your codebase and converts it to a single function; depends on the event that triggers this function, Vapor runs a certain part of your application. This way all the wiring is done by Laravel under the hood.

So for example; when the user visits the /api/products endpoint, Vapor will dispatch the HTTP request to the Laravel router and sends the response back. Or when a job is available on SQS, Vapor will marshal that job to a worker to process it.

That way you can have all the benefits of running serverless without having to change the way you write your Laravel applications. Vapor takes care of all the work needed to convert your Laravel app to work serverless.

How it works

As we said earlier, Vapor converts your application to a single lambda. However, to allow you to set different configuration values for your HTTP and CLI environments, Vapor creates 2 identical Lambdas on AWS.

The HTTP lambda is responsible for serving HTTP requests; you can configure the amount of memory AWS should allocate to your HTTP requests, the timeout value, and the concurrency limit.

The CLI lambda is responsible for running artisan commands, processing queued jobs, and running scheduled jobs. You can also configure memory, timeout, and concurrency limits.

For the HTTP lambda, it's invoked via the API Gateway or an Application Load Balancer. We'll talk about the difference between both services in another post.

For queued jobs, Vapor configures your laravel application to use SQS to dispatch and process jobs. The CLI lambda will be invoked whenever a job is available in SQS.

Scheduled jobs are configured using CloudWatch/EventBridge, Vapor creates a rule that runs every minute and invokes your CLI lambda with the php artisan schedule:run command.

Finally, when you run vapor:command and provide the artisan command you wish to run, Vapor invokes the CLI lambda and instructs it to run the provided command.

Working with a database-per-tenant model in Laravel

Mohamed Said — Wed, 22 Jan 2020 09:09:27 +0000

In this article, we're going to explore one of the most confusing aspects of multi-tenancy in laravel applications; communicating with multiple databases.

The majority of applications just communicate with a single database. However, a considerable portion of laravel applications communicates with multiple databases. There are some neat packages that help with managing multiple connections, but it'd be useful if we understand how database connections work in Laravel, so let's dive in.

Establishing a connection with the Database

When you run a query in Laravel, the Illuminate\Database\DatabaseManager takes care of configuring a database connection to run the query on. Each connection has a unique name and you get to choose a default connection to be used when no connection name is explicitly provided:

// Uses the default connection.
DB::table('users')->all();

// Uses the "tenant" connection.
DB::connection('tenant')->table('users')->all();

The connection is created once and then re-used every time you need to run a query during the application life cycle.

The PHP Data Objects (PDO)

The PDO is a standard interface for accessing databases in PHP, Laravel uses the PDO to run all kinds of queries. However, you can configure a connection to use a separate read & write PDO objects for read/write operations. You can find more details on that subject in the official docs.

Most multi-tenancy apps that use a separate database for each tenant has a central database where details on all tenants are stored. So basically in a single application you might have a system connection and a tenant connection.

'tenant' => [
  'driver' => 'mysql',
  'host' => env('DB_HOST', '127.0.0.1'),
  'port' => env('DB_PORT', '3306'),
  // ...
],

'system' => [
  'driver' => 'mysql',
  'host' => env('DB_HOST', '127.0.0.1'),
  'port' => env('DB_PORT', '3306'),
  // ...
],

The system connection always connects to the same database, so the configuration set in the config file can always be used, and queries to this connection are pretty easy to do:

DB::connection('system')->table('tenants')->all();

It gets interesting though for when you want to run a query on the tenant connection. Since the tenant connection configurations are based on who is the current tenant, we can't put the configuration in the config/database.php file, instead we want to configure the connection on the fly.

config(['database.connections.tenant.database' => 'tenant1']);

This line of code will set the tenant connection configuration to read from the "tenant1" database, you can change any connection parameters in the same manner; like the username, password, read/write connections, anything.

Now when the DatabaseManager tries to build the tenant connection, it will use the configurations you set on the fly in the step above. However, if the tenant connection was already resolved before any changes to the config file won't take effect since the connection is cached first time it's created and Laravel won't create a new instance of the connection.

To overcome this, you need to make sure no connection is resolved before you can set the new configuration:

config(['database.connections.tenant.database' => 'tenant1']);

DB::purge('tenant');

DB::reconnect('tenant');

Using purge() and reconnect() will ensure any query that runs in the future on the tenant connection will use the configuration from above.

Where to put this piece of code
There are several entry points to a laravel application:

HTTP Requests.
Console Commands.
Queued Jobs.

Let's create a new TenancyProvider and add it to our config/app.php file. In the register method of this provider we can configure the current tenant like this:

public function register(){
    if($this->app->runningInConsole()){
        return;
    }

    if($request->getHttpHost() == 'tenant1.app.com'){
      config(['database.connections.tenant.database' => 'tenant1']);

      DB::purge('tenant');

      DB::reconnect('tenant');
     }
}

We check the HTTP host of the current request and then assign the configuration to respect the current tenant.

As for queued jobs, we can store the tenant_id in the payload of all jobs, and while precessing the job we set the current tenant configuration same as above.

So in our service provider, we add this line:

$this->app['queue']->createPayloadUsing(function () {
      return Tenant::get() ? [
              'tenant_id' => Tenant::get()->id
             ] : [];
});

To simplify things I use Tenant::get() that should be holding the logic that identifies who is the current tenant.

Now the payload of each job will include a tenant_id if a tenant is discovered, now we can listen to the JobProcessing event and configure our database for the current tenant if one exists:

$this->app['events']->listen(\Illuminate\Queue\Events\JobProcessing::class, function($event){
    if (isset($event->job->payload()['tenant_id'])) {
        Tenant::set($event->job->payload()['tenant_id']);
    }
});

As for Console Commands; you will need to specify who is the tenant to run the code against. So each time you run a command you need to send details about which tenant to be used, and inside the command code you configure the tenant database connection as seen above.