DEV Community: Oussama Mater

Boosting Laravel Boost

Oussama Mater — Sun, 24 Aug 2025 08:21:53 +0000

Hello 👋

It's been a while since I wrote an article. I mean, why would I? You prompt AI about a subject, and it spits out everything you need. That kinda killed the joy for me, I ended up drafting like 10 articles but never publishing any of them. Still, part of me believes people enjoy reading something human-made. Like, an AI wouldn't make you sit through this boring intro, but hey, it's human, crappy, but human. Thanks by the way.

Anyway, I'm writing about AI today (the irony ha). Laravel just dropped a new package, Laravel Boost, which basically makes AI suck less. It makes it more deterministic by giving it rules and extra context to follow. Because yeah, the main bottlenecks of LLMs (at least from my day-to-day usage) are the prompt and the context.

WTF are MCPs

I'm not going to lecture you about prompt engineering, there are tons of resources out there already. Instead, let's talk about the second bottleneck: context.

LLMs are trained on massive datasets, and those datasets are their reference point. For example, if the training data only goes up to 2023 and you ask about today's weather, it won't have a clue. So what do we do?

We empower LLMs, give them up-to-date context, through tools. You have probably used this without even realizing it. Ask an LLM about the latest news and you will see "searching web". That's a tool in action, feeding the AI fresh data so it can answer you. Neat.

But "searching web" is just a built-in tool. If you asked it about your latest Jira ticket, it wouldn't know. And think about it, providers like OpenAI or Anthropic can't build tools for every possible need. For instance, you might want your LLM to query internal company data. That's where the idea of bringing your own tool comes in. The LLM can call your tool, fetch the data it needs, and then respond. Again, pretty neat.

So neat that Anthropic introduced the Model Context Protocol (MCP) to document this. It standardizes how LLMs call tools, how you plug tools into them, and how they fetch more context. So, if you have never heard of MCPs, well, we just covered them. At the core, they are just a thin layer that lets LLMs use tools (like the "searching web" tool) to grab more context.

MCPs do a bit more too.

And these tools can be anything, API calls, system calls, method calls, whatever. As long as they can provide an answer back to the LLM, the model can use it to finish the task.

Cool. Now you know about MCPs. You can read more about them here.

Hmm, Laravel Boost?

So Laravel Boost is basically an MCP server that exposes a set of tools. These tools revolve around the Laravel ecosystem, things like reading routes, checking logs, or searching the Laravel docs.

So when you prompt an LLM to fix your vibe coded SaaS, it can decide which tool to use. Though, nothing's guaranteed, an LLM can be a bitch and just ignore the tools, making up a method that never existed 🤷🏽.

And then you undo the change, get pissed, prompt again, and deal with a "sorry, you are absolutely right"...

I'm not going to cover how to install it, there's already an official YouTube video, a Laracasts episode, and a bunch of community guides. Besides, I'm a bit late to the party.

Though, I do want to show you how to boost Laravel boost.

What's My Purpose?

Boost lets you give your application a "purpose", basically a description of your product so the AI knows the context. Say you are building a SaaS, you could write something like:

This application is a SaaS that provides X services, etc.

You know your product best buddy.

First, make sure you have published the Boost config:

php artisan vendor:publish --tag=boost-config

At the time of writing, the config file looks like this:

<?php

declare(strict_types=1);

return [
    /*
    |--------------------------------------------------------------------------
    | Boost Master Switch
    |--------------------------------------------------------------------------
    |
    | This option may be used to disable all Boost functionality, which
    | simply provides a single and convenient way to enable or disable
    | Boost's AI development tools.
    |
    */

    'enabled' => env('BOOST_ENABLED', true),

    /*
    |--------------------------------------------------------------------------
    | Boost Browser Logs Watcher
    |--------------------------------------------------------------------------
    |
    | The following option may be used to enable or disable the browser logs
    | watcher feature within Laravel Boost. The log watcher will read any
    | errors within the browser's console to give Boost better context.
    */

    'browser_logs_watcher' => env('BOOST_BROWSER_LOGS_WATCHER', true),

];

To add the application purpose we just talked about, drop a new entry in the config:

// omitted for breivety
'purpose' => 'Describe your application purpose'

For this to take effect, you will need to re-generate the guidelines:

php artisan boost:install

In the published guidelines, for example, if you are using Cursor, you will find your purpose (I hope we all do lol) in .cursor/rules/laravel-boost.mdc, in the "Foundational Context" section.

Less is More

Boost ships with 15+ tools, but depending on your app you might not need them all. If you are building a pure API, you don't need a BrowserLogs tool, you are spared from frontend hell. Personally, I also found GetConfig and ListAvailableConfigKeys kinda useless, the LLM can just read configs directly without jumping through those hoops. So let's exclude them.

Tweak the boost.php config:

<?php

use Laravel\Boost\Mcp\Tools\GetConfig;
use Laravel\Boost\Mcp\Tools\BrowserLogs;
use Laravel\Boost\Mcp\Tools\ListAvailableConfigKeys;

// omitted for breivety
'mcp' => [
    'tools' => [
        'exclude' => [BrowserLogs::class, GetConfig::class, ListAvailableConfigKeys::class],
    ],
],

Boom, 3 tools gone.

And just like excluding tools, you can add your own. For example, I like having a tool that lists all registered events in the app. If you are pulling in third-party packages, this makes it easier for the LLM to spot events it can hook into instead of building extra logic or extending classes.

Under the hood, Boost uses a new first-party package, laravel/mcp, which handles tool creation and all the fun stuff. You can create a new tool with:

php artisan make:mcp-tool ListEvents

The tool code for listing event is something like:

<?php

namespace App\Mcp\Tools;

use Illuminate\Support\Facades\Artisan;
use Laravel\Mcp\Server\Tool;
use Laravel\Mcp\Server\Tools\Annotations\IsReadOnly;
use Laravel\Mcp\Server\Tools\ToolInputSchema;
use Laravel\Mcp\Server\Tools\ToolResult;
use Symfony\Component\Console\Command\Command as CommandAlias;
use Symfony\Component\Console\Output\BufferedOutput;

#[IsReadOnly]
class ListEvents extends Tool
{
    public function description(): string
    {
        return 'List all available events defined in the application';
    }

    public function schema(ToolInputSchema $schema): ToolInputSchema
    {
        return $schema;
    }

    /**
     * @param array<string> $arguments
     */
    public function handle(array $arguments): ToolResult
    {
        $eventsOutput = $this->artisan('event:list');

        return ToolResult::text($eventsOutput);
    }

    /**
     * @param array<string|bool> $options
     */
    private function artisan(string $command, array $options = []): string
    {
        $output = new BufferedOutput;
        $result = Artisan::call($command, $options, $output);

        if ($result !== CommandAlias::SUCCESS) {
            return 'Failed to list routes: '.$output->fetch();
        }

        return trim($output->fetch());
    }
}

Then register it in, you guessed it, the config file:

<?php

use App\Mcp\Tools\ListEvents;
use Laravel\Boost\Mcp\Tools\GetConfig;
use Laravel\Boost\Mcp\Tools\BrowserLogs;
use Laravel\Boost\Mcp\Tools\ListAvailableConfigKeys;

// omitted for breivty
'mcp' => [
    'tools' => [
        'exclude' => [BrowserLogs::class, GetConfig::class, ListAvailableConfigKeys::class],
        'include' => [ListEvents::class], // include the tool
    ],
],

And just like that, you added a custom tool.

Bonus tip: The MCP server Boost uses comes with an inspector, so you can test new tools right away. Just run:

php artisan mcp:inspector laravel-boost

You will see all available tools, test them, etc.

Don't call me, Don't come by my house

If you are using a modular monolith architecture with a modules/ directory... bad news: Boost only checks enums, models, and controllers inside app/.

Would be nice if there was a native way to customize this, but until then, we do it ourselves.

All you need to do is rebind Laravel\Boost\Install\GuidelineAssist to your own custom GuidelineAssist, which scans modules/ (or wherever).

Your custom guideline might look like:

<?php

declare(strict_types=1);

namespace App\Support;

use Illuminate\Database\Eloquent\Model;
use Laravel\Boost\Install\GuidelineAssist;
use ReflectionClass;
use Symfony\Component\Finder\Finder;

class CustomGuidelineAssist extends GuidelineAssist
{
    public function __construct()
    {
        $this->modelPaths = $this->discover(fn ($reflection) => ($reflection->isSubclassOf(Model::class) && ! $reflection->isAbstract()));
        $this->controllerPaths = $this->discover(fn (ReflectionClass $reflection) => (stripos($reflection->getName(), 'controller') !== false || stripos($reflection->getNamespaceName(), 'controller') !== false));
        $this->enumPaths = $this->discover(fn ($reflection) => $reflection->isEnum());
    }

    private function discover(callable $cb): array
    {
        $classes = [];

        if (empty(self::$classes)) {
            $finder = Finder::create()
                ->in([app_path(), base_path('modules')])
                ->files()
                ->name('/[A-Z].*\.php$/');

            foreach ($finder as $file) {
                $relativePath = $file->getRelativePathname();
                $isModule = str_starts_with($file->getRealPath(), base_path('modules'));

                $className = $isModule
                    ? 'Modules\\'.str_replace(['/', '.php'], ['\\', ''], $relativePath)
                    : app()->getNamespace().str_replace(['/', '.php'], ['\\', ''], $relativePath);

                try {
                    if ($this->fileHasClassLike($file->getRealPath()) && class_exists($className)) {
                        self::$classes[$className] = $file->getRealPath();
                    }
                } catch (\Throwable) {
                    // Ignore exceptions from class loading
                }
            }
        }

        foreach (self::$classes as $className => $path) {
            if ($cb(new ReflectionClass($className))) {
                $classes[$className] = $path;
            }
        }

        return $classes;
    }
}

It's mostly the parent discover() with minor tweaks.

Don't forget to rebind it in a service provider. Once you do, testing the "application-info" tool from the inspector should show all your models listed correctly.

That's it

AI sucks? Maybe. But it sucks a lot less with the right tool, something like Boost.

But don't stop there. There are MCPs for everything, Github, Sentry, Linear. They add tons of value. You can even build your own MCP for fun, I had one that turned on my air fryer (yes, it cooked fries), and another that played a Spotify playlist based on how shitty the code was.

Fun fact: even though I'm shitting on AI a bit here, I used AI to correct my poor grammar. Fixing grammar while getting insulted, cool lol. Sorry AI, you do push me over the line sometimes.

Laravel Under The Hood - The Strategy Pattern

Oussama Mater — Sat, 18 Jan 2025 20:15:31 +0000

Hello 👋

Wikipedia: In computer programming, the strategy pattern (also known as the policy pattern) is a behavioral software design pattern that enables an algorithm's behavior to be selected at runtime.

For the first time, a Wikipedia definition in an IT context makes sense to me. Nonetheless, we'll be discussing the strategy pattern in this article and how Laravel uses it under the hood. It's commonly referred to as the Manager pattern in the Laravel community. I've also encountered it labeled as the "Builder" pattern in a book, something I don't agree with, and I'll explain why later on. In simple terms, the strategy pattern allows you to switch the implementation (or algorithm) based on a condition. Now, before we dive deeper, it's important to understand that these patterns are not sacred texts; they can be implemented in various ways 🤷 (YES REDDIT, YES, I'M LOOKING AT YOU). Patterns will always address the same problem, but can introduce some tweaks, and that's exactly what Laravel has done.

What problem are we solving and how?

In Laravel, you have probably called the driver() method (at least once), when using the Cache facade, with the Mail, or when logging. Let's stick with caching.

Cache::put(key: 'foo', value: 'bar');

This will cache the value 'bar', using the database driver. Now the problem is we don't want to force users to use a single driver; they can choose different ones, like a file driver, a Redis driver, or whatever driver. So we need a way to swap between those implementations based on a condition that the users set, or can affect. If nothing is set, we can always fall back to the default driver.

Laravel solves this by implementing the strategy pattern (or the manager pattern), which allows you to set a driver to be used. For example, if we want to use the file driver instead of the database, we can simply call the driver() method:

Cache::driver('file')->put('foo', 'bar');

The file driver will be used instead of the database because we altered a condition that picks the behavior (implementation) at runtime. Let's see how.

Demystifying the magic

When you call the driver method on the facade, it's proxied to a manager, depending on which facade you're using. In the caching scenario, it's directed to the CacheManager. Let's inspect its code.

Curious about how we got to the Manager from the facade? I highly recommend reading "Facades Under The Hood".

<?php

namespace Illuminate\Cache;

use Illuminate\Contracts\Cache\Factory as FactoryContract;

/**
 * @mixin \Illuminate\Cache\Repository
 * @mixin \Illuminate\Contracts\Cache\LockProvider
 */
class CacheManager implements FactoryContract
{
    // omitted for brevity

    /**
     * Get a cache driver instance.
     *
     * @param  string|null  $driver
     * @return \Illuminate\Contracts\Cache\Repository
     */
    public function driver($driver = null)
    {
        return $this->store($driver);
    }

    // omitted for brevity
}

Here, you'll find the driver() method, which optionally accepts a driver. This method returns whatever results from store().

<?php

namespace Illuminate\Cache;

use Illuminate\Contracts\Cache\Factory as FactoryContract;

/**
 * @mixin \Illuminate\Cache\Repository
 * @mixin \Illuminate\Contracts\Cache\LockProvider
 */
class CacheManager implements FactoryContract
{
    // omitted for brevity

    /**
     * Get a cache store instance by name, wrapped in a repository.
     *
     * @param  string|null  $name
     * @return \Illuminate\Contracts\Cache\Repository
     */
    public function store($name = null)
    {
        // This is the condition we modified by passing a driver.
        $name = $name ?: $this->getDefaultDriver();

        return $this->stores[$name] ??= $this->resolve($name);
    }

    // omitted for brevity
}

If no $name (driver) is set by the user, it defaults to the default driver specified in the configuration under cache.default (have a quick look here). Subsequently, it attempts to resolve that driver. Now, let's inspect the resolve() method.

<?php

namespace Illuminate\Cache;

use Illuminate\Contracts\Cache\Factory as FactoryContract;

/**
 * @mixin \Illuminate\Cache\Repository
 * @mixin \Illuminate\Contracts\Cache\LockProvider
 */
class CacheManager implements FactoryContract
{
    // omitted for brevity

    /**
     * Resolve the given store.
     *
     * @param  string  $name
     * @return \Illuminate\Contracts\Cache\Repository
     *
     * @throws \InvalidArgumentException
     */
    public function resolve($name)
    {
        $config = $this->getConfig($name);

        if (is_null($config)) {
            throw new InvalidArgumentException("Cache store [{$name}] is not defined.");
        }

        $config = Arr::add($config, 'store', $name);

        if (isset($this->customCreators[$config['driver']])) {
            return $this->callCustomCreator($config);
        }

        $driverMethod = 'create' . ucfirst($config['driver']) . 'Driver';

        if (method_exists($this, $driverMethod)) {
            return $this->{$driverMethod}($config);
        }

        throw new InvalidArgumentException("Driver [{$config['driver']}] is not supported.");
    }

    // omitted for brevity
}

You notice that we first fetch the configuration for that driver, so we can build it. Then, we check if the developer extended the cache drivers. Finally, we create a method name following the convention create[Name]driver. In our case, it will be createFileDriver. Afterward, we call this method (which indeed exists) and return the cache implementation for the file driver. This way, the put() and get() methods are called on that implementation.

This implies that if we called Cache::driver('redis'), we would be invoking a method called createRedisDriver, which in turn would return the implementation for the redis driver, and so forth.

The strategy (cache implementation) changes depending on the condition (the given name).

Sounds cool, can we leverage it?

Yes! That's the beauty of source diving. You can now make use of this in your application if you want to swap between different implementations. And the fun part is, there is already a base manager ready to be used!

Let's imagine we are building a notifications system. There are multiple channels: SMS, Emails, Slack, and Discord. Our code will look like this:

<?php

namespace App\Managers;

use App\Notification\DiscordNotification;
use App\Notification\EmailNotification;
use App\Notification\SlackNotification;
use App\Notification\SmsNotification;
use Illuminate\Support\Manager;

class NotificationsManager extends Manager
{
    public function createSmsDriver() // create[Name]Driver
    {
        return new SmsNotification();
    }

    public function createEmailDriver() // create[Name]Driver
    {
        return new EmailNotification();
    }

    public function createSlackDriver() // create[Name]Driver
    {
        return new SlackNotification();
    }

    public function createDiscordDriver() // create[Name]Driver
    {
        return new DiscordNotification();
    }

    public function getDefaultDriver()
    {
        return 'slack'; // will turn into createSlackDriver
    }
}

You can see we didn't define the driver() method ourselves, instead, we extended the base manager which already has it. Now all you are left to do is to wrap this NotificationsManager in a Notification facade.

I won't cover how to do it in this article. That's a good exercise for you. Stuck? here is how.

Suppose we created the facade; you can now do

<?php

use App\Facades\Notification;

Notification::send(); // will use the default driver, slack
Notification::driver('discord') // will use the discord driver
Notification::driver('email') // will use the email driver
Notification::driver('sms') // will use the sms driver

That's it, you created your own manager!

Change My Mind

In the introduction, I mentioned my disagreement with associating the manager pattern with the builder pattern. Perhaps the author saw similarities with the builder pattern more than with the strategy pattern, but for me, it doesn't align. The builder pattern allows you to construct complex objects with dynamic attributes.

Wikipedia: The builder pattern is an object creation software design pattern with the intention of finding a solution to the telescoping constructor anti-pattern.

A basic implementation of the builder pattern might look like this

(new BurgerBuilder())
    ->addPatty()
    ->addLettuce()
    ->addTomato()
    ->prepare();

Each burger can be different; some might have cheese, some might not have lettuce (I HATE LETTUCE, IT FREAKING SUCKS). This pattern fits perfectly, otherwise, we would end up with a bloated constructor like this

public function __construct($cheese = true, $patty = true, $tomato = true, $lettuce = false)
{
}

Similarly, when sending an email in Laravel, we do

Mail::to($request->user())
    ->cc($moreUsers)
    ->bcc($evenMoreUsers)
    ->when($this->condition(...))
    ->locale($request->user()->locale)
    ->send(new OrderShipped($order));

Each mail object will vary from case to case; one object might only have the to() method. Again, if it weren't for this implementation, we would end up with a constructor like this

public function __construct($users, $cc = null, $bcc = null, $when = null, $locale = null)
{
}

They look pretty similar, right? They're almost identical.

Well, one for burgers, the other for mails, but hey you got me 🍔

The Laravel example is known as the "pending pattern", which is essentially a builder pattern. That's why I prefer not to associate the manager pattern with the latter.

Let me know if you want me to write about the pending object!

Conclusion

Patterns solve problems. You don't have to use them everywhere, nor do you have to overdo it. However, it's valuable to understand which pattern is suitable for which situation and what is being used in your framework. This understanding can simplify your workflow. As you've seen, we implemented our manager in just a few lines of code because we understand how Laravel works. Don't expect the implementation or the naming to always be the same; they are not sacred texts. They can be tweaked to suit your needs. Problems may be similar, but they are not always identical.

Laravel Envoy - Automate the boring stuff

Oussama Mater — Sat, 18 Jan 2025 20:03:39 +0000

Laravel Envoy is a tool for executing common tasks you run on your remote servers.

I believe Envoy is underrated, I don't see it being used very often, even though I have always found it super useful. In this article, we will explore how Envoy can help increase your productivity🚀.

Laravel Envoy is not exclusive to Laravel developers or limited to Laravel projects, anyone can use it ❤️.

First, let's discuss two key concepts in Envoy:

Tasks: which represents a specific action like updating the server or cloning a repository.
Stories: which is a collection of Tasks.

That's all you need to know for now, you can always read about all the features in the docs.

What are we automating?

In this article, we will automate 2 things most developers do when deploying their application:

Configuring Nginx.
Generating SSH keys and adding them to GitHub to be able to access private repositories.

Yes I know, most of the times Envoy is used for CI/CD workflows, but it can do EVERYTHING, literally.

Envoy Setup

First let's create a directory

mkdir tuto && cd $_

$ take tuto if you are using zsh.

Install Envoy by running the following command:

composer require laravel/envoy --dev

Make sure you have composer installed.

Now create a file called Envoy.blade.php. Yes we will be using the Blade syntax, super cool right?

touch Envoy.blade.php

That's it! All you need is a single script. It doesn't have to be specific to Laravel or any Laravel related project. Let's start automating! 😁

Configure Nginx

We have a brand new server, and we want to setup Nginx. If we break down the process it would be like:

Update the server
Install Nginx
Configure Nginx

That's exactly what we will be doing with Envoy, think of each step as a Task, and the entire process as a Story.

So let's translate what we have just said into a story:

@servers(['web' => 'oussama@192.168.1.100', 'local' => '127.0.0.1'])

@story('setup-nginx')
    update-server
    install-nginx
    copy-nginx-stub
    configure-nginx
@endstory

The @servers directive is used to specify the servers on which we will be running our tasks later on.

Now we can proceed to define each task 😁

Our first task update-server will ensure that the server's packages and dependencies are up to date:

@task('update-server', ['on' => ['web']])
    echo "Updating server..."

    apt update && apt upgrade -y
@endtask

The second task install-nginx will install Nginx on our server:

@task('install-nginx', ['on' => ['web']])
    echo "Installing nginx..."

    apt install nginx -y

    rm /etc/nginx/sites-enabled/default /etc/nginx/sites-available/default

    touch /etc/nginx/sites-available/{{ $application_name }}.conf

    ln -s /etc/nginx/sites-available/{{ $application_name }}.conf /etc/nginx/sites-enabled/{{ $application_name }}.conf
@endtask

Notice that we have removed the default Nginx link and created a new one for our application, with the name coming from the $application_name variable.

To be able to use that variable, you need to declare it, so we need to include the @setup directive:

@setup
    $application_name = 'your-application-name';
@endsetup

Now we can move to the third task copy-nginx-stub. In my case, I am deploying a Laravel application, so I will use the Nginx configuration file provided by the docs, with few tweaks. If you're deploying a different application, you can apply the same concept to your own configuration file.

In the directory we just created, run the following command:

mkdir stubs; nano stubs/nginx.conf

Then, paste the following content into the editor, save it, and exit:

server {
    listen 80;
    listen [::]:80;
    server_name public_ip;
    root /var/www/app_name/public;

    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";

    index index.php;

    charset utf-8;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    error_page 404 /index.php;

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.0-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

The public_ip and app_name are placeholders for now and will be automatically updated with our variables.

Let's move on to writing the task itself:

@task('copy-nginx-stub', ['on' => 'local'])
    scp -P{{ $production_port }} -r ./stubs/nginx.conf
    {{ $production_host }}:/etc/nginx/sites-available/{{ $application_name }}.conf
@endtask

This task will be executed on our local machine instead of the remote server. We specify this using 'on' => 'local'.

And don't forget to update the @setup directive with the necessary variables:

@setup
    $application_name = 'your-application-name';
    $production_port = 22;
    $production_host = 'oussama@192.168.1.103';
@endsetup

The fourth and final task configure-nginx will update the placeholders, so we can serve the application correctly:

@task('configure-nginx', ['on' => 'web'])
    echo "Configuring nginx..."

    cd /etc/nginx/sites-available/

    sed -i 's/app_name/{{ $application_name }}/g' {{ $application_name }}.conf
    sed -i 's/public_ip/{{ $production_ip }}/g' {{ $application_name }}.conf
@endtask

Note the cd command. This is because each task is executed separately, so it always starts from the home directory of the remote server.

We have already created the symlink when installing Nginx, we don't have to worry about it now.

And we are done for this section! Your script should look like this:

@servers(['web' => 'oussama@192.168.1.100', 'local' => '127.0.0.1'])

@setup
    $application_name = 'your-application-name';
    $production_port = 22;
    $production_host = 'oussama@192.168.1.103';
@endsetup

@story('setup-nginx')
    update-server
    install-nginx
    copy-nginx-stub
    configure-nginx
@endstory

@task('update-server', ['on' => ['web']])
    echo "Updating server..."

    apt update && apt upgrade -y
@endtask

@task('install-nginx', ['on' => ['web']])
    echo "Installing nginx..."

    apt install nginx -y

    rm /etc/nginx/sites-enabled/default /etc/nginx/sites-available/default

    touch /etc/nginx/sites-available/{{ $application_name }}.conf

    ln -s /etc/nginx/sites-available/{{ $application_name }}.conf /etc/nginx/sites-enabled/{{ $application_name }}.conf
@endtask

@task('copy-nginx-stub', ['on' => 'local'])
    scp -P{{ $production_port }} -r ./stubs/nginx.conf
    {{ $production_host }}:/etc/nginx/sites-available/{{ $application_name }}.conf
@endtask

@task('configure-nginx', ['on' => 'web'])
    echo "Configuring nginx..."

    cd /etc/nginx/sites-available/

    sed -i 's/app_name/{{ $application_name }}/g' {{ $application_name }}.conf
    sed -i 's/public_ip/{{ $production_ip }}/g' {{ $application_name }}.conf
@endtask

SSH Key Configuration

Now that we configured Nginx, and it is ready to serve our application, we need to generate ssh keys, and add the public key to Github so we can pull the private repositories.

For this we will use GitHub REST API, so before we start, you need to create a token.

When creating your token, ensure that you only select the "admin:public_key" scope.

Now that you created your token, let's begin by defining some variables:

@setup
    $ssh_key = '~/.ssh/id_rsa_github';
    $github_api_key = 'your-github-token';
    $email = 'oussama@example.com';
@endsetup

At this point, you might be wondering about the steps involved in this process. Well we can break it down into two steps:

Generate SSH keys
Copy the public key to Github

Once again this process will be our story:

@story('setup-ssh-keys')
    generate-ssh-keys
    add-ssh-keys-to-github
@endstory

The first task generate-ssh-keys, can be done by running a single command:

@task('generate-ssh-keys', ['on' => ['web']])
    echo "Generating ssh keys..."

    ssh-keygen -t ed25519 -f {{ $ssh_key }} -N '' -q -C "{{ $email }}"
@endtask

Once we have generated our SSH keys, we can add the public key to Github using the Github API. This can be done with a single request:

@task('add-ssh-keys-to-github', ['on' => ['web']])
    echo "Adding ssh keys to github..."

    key=$(cat {{ $ssh_key }}.pub)

    curl --request POST \
    --url https://api.github.com/user/keys \
    --header 'Accept: application/vnd.github+json' \
    --header 'Authorization: Bearer {{ $github_api_key }}' \
    --header 'Content-Type: application/json' \
    --header 'X-GitHub-Api-Version: 2022-11-28' \
    --data '{
    "title": "[Envoy] Public key",
    "key": "'"$key"'"
    }'
@endtask

And that's it! If you visit your Github developer settings, you should see your newly created key.

By combining the two sections, your final script should look like this:

@servers(['web' => 'oussama@192.168.1.100', 'local' => '127.0.0.1'])

@setup
    $application_name = 'your-application-name';
    $production_port = 22;
    $production_host = 'oussama@192.168.1.103';
    $ssh_key = '~/.ssh/id_rsa_github';
    $github_api_key = 'your-github-token';
    $email = 'oussama@example.com';
@endsetup

@story('setup-nginx')
    update-server
    install-nginx
    copy-nginx-stub
    configure-nginx
@endstory

@story('setup-ssh-keys')
    generate-ssh-keys
    add-ssh-keys-to-github
@endstory

@task('update-server', ['on' => ['web']])
    echo "Updating server..."

    apt update && apt upgrade -y
@endtask

@task('install-nginx', ['on' => ['web']])
    echo "Installing Nginx..."

    apt install nginx -y

    rm /etc/nginx/sites-enabled/default /etc/nginx/sites-available/default

    touch /etc/nginx/sites-available/{{ $application_name }}.conf

    ln -s /etc/nginx/sites-available/{{ $application_name }}.conf /etc/nginx/sites-enabled/{{ $application_name }}.conf
@endtask

@task('copy-nginx-stub', ['on' => 'local'])
    scp -P{{ $production_port }} -r ./stubs/nginx.conf
    {{ $production_host }}:/etc/nginx/sites-available/{{ $application_name }}.conf
@endtask

@task('configure-nginx', ['on' => 'web'])
    echo "Configuring nginx..."

    cd /etc/nginx/sites-available/

    sed -i 's/app_name/{{ $application_name }}/g' {{ $application_name }}.conf
    sed -i 's/public_ip/{{ $production_ip }}/g' {{ $application_name }}.conf
@endtask

@task('generate-ssh-keys', ['on' => ['web']])
    echo "Generating ssh keys..."

    ssh-keygen -t ed25519 -f {{ $ssh_key }} -N '' -q -C "{{ $email }}"
@endtask

@task('add-ssh-keys-to-github', ['on' => ['web']])
    echo "Adding ssh keys to github..."

    key=$(cat {{ $ssh_key }}.pub)

    curl --request POST \
    --url https://api.github.com/user/keys \
    --header 'Accept: application/vnd.github+json' \
    --header 'Authorization: Bearer {{ $github_api_key }}' \
    --header 'Content-Type: application/json' \
    --header 'X-GitHub-Api-Version: 2022-11-28' \
    --data '{
    "title": "creating from script",
    "key": "'"$key"'"
    }'
@endtask

Conclusion

We learned how to use Envoy to automate common tasks. It's a powerful tool with even more capabilities than we've explored here. Don't limit yourself to just deploying your applications, Envoy can automate ANY terminal command, literally anything that comes to mind.

The next time you find yourself repeating the same commands, consider using it, I promise you it does way more than CI/CD 😛😛

Laravel Under The Hood - Extending the framework

Oussama Mater — Sat, 30 Nov 2024 18:52:26 +0000

Hello 👋

A few days ago, I was fixing a flaky test, and it turned out I needed some unique and valid values within my factory. Laravel wraps FakerPHP, which we usually access through the fake() helper. FakerPHP comes with modifiers like valid() and unique(), but you can use only one at a time, so you can't do fake()->unique()->valid(), which is exactly what I needed. This made me think, what if we want to create our own modifier? For example, uniqueAndValid(), or any other modifier. How can we extend the framework?

Thinking out loud

I will be dumping my train of thought.

Before jumping into any over-engineered solution, I always want to check if there is a simpler option and understand what I'm dealing with. So, let's take a look at the fake() helper:

function fake($locale = null)
{
    if (app()->bound('config')) {
        $locale ??= app('config')->get('app.faker_locale');
    }

    $locale ??= 'en_US';

    $abstract = \Faker\Generator::class.':'.$locale;

    if (! app()->bound($abstract)) {
        app()->singleton($abstract, fn () => \Faker\Factory::create($locale));
    }

    return app()->make($abstract);
}

Reading the code, we can see that Laravel binds a singleton to the container. However, if we inspect the abstract, it's a regular class that does not implement any interface, and the object is created via a factory. This complicates things. Why?

Because if it were an interface, we could just create a new class that extends the base \Faker\Generator class, add some new features, and rebind it to the container. But we don't have this luxury.
There is a factory involved. This means it's not a simple instantiation, there is some logic being run. In this case, the factory adds some providers (PhoneNumber, Text, UserAgent, etc..). So, even if we try to rebind, we will have to use the factory, which will return the original \Faker\Generator.

Solutions 🤔? One might think, "What's stopping us from creating our own factory that returns the new generator as outlined in point 1?" Well, nothing, we can do that, but we won't! We use a framework for several reasons, one of them being updates. What will happen if FakerPHP adds a new provider or has a major upgrade? Laravel will adjust the code, and people who haven't made any changes won't notice anything. However, we would be left out, and our code might even break (most likely). So, yes, we don't want to go that far.

So, what do we do?

Now that we've explored the basic options, we can start thinking of more advanced ones, like design patterns. We don't need an exact implementation, just something familiar to our problem. This is why I always say it's good to know them. In this case, we can "decorate" the Generator class by adding new features while maintaining the old ones. Sounds good? Let's see how!

First, let's create a new class, FakerGenerator:

<?php

namespace App\Support;

use Closure;
use Faker\Generator;
use Illuminate\Support\Traits\ForwardsCalls;

class FakerGenerator
{
    use ForwardsCalls;

    public function __construct(private readonly Generator $generator)
    {
    }

    public function uniqueAndValid(Closure $validator = null): UniqueAndValidGenerator
    {
        return new UniqueAndValidGenerator($this->generator, $validator);
    }

    public function __call($method, $parameters): mixed
    {
        return $this->forwardCallTo($this->generator, $method, $parameters);
    }
}

This will be our "decorator" (kinda). It is a simple class that expects the base Generator as a dependency and introduces a new modifier, uniqueAndValid(). It also uses the ForwardsCalls trait from Laravel, which allows it to proxy calls to the base object.

This trait has two methods: forwardCallTo and forwardDecoratedCallTo. Use the latter when you want to chain methods on the decorated object. In our case, we will always have a single call.

We also need to implement the UniqueAndValidGenerator, which is the custom modifier, but this is not the point of the article. If you are interested in the implementation, this class is basically a mixture of the ValidGenerator and UniqueGenerator that ship with FakerPHP, you can find it here.

Now, let's extend the framework, in the AppServiceProvider:

<?php

namespace App\Providers;

use Closure;
use Faker\Generator;
use App\Support\FakerGenerator;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->extend(
            $this->fakerAbstractName(), 
            fn (Generator $base) => new FakerGenerator($base)
        );
    }

    private function fakerAbstractName(): string
    {
        // This is important, it matches the name bound by the fake() helper
        return Generator::class . ':' . app('config')->get('app.faker_locale');
    }
}

The extend() method checks if an abstract matching the given name has been bound to the container. If so, it overrides its value with the result of the closure, take a look:

// Laravel: src/Illuminate/Container/Container.php

public function extend($abstract, Closure $closure)
{
    $abstract = $this->getAlias($abstract);

    if (isset($this->instances[$abstract])) {
         // You are interested here
        $this->instances[$abstract] = $closure($this->instances[$abstract], $this);

        $this->rebound($abstract);
    } else {
        $this->extenders[$abstract][] = $closure;

        if ($this->resolved($abstract)) {
            $this->rebound($abstract);
        }
    }
}

That's why we defined the fakerAbstractName() method, which generates the same name the fake() helper binds in the container.

Recheck the code above if you missed it, I left a comment.

Now, every time we call fake(), an instance of FakerGenerator will be returned, and we will have access to the custom modifier we introduced. Every time we invoke a call that does not exist on the FakerGenerator class, __call() will be triggered, and it will proxy it to the base Generator using the forwardCallTo() method.

That's it! I can finally do fake()->uniqueAndValid()->randomElement(), and it works like a charm!

Before we conclude, I want to point out that this is not a pure decorator pattern. However, patterns are not sacred texts; tweak them to fit your needs and solve the problem.

Conclusion

Frameworks are incredibly helpful, and Laravel comes with a lot of built-in features. However, they can't cover all the edge cases in your projects, and sometimes you might hit a dead end. When that happens, you can always extend the framework. We've seen how simple it is, and I hope you understood the main idea, which applies beyond just this Faker example.

Always start simple and look for the simplest solution to the problem. Complexity will come when it's necessary, so if basic inheritance does the trick, there's no need to implement a decorator or anything else. When you do extend the framework, ensure you don't go too far, where the loss outweighs the gain. You don't want to end up maintaining a part of the framework on your own.

Laravel Custom Query Builders Over Scopes

Oussama Mater — Mon, 25 Nov 2024 18:38:47 +0000

Hello 👋

Alright, let's talk about Query Scopes. They're awesome, they make queries much easier to read, no doubt about it. But there's one thing I hate about them: magic. And when you're working with a team where not everyone is a backend developer, it can make their lives miserable. Sure, you can add PHPDocs, but there’s always some magic going on. If you've never used scopes before, no worries, hang tight bud.

So, What Are Scopes? 🤔

Consider this code:

use App\Models\User;

$users = User::query()
    ->where('votes', '>', 100);
    ->where('active', 1);
    ->orderBy('created_at')
    ->get();

This is how you would typically write queries. But when queries become too complex or hard to read, you can abstract them into scopes:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    public function scopePopular(Builder $query): void
    {
        $query->where('votes', '>', 100);
    }

    public function scopeActive(Builder $query): void
    {
        $query->where('active', 1);
    }
}

Now you can do this:

$users = User::query()
    ->popular()
    ->active()
    ->orderBy('created_at')
    ->get();

Reads much better right? I know. But the issue is, you don't get any autocompletion. This is dark magic to the IDE. Since scopes are resolved at runtime and prefixed with scope, there is no way your IDE knows about them unless you help it out.

One way is through PHPDocs, like so:


/**
 * @method static Builder popular()
 * @method static Builder active()
 */
class User extends Model

Another downside to scopes? The most frequently used models end up bloated with tons of them, for nothing. I love skimming through my models and immediately seeing the relationships and core logic, not a bunch of query abstractions.

Sooo? Do we just ditch scopes and move on? Well, that's an option, or you could use custom query builders.

Custom Query Builders 😎

As the name suggests, a custom query builder let's you move all your query abstractions into a dedicated class. The code will be more organized in a way.

Let's create a new class UserQueryBuilder:

<?php

namespace App\Eloquent\QueryBuilders;

use App\Models\User;
use Illuminate\Database\Eloquent\Builder;

class UserQueryBuilder extends Builder
{
    public function popular(): self
    {
        return $this->where('votes', '>', 100);
    }

    public function active(): self
    {
        return $this->where('active', 1);
    }
}

Where to put builders? There is no guideline, but I personally like to place them in app/Eloquent/QueryBuilders.

Now let's use this builder in the User model:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    public function newEloquentBuilder($query): UserQueryBuilder
    {
        return new UserQueryBuilder($query);
    }

    // for type hints
    public static function query(): UserQueryBuilder
    {
        return parent::query();
    }
}

And just like that, you can now do:

$users = User::query()
    ->popular()
    ->active()
    ->orderBy('created_at')
    ->get();

Works exactly the same, and you get full autocompletion. Plus, code navigation works perfectly, it takes you where you need to be 🙌

Another cool thing is you can dynamically resolve query builders if needed.

public function newEloquentBuilder($query): UserQueryBuilder
{
    if ($this->status === State::Pending) {
        return new PendingUserQueryBuilder($query); // extends UserQueryBuilder
    }

    return new UserQueryBuilder($query);
}

This way you avoid having one big query builder when you can group queries by context (like a state).

That's it ✅

Scopes are cool, and if I only have 2-3 of them, I'll stick with them. But when things start to get out of hand, custom query builders are the way to go. They are worth the extra effort, keeping your code clean, organized, and easier to maintain 🚀

Laravel Under The Hood - A Little Bit of Macros

Oussama Mater — Mon, 04 Nov 2024 11:33:15 +0000

Hello 👋

How often have you wished for a method that doesn't exist on collections or string helpers? You start chaining methods, only to hit a wall when one of them turns out to be missing. Honestly, it's understandable; frameworks, you know, are a one-size-fits-all thing. I found myself in this situation multiple times. Every time, before diving into how to extend the framework, I check to see if what I want to extend is macroable or not. But what does that mean? That's exactly what we'll be exploring!

WTF are Macros? 🍏

Let's say we have this JWT:

$jwt = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c';

And we need to extract the headers:

str($jwt)
    ->before('.')
    ->fromBase64()
    ->fromJson(); // does not exist 😞

//  BadMethodCallException  Method Illuminate\Support\Stringable::fromJson does not exist.

The fromJson() doesn't exist 😔 Sure, one could simply do:

json_decode(str($jwt)->before('.')->fromBase64());

But where's the fun in that? Plus, it is my article 🤷

So, we need a way to extend the Stringable class. There are a few ways to do this, but Laravel thought ahead, it knew that developers might want to add custom methods, so it made the class macroable, or as I like to call it, extendable.

If you inspect the Illuminate\Support\Stringable class, you'll see it uses a Macroable trait.

Let's go ahead and extend the class. In the AppServiceProvider, add the following:

<?php

namespace App\Providers;

use Illuminate\Support\Stringable;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Stringable::macro('fromJson', function (bool $associative = true) {
            return json_decode($this->value, $associative);
        });
    }
}

Now let's rerun the code:

str($jwt)
    ->before('.')
    ->fromBase64()
    ->fromJson();

// ["alg" => "HS256", "typ" => "JWT"]

It works perfectly 🎉 But now, you might be wondering, how did this work? And what exactly is $this->value? What in the harry potter is going on?

Unveiling the magic 🪄

We know that the Stringable class uses the Macroable trait, which provides the macro() method. Let's take a closer look at what it does:

// src/Illuminate/Macroable/Traits/Macroable.php

/**
 * Register a custom macro.
 *
 * @param  string  $name
 * @param  object|callable  $macro
 *
 * @param-closure-this static  $macro
 *
 * @return void
 */
public static function macro($name, $macro)
{
    static::$macros[$name] = $macro;
}

It's pretty straightforward, it just saves the callback to a static macros array. Now, if we inspect the trait further, we will find the __call method, which is triggered every time a non-existent method is called. In our case, that's fromJson(). Let's dive in:

/**
 * Dynamically handle calls to the class.
 *
 * @param  string  $method
 * @param  array  $parameters
 * @return mixed
 *
 * @throws \BadMethodCallException
 */
public function __call($method, $parameters)
{
    if (! static::hasMacro($method)) {
        throw new BadMethodCallException(sprintf(
            'Method %s::%s does not exist.', static::class, $method
        ));
    }

    $macro = static::$macros[$method];

    if ($macro instanceof Closure) {
        $macro = $macro->bindTo($this, static::class);
    }

    return $macro(...$parameters);
}

First, it checks if a macro is registered, which is the case with fromJson(), it then fetches the callback (or object) from the macros array. Now for the magic trick, if the macro is a closure (as in our case), it calls bindTo(), which essentially tells the closure that $this should refer to whatever is passed as the first argument. In this case, it is the Stringable instance, which happens to have the $value attribute.

// $this here is the stringable
// $this inside the closure is now referencing the stringable class
$macro->bindTo($this, static::class);

And this is why we can do $this->value.

We can do better: Mixins 🧩

There is one more thing I want to show you! When we extend the same class a couple of times, the service provider might get messy very quick. We can extract all our custom macros to a class called a Mixin.

Let's create a StringableMixin:

<?php

namespace App\Macros;

use Closure;

class StringableMixin
{
    public function fromJson(): Closure
    {
        return function (bool $associative = true) {
            json_decode($this->value, $associative);
        };
    }

    // Add more macros here as needed
}

Now, in AppServiceProvider, we can register this mixin:

use App\Macros\StringableMixin;
use Illuminate\Support\Stringable;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Stringable::mixin(new StringableMixin);
    }
}

And that's it! Now we can do:

str($jwt)
    ->before('.')
    ->fromBase64()
    ->fromJson();

Which is basically the same, just a bit cleaner.

If you are curious about how this works, the mixin() method on the Macroable trait uses the reflection API. It retrieves all the public methods from the Mixin class, expects each to return a closure, and then registers the closure as a macro just like we have seen earlier.

The Poor IDE 🥲

Well, as you have seen, there is a lot of magic going on, and the IDE wouldn't know about the defined macros. If you're working within a team, other developers won't know about these macros either, which is not good. Luckily, there are tools to help you with that. A free and open source option is the Laravel IDE helper package.

You can install the package and generate the _ide_helper.php file, and you should be good to go.

And so it ends..

Our example is fairly simple, but you can push macros much further than this, as most of the common classes Laravel ships with are macroable. For instance, you can add a new apiResponse() macro, or anything that you feel is very common in your app's logic and is being repeated more than it should be. But don't overdo it. Macros add a new layer of complexity, and when working in a team, they could be confusing.

Soo, whenever you feel something is missing from your application, but not from the framework itself, use macros 🪄

Code to an interface!

Oussama Mater — Mon, 24 Jun 2024 12:22:00 +0000

Hello 👋

As you get more serious about programming, you inevitably encounter the phrase "Code to an interface", either in videos, books, or articles. And it never made sense to me. I questioned the need to create an interface and then implement it. How do I determine when and where to use these interfaces? Whenever I watched a tutorial or read an article, they would explain what an interface is, "It is a class without implementation", and I am like "Ehmm, thanks 😏". I mean, I already knew that; what I really wanted to know was why and when to use it.

I remember one day asking on the Discord community, and one of the seniors simply said, "Don't worry; it will eventually click for you", and it did, it took some time, but it did. If you're experiencing this, know that we've all been there, let's help you understand why you need to Code to an interface.

Let's write some code

Since AI is taking over, and everyone is losing their shit about it, we don't want to be late to the party. We want to add it to our website, a small chatbot that answers questions about our product will do it.

I will be using PHP for my example; feel free to use any language you are comfortable with. What matters is the concept.

Our chatbot can be as simple as this

<?php

class ChatBot
{
    public function ask(string $question): string
    {
        $client = new OpenAi();

        $response = $client->ask($question);

        return $response;
    }
}

There's a single method ask(), which uses the OpenAI SDK to connect to their API, pose a question, and then simply return the response.

We can now start using our chatbot

$bot = new ChatBot();

$response = $bot->ask('How much is product X'); // The product costs $200.

So far, the implementation looks good, it's functioning as expected and the project is deployed and in use. But, we cannot deny that our chatbot is heavily dependent on the Open AI API, I'm sure you agree.

Now, let's consider a scenario where Open AI prices double, and continue to increase, what are our options? We either just accept our fate, or look for another API. The first option is easy, we just keep paying them, and the 2nd one is not as simple as it sounds. The new provider will likely have its own API and SDK, we will have to make updates to all classes, tests, and related components originally designed for Open AI, that's a lot of work.

This also raises concerns, what if the new API doesn't meet our expectations in terms of accuracy or has increased downtime? What if we want to just experiment with different providers simultaneously? For example, providing our subscribed clients with the OpenAI client while using a simpler API for guests? You can see how this can be complex, and you know why? Because our code was poorly designed. We didn't have a vision; we just picked an API and were completely dependent on it and its implementation. Now, the principle of "Code to interface" would have saved us from all of this. How? Let's see.

Let's start with creating an interface

<?php

interface AIProvider
{
    public function ask(string $question): string;
}

We have our interface, or as I like to call it, a contract. Let's implement it, or code to it.

<?php

class OpenAi implements AIProvider
{
    public function ask(string $question): string
    {
        $openAiSdk = new OpenAiSDK();
        $response = $openAiSdk->ask($question);

        return "Open AI says: " . $response;
    }
}

class RandomAi implements AIProvider
{
    public function ask(string $question): string
    {
        $randomAiSdk = new RandomAiSDK();
        $response = $randomAiSdk->send($question);

        return "Random AI replies: " . $response->getResponse();
    }
}

In reality, both OpenAiSDK and RandomAiSDK will be injected through the constructor. This way we delegate the complex instantiation logic to a DI container, a concept known as inversion of control. This is because each provider typically requires certain configurations.

We now have two providers that we can use to answer questions. Regardless of their implementation, we are confident that when given a question, they will connect to their API and respond to it. They have to adhere to the contract AIProvider.

Now, in our ChatBot, we can do the following

class ChatBot
{
    private AIProvider $client;

    // A dependency can be injected via the constructor
    public function __construct(AIProvider $client)
    {
        $this->client = $client;
    }

    // It can also be set via a setter method
    public function setClient(AIProvider $client): void
    {
        $this->client = $client;
    }

    public function ask(string $question): string
    {
        return $this->client->ask($question);
    }
}

Note well that the example aims to demonstrate the multiple ways you can inject a dependency, in this case, an AIProvider. You are not required to use both constructors and setters.

You can see we made some tweaks; we no longer depend on OpenAI, and you won't find any reference to it. Instead, we depend on the contract/interface. And, somehow, we can relate to this example in real life; we have all been a ChatBot at least once.

Imagine purchasing a solar panel system. The company promises to send technicians to install it, assuring you that regardless of the employee they send, the job will be done, and you'll have your panels installed in the end. So, you don't really care whether they send Josh or George. They might be different, with one being better than the other, but both are contracted to install the panels. They won't be like, you know what I am repairing your TV instead, they are obligated by the company to do the specified job. Both RandomAi and OpenAi act as employees of AIProvider; you ask a question, and they will provide an answer. Just as you didn't care about who installs the panels, the ChatBot shouldn't care at all about who does the job. It just needs to know that any implementation provided will do it.

Now, you can freely use one or another

$bot = new ChatBot();

// For subscribed users
$bot = new ChatBot(new OpenAi());
$response = $bot->ask('How much is Product X'); // Open AI says: 200$

// For guests
$bot->setClient(new RandomAi());
$response = $bot->ask('How much is Product X'); // Random AI replies: 200$

Now, you have the flexibility to change the entire API provider, and your code will always behave the same. You don't have to change anything about it because you coded to an interface, so none of the concerns we raised earlier will be an issue.

There are bonuses, always

In our example, by coding to an interface, we have also respected three of the SOLID principles, without even knowing we did, let me elaborate.

I won't go into details; each of the principles can have a long article. This is just a brief explanation to show what we gained by coding to an interface.

Open-Closed Principle

The first principle we respected is the Open-Closed Principle, which states that the code should be open for extension and closed for modification. As challenging as it may sound, you've achieved it. Think about it, the ChatBot is closed for modification now; we won't touch the code again. This was our goal from the beginning. But, it is open for extension; if we were to add a 3rd, 4th, or even a 5th provider, nothing is stopping us. We can implement the interface, and our class can use it out of the box, no changes are required.

Liskov Substitution

I won't bore you with its definition, but basically, it states that you can substitute classes with ALL their subclasses and vice versa. Technically, all of our AI providers are-a AIProvider, and their implementations can be swapped for one another, without affecting the correctness of ChatBot, the latter does not even know which provider it is using 😂, so yes, we respected Ms. Liskov.

Dependency Inversion

I must admit, this one could have its own article. But to put it simply, the principle states that you should depend on abstractions rather than concretes, which is exactly what we are doing. We are dependent on a provider, not a specific one like Open AI.

Remember, all of this, is because we coded to an interface.

It will eventually click for you

Whenever you update a class that you know you shouldn't update, and your code is getting hacky with if statements, you need an interface. Always ask yourself, does this class really need to know the how? Will I forever use this service provider? or database driver? If not, you know what to do.

With that being said, just give it some time, it will eventually click for you.