Forem: Goran Popović

Running custom Artisan commands with Supervisor

Goran Popović — Tue, 05 Mar 2024 00:35:25 +0000

If you ever used Laravel queues on the server, you probably came across a section in the documentation about needing to run a Supervisor on your server in order to keep your queue processes going in case they are stopped for whatever reason. What you would typically need to do is configure the Supervisor to run the queue:work Artisan command.

I won't get too much into detail now on how different Artisan commands regarding queues are functioning behind the scenes, but if we take a closer look at the queue:work command, for example, essentially what is going on is that the jobs are being run inside a while loop, and if certain conditions are met, the worker will be stopped and the command will exit. After that, the Supervisor will run it again.

Here is an example of what a trimmed-down and simplified version of that loop might look like (taken from the daemon function inside the Illuminate/Queue/Worker.php file):

while (true) {
    // Get the next job from the queue.
    $job = $this->getNextJob(
        $this->manager->connection($connectionName), $queue
    );

    // Run the job if needed.
    if ($job) {
        $jobsProcessed++;

        $this->runJob($job, $connectionName, $options);
    }

    // Get the worker status.
    $status = $this->stopIfNecessary(
        $options, $lastRestart, $startTime, $jobsProcessed, $job
    );

    // Stop the worker if needed.
    if (! is_null($status)) {
        return $this->stop($status, $options);
    }
}

Custom command

Now, if we were to take that example as a starting point, we could create our own command that could be run indefinitely (if needed) with the help of the Supervisor.

Let's say we created an app for the Handyman Tools Store. The user selects an item, fills in the necessary data, and submits an order for a specific tool. As soon as the order is created, it is automatically set to a pending status. To be able to monitor that kind of order and include some logic of our own, we could create a custom Artisan command that would check for all pending orders from time to time, and if any are found, we could dispatch a Laravel job that would further process that order (maybe check if the tool is in stock, can it be shipped to the user's location, and send an email to the user about that order status).

Here is an example of such a command:

namespace App\Console\Commands;

use Illuminate\Console\Command;

class MonitorOrders extends Command
{
    /**
     * The name and signature of the console command.
     *
     * @var string
     */
    protected $signature = 'orders:monitor';

    /**
     * The console command description.
     *
     * @var string
     */
    protected $description = 'Monitor pending tool orders and dispatch them for processing.';

    /**
     * Execute the console command.
     */
    public function handle()
    {
        while (true) {
            // Get all the orders with the pending status
            $orders = Order::where('status', 'pending')->get();

            // If there are no orders with a pending status wait for a second then check again
            if ($orders->doesntExist()) {
                sleep(1);

                continue;
            }

            foreach ($orders as $order) {
                // Dispatch the order for further processing to a job
                ProcessOrder::dispatch($order)
                    ->onQueue('orders')
                    ->onConnection('database');
            }

            sleep(1); // Potentially take a break between runs
        }
    }
}

Option for max jobs

What if we wanted to specify the number of jobs that should be processed, similar to the --max-jobs flag? If the maximum number of jobs is reached the worker could exit and release any memory that may have accumulated. To achieve that, we could introduce a new option to our command, like this:

/**
 * The name and signature of the console command.
 *
 * @var string
 */
protected $signature = 'orders:monitor
                        {--max-jobs=100 : The number of jobs to process before stopping}';

Then, in our handle method, we can set the initial number of the processed jobs and get the maximum number from the option we defined previously:

/**
 * Execute the console command.
 */
public function handle()
{
    $jobsProcessed = 0;
    $maxJobs = $this->option('max-jobs');

    while (true) {
            // Get all the orders with the pending status
            $orders = Order::where('status', 'pending')->get();

As soon as the job is sent to be processed, we will increment the $jobsProcessed variable and check if the worker should exit. If that is the case, we would just return a default success exit code (0). After the worker exits, the Supervisor will restart it again.

foreach ($orders as $order) {
    // Dispatch the order for further processing to a job
    ProcessOrder::dispatch($order)
        ->onQueue('orders')
        ->onConnection('database');

    // Increase the number of processed jobs
    $jobsProcessed++;

    // Stop the command if the number of jobs reaches the maximum number set
    if($jobsProcessed >= $maxJobs) {
        return 0; // Success
    }
}

Restarting the command manually

When you update the code inside of the command and deploy it to the server, the change won't be reflected until the Supervisor has had a chance to actually restart the worker. To resolve that issue, you could restart the Supervisor itself on deploy (and reread the configuration file if you updated it):

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl restart

Or better yet, we could create another custom command that will cause our initial orders:monitor command to exit, again allowing the Supervisor to restart it. We could do that by using the built-in Cache functionality, similar to how the queue:restart command does it.

Here is an example of how our orders:restart command could look like:

<?php

namespace App\Console\Commands;

use Illuminate\Console\Command;
use Illuminate\Support\Facades\Cache;

class RestartOrders extends Command
{
    /**
     * The console command name.
     *
     * @var string
     */
    protected $name = 'orders:restart';

    /**
     * The console command description.
     *
     * @var string
     */
    protected $description = 'Restart orders monitor command after the current job.';

    /**
     * Execute the console command.
     *
     * @return void
     */
    public function handle()
    {
        Cache::forever('orders:restart', true);
    }
}

Now, we need to amend our orders:monitor command to check if the orders:restart has been triggered. Make sure to include the Cache facade first:

use Illuminate\Support\Facades\Cache;

And then update the loop like so:

foreach ($orders as $order) {
    // Dispatch the order for further processing to a job
    ProcessOrder::dispatch($order)
        ->onQueue('orders')
        ->onConnection('database');

    // Increase the number of processed jobs
    $jobsProcessed++;

    // Stop the command if the number of jobs reaches the maximum number set
    if($jobsProcessed >= $maxJobs) {
        return 0; // Success
    }

    // Get the restart command value from the cache
    $restartCommand = Cache::get('orders:restart', false);

    // Stop the command if needed and remove the entry from the cache
    if($restartCommand) {
        Cache::forget('orders:restart');
        return 0; // Success
    }
}

That's it. Now you can add the orders:restart command to your deploy procedure, and you won't have to worry about any changes in your code not being reflected.

As per usual, you can check out the Gist for source code.

Supervisor configuration

What's left for us to do is add a supervisor configuration file, named, for example, monitor-orders.conf, in the /etc/supervisor/conf.d directory (location of the directory in most cases) that starts (and restarts, if needed) our command, which will in turn continually monitor for any pending tool orders.

[program:monitor-orders]
process_name=%(program_name)s_%(process_num)02d
command=php /home/forge/app.com/artisan orders:monitor --max-jobs=300
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=forge
numprocs=8
redirect_stderr=true
stdout_logfile=/home/forge/app.com/worker.log
stopwaitsecs=3600

The setup above uses an example from the documentation, but you may not need to spawn 8 processes (numprocs), depending on the number of orders you receive. The path to the Artisan command on your server might be completely different; it could be something like php /var/www/my-website.com/artisan so make sure to double check that as well as the user value and the path to the worker.log file.

Conclusion

We made it. Following the basic example of the queue:work command and the instructions from the Laravel documentation, we were able to create our own custom command that will monitor for pending orders in our app for Handyman Tools. With the help of the Supervisor, the command will be run automatically in the background and restarted if anything unexpected happens.

Of course, the examples above are just a start; you could build a lot more complex logic around them; you could introduce more conditions by which the pending orders should be processed or not; you could add other useful options and arguments; and so on.

All in all, I hope this article helped you get a better understanding of Artisan commands that are run with the help of the Supervisor.

Enjoyed the article? Consider subscribing to my newsletter for future updates.

Originally published at geoligard.com.

EmailOctopus SDKs for PHP and Laravel

Goran Popović — Tue, 05 Mar 2024 00:28:41 +0000

When I wanted to start a newsletter and send regular updates to the subscribers of my blog, and since I didn't have that much experience with sending email campaigns, I needed a service that is simple to use, easy to integrate, has a good reputation, and has transparent and affordable pricing plans (possibly with a free plan with essential options to try things out and get started).

I went through some usual (and some less usual) suspects like Mailchimp, MailerLite, ConvertKit, Brevo, Campaign Monitor, and so on. But none of those really clicked for me at first glance, they were either too advanced and with too many options for my needs, the prices were too steep, or some of their free and starter plans were too restrictive.

That's when I discovered EmailOctopus. I found it to be the most appropriate email marketing platform for my current needs. I really like the simplicity of their dashboard and the UI. They have a well-maintained and informative knowledge base where I was able to find anything that was possibly unclear to me. Later on, I discovered that their support is also pretty responsive. They have a very decent API as well, which is easy to use, and they offer a really generous free plan to get you started.

They achieve their affordable pricing by focusing on a single service—providing you with a way to send marketing emails. So, for example, that means that they currently don't offer an option to use a SMTP connection to set up transactional emails. All of the emails you plan on sending must be created and sent through their dashboard.

This is by no means a sponsored article, I'm speaking from my own experience and related to my particular use case. Your situation might be completely different, and you are free to stick to any service that suits your needs best.

That being said, EmailOctopus is by no means perfect; there are improvements that could be made (i.e., IDs of different resources needed for the API could be more prominent), but I found it to be near-perfect in my scenario.

Anyway, as I browsed through different integrations and community-maintained libraries and SDKs, I noticed there isn't a PHP or Laravel-based API wrapper, so I thought it would be helpful to create a PHP API client that will allow others to easily communicate with the EmailOctopus's API in their PHP applications. Using the packages I created, you can easily subscribe or unsubscribe users to your newsletter, trigger automations, and view various data about your campaigns.

PHP SDK

If you want to interact with the API in a framework-agnostic way, you can install the Email Octopus SDK for PHP using Composer:

composer require goran-popovic/email-octopus-php

Next, in order to get started you would need to create an Email Octopus API key by following the instructions from their knowledge base.

You could store your API key in an .env file, like this for example:

EMAIL_OCTOPUS_API_KEY=YOUR_API_KEY

Then you can instantiate the client easily with one or two lines of code, like so:

$apiKey = getenv('EMAIL_OCTOPUS_API_KEY');

$client = EmailOctopus::client($apiKey);

The most usual use case will probably be to add/subscribe a contact to your list when someone fills out the newsletter form on your website. This can be easily done with a few lines of code by providing a list ID and the email address of the contact:

$client->lists()->createContact(
    '00000000-0000-0000-0000-000000000000',
    [
        'email_address' => 'goran.popovic@geoligard.com'
    ]
);

The ID of the list (00000000-0000-0000-0000-000000000000) can be found when editing the list in the settings tab, or in the URL in the dashboard:

IDs of other resources can also be found directly in the URL, like the automation ID, campaign ID, contact ID, and so on. So be sure to keep an eye on those.

If the contact is already subscribed to your list, or if a contact attempts to re-subscribe, the createContact API call will fail since that email already exists.

In order to handle that use case, you could check if the contact is already subscribed by trying to get the contact first, and if the contact exists, update it, and if it doesn't exist, create a new one:

$response = $client->lists()->getContact(
    '00000000-0000-0000-0000-000000000000',
    '00000000-0000-0000-0000-000000000000'
);

if(isset($response['error'])) { // contact doesn't exist
    // create contact
    $response = $client->lists()->createContact(
        '00000000-0000-0000-0000-000000000000',
        [
            'email_address' => 'goran.popovic@geoligard.com'
        ]
    );
} else {
    // update existing contact
    $client->lists()->updateContact(
        '00000000-0000-0000-0000-000000000000',
        md5('goran.popovic@geoligard.com'),
        [
            'status' => 'SUBSCRIBED'
        ]
    );
}

or you could just try to create a contact every time, and if that fails with a specific error code, then update it:

$response = $client->lists()->createContact(
    '00000000-0000-0000-0000-000000000000',
    [
        'email_address' => 'goran.popovic@geoligard.com'
    ]
);

// creating a contact failed
if(($response['error']['code'] ?? '') === 'MEMBER_EXISTS_WITH_EMAIL_ADDRESS') {
    // update existing contact
    $client->lists()->updateContact(
        '00000000-0000-0000-0000-000000000000',
        md5('goran.popovic@geoligard.com'),
        [
            'status' => 'SUBSCRIBED'
        ]
    );
}

Check out the repo and the docs for all of the remaining routes on GitHub.

Laravel SDK

Now, when it comes to the Email Octopus SDK for Laravel, as you may have guessed, it's basically another wrapper around the PHP version of the SDK, and all of the routes that are available in the PHP SDK are also available in the Laravel one. The Laravel package will allow you to easily interact with the API Client through the use of Facades.

First, we should install the package:

composer require goran-popovic/email-octopus-laravel

Please note that if you are using the Laravel SDK, you don't need to install the PHP SDK separately, since it is already included as a dependency for the Laravel package.

Now that we have installed the package, you can optionally publish the config files with this command:

php artisan vendor:publish --tag="email-octopus-config"

Like I mentioned already in the previous section, make sure to get your Email Octopus API key and add it to your .env file:

EMAIL_OCTOPUS_API_KEY=YOUR_API_KEY

Now, just just need to use the Facade in your file:

use GoranPopovic\EmailOctopus\Facades\EmailOctopus;

and you can perform the same operations as with the PHP SDK through the Facade, like so:

EmailOctopus::lists()->createContact(
    '00000000-0000-0000-0000-000000000000', 
    [
        'email_address' => 'goran.popovic@geoligard.com'
    ]
);

Check out the repo of the Laravel SDK for further instructions and details.

Conclusion

As I already mentioned, EmailOctopus has worked well for me so far, and I'm pretty satisfied with their service. If you ever decide to try them out for yourself, I hope both SDKs will prove to be useful assets when interacting with the EmailOctopus's API from your PHP applications.

For any bugs and improvements, feel free to create a pull request or open an issue on GitHub.

Enjoyed the article? Consider subscribing to my newsletter for future updates.

Originally published at geoligard.com.

Send, validate, and store Base64 files with Laravel

Goran Popović — Tue, 05 Mar 2024 00:25:35 +0000

Laravel makes it easy to send and upload files, at least when it comes to handling binary files. You would typically send binary files using an HTML form with a multipart/form-data encoding type. Inside your controller, you can simply get the file like this: $request->file('image') and save it on the disk. The file you receive returns an instance of the Illuminate\Http\UploadedFile class, which provides you with a lot of handy methods to manipulate the received file further. Pretty easy and straightforward, right?

But what if you want to send and receive files with JSON requests? Things get a bit tricky there since JSON requests can't transport binary data. You would have to convert your file to a Base64 string and then process it within your application to extract the necessary data. Let's see how we can do that.

Converting the image to Base64

First, let's see how we can convert an image of our choosing to a Base64 string. This can be of course done programmatically, but for simplicity, we are just going to upload a simple PNG image on a Base64 Guru website (you can, of course, use any other), and save the output for later use.

Here is an example of what that might look like:

Postman example

Now, before we proceed, let's see a complete example of that kind of request in Postman. So, in short, we will be sending a raw JSON POST request with a single image param, and in return, we will just get the URL of the newly stored file.

That might look something like this:

Initial setup

Ok, we know what to expect. Let's create a controller and a route to handle the request.

php artisan make:controller Base64Controller

// api.php

use App\Http\Controllers\Base64Controller;

Route::post('base64', [Base64Controller::class, 'index']);

So far, so good. Our base64 route will target the index method inside of the Base64Controller. Next, we will add some basic code to handle the JSON request in the index method.

// Base64Controller.php

namespace App\Http\Controllers;

use Illuminate\Http\File;
use Illuminate\Http\UploadedFile;
use Illuminate\Support\Arr;
use Illuminate\Support\Facades\Storage;
use Illuminate\Support\Facades\Validator;

class Base64Controller extends Controller
{
    public function index()
    {
        if (request()->isJson() && !empty(request()->input('image'))) {
            $base64Image = request()->input('image');

            if (!$tmpFileObject = $this->validateBase64($base64Image, ['png', 'jpg', 'jpeg', 'gif'])) {
                return response()->json([
                    'error' => 'Invalid image format.'
                ], 415);
            }

            $storedFilePath = $this->storeFile($tmpFileObject);

            if(!$storedFilePath) {
                return response()->json([
                    'error' => 'Something went wrong, the file was not stored.'
                ], 500);
            }

            return response()->json([
                'image_url' => url(Storage::url($storedFilePath)),
            ]);
        }

        return response()->json([
            'error' => 'Invalid request.'
        ], 400);
    }

We are first checking if we are dealing with a JSON request and if the image parameter is not empty. We then validate and upload the image. In the end, we return the URL of the newly uploaded file. Simple enough, right? You may have noticed that we have defined two helper functions, validateBase64 and storeFile that are validating and storing the file for us. Time to define them.

Helper functions

The first function (validateBase64) will just check if the image param is a Base64 representation of an image. It will accept a Base64 string and an array of allowed mime types. If the validation doesn't fail, a temporary file object will be returned. The function is mostly based on this Stack Overflow answer.

// Base64Controller.php

/**
 * Validate base64 content.
 *
 * @see https://stackoverflow.com/a/52914093
 */
private function validateBase64(string $base64data, array $allowedMimeTypes)
{
    // strip out data URI scheme information (see RFC 2397)
    if (str_contains($base64data, ';base64')) {
        list(, $base64data) = explode(';', $base64data);
        list(, $base64data) = explode(',', $base64data);
    }

    // strict mode filters for non-base64 alphabet characters
    if (base64_decode($base64data, true) === false) {
        return false;
    }

    // decoding and then re-encoding should not change the data
    if (base64_encode(base64_decode($base64data)) !== $base64data) {
        return false;
    }

    $fileBinaryData = base64_decode($base64data);

    // temporarily store the decoded data on the filesystem to be able to use it later on
    $tmpFileName = tempnam(sys_get_temp_dir(), 'medialibrary');
    file_put_contents($tmpFileName, $fileBinaryData);

    $tmpFileObject = new File($tmpFileName);

    // guard against invalid mime types
    $allowedMimeTypes = Arr::flatten($allowedMimeTypes);

    // if there are no allowed mime types, then any type should be ok
    if (empty($allowedMimeTypes)) {
        return $tmpFileObject;
    }

    // Check the mime types
    $validation = Validator::make(
        ['file' => $tmpFileObject],
        ['file' => 'mimes:' . implode(',', $allowedMimeTypes)]
    );

    if($validation->fails()) {
        return false;
    }

    return $tmpFileObject;
}

Great, now let's define the second helper function that will process the temporary file object that was returned from the previous function and upload the file.

// Base64Controller.php

/**
 * Store the temporary file object
 */
private function storeFile(File $tmpFileObject)
{
    $tmpFileObjectPathName = $tmpFileObject->getPathname();

    $file = new UploadedFile(
        $tmpFileObjectPathName,
        $tmpFileObject->getFilename(),
        $tmpFileObject->getMimeType(),
        0,
        true
    );

    $storedFile = $file->store('images/base64', ['disk' => 'public']);

    unlink($tmpFileObjectPathName); // delete temp file

    return $storedFile;
}

And just like that, we are done. If you would like to copy the whole code from Base64Controller.php head out to Gist.

Conclusion

Today we made a few great functions that would allow us to accept, validate, and store Base64 encoded files. In our example, we were validating images, but you can use these functions for other types of files as well, like .txt, .pdf, and so on. Also, for simplicity, all of the code was added to the same controller, but you could also move these functions to your custom helper function file, or create a trait, and then easily reuse them whenever you need to process a Base64 file.

Enjoyed the article? Consider subscribing to my newsletter for future updates.

Originally published at geoligard.com.

Interact with Docker containers without leaving PhpStorm

Goran Popović — Tue, 05 Mar 2024 00:19:24 +0000

In the previous article, I wrote about a particular setup you can use to configure Docker on WSL through SSH for performance boosts and the ability to keep using your native Windows apps without having to move them to WSL: Docker on WSL with PhpStorm - Best of both worlds.

In this article, we are going to see how we can use a PHP CLI interpreter from our Docker compose file and, finally, how we can interact with containers within PhpStorm. One thing to note is that I'm using Windows 10 and Docker Desktop, which is integrated with WSL, and on WSL, I'm running my project with Laravel Sail, but general guidelines from this post can be applied to any OS.

Requirements

First things first, in order for the following setup to work, make sure that the Docker and PHP Docker plugins are enabled in PhpStorm. These plugins are bundled and enabled by default, but if you disabled them for any reason, now would be a good time to re-enable them. Also, make sure that your Docker containers are up and running.

Setting up the CLI interpreter

Now, inside PhpStorm, go to File > Settings > PHP and add a new CLI interpreter by clicking on the ellipsis (...):

To configure the CLI interpreter from the Docker compose file, click the plus icon to add a new interpreter, select From Docker, Vagrant, VM, WSL, Remote... and go to the Docker Compose tab:

Setting up a Docker server

While in that tab, we are going to create a new Docker server configuration in another modal. Click on the New... button, add a server name, and choose a connection.

There are several connections to choose from, and depending on your OS, for the first option, you might get something like Docker for Windows, Docker for Mac, or Unix socket (for Linux). In this example, I'm going to use WSL, but if you have another setup or, for some reason, WSL integration doesn't work for you in the end, remember to return to this modal (I'll explain where to find it later on) and change the connection. Docker for Windows and SSH (you can refer to the previous article on how to setup an SSH connection in PhpStorm) options worked well for me in some other cases. Here is what that setup might look like in the end:

After you save all of the settings in the Docker server connection modal, we are back in the Docker compose tab of the CLI interpreter.

What is left in our current modal is to select the local docker-compose.yml file, which is in my case in the root of my project, and select a service/container that is running PHP, which is laravel.test by default when using Laravel Sail. Save all of the settings, and you should be good to go.

The Services tab should open automatically, and there you can connect to the Docker and, for example, access the PHP container and interact with it:

Troubleshooting

If you can't connect to Docker containers, or the PHP CLI interpreter is telling you it can't find the PHP executable, go back to Docker server settings (File > Settings > Build, Execution, Deployment > Deployment > Docker) and try using another connection, like SSH or Docker for Windows/Mac/Unix socket:

Conclusion

We made it! We are able to setup PhpStorm integration with Docker to easily start and stop Docker containers and access their terminals directly from the services tab inside PhpStorm. Also, this setup allowed us to use the PHP from our Docker container as our project's PHP CLI interpreter. Pretty neat!

Enjoyed the article? Consider subscribing to my newsletter for future updates.

Originally published at geoligard.com.

Docker on WSL with PhpStorm - Best of both worlds

Goran Popović — Tue, 05 Mar 2024 00:11:52 +0000

Most of you are aware that using Docker locally on Windows with Hyper-V enabled can be really slow for most Laravel or any other type of project. Sure, that kind of setup is much simpler; your project files are on your hard drive, and you are running Docker and any additional tools that your project depends on natively inside your Windows OS. Hey, I've been using Docker that way for a while and actually got used to 5-8 second page load times. I know, that's pretty bad. Your project and load times might not be as big, but they could still be improved.

Once, I tried running my projects inside WSL, but that introduced other issues, the main one being that my files were taking too long to be indexed both by Git and PhpStorm. So for the files to be indexed properly, I would have had to install Git, Sourcetree, and possibly PhpStorm inside WSL. That seemed like too much hassle, and I would have needed a decent alternative to Sourcetree since it isn't available for Linux systems.

So I gave up for a while. Recently, those load times were starting to get bigger and bigger from time to time, so I decided to search for alternatives again to improve performance. Obviously, I didn't want to give up on Docker since it provides me with an environment that is the closest to the setup on the server we've been using. While XAMPP, Laragon, or WAMP might be good alternatives for certain types of projects, I started digging deeper into using Docker with WSL. So I came across this article. The author suggested using PhpStorm's automatic deployment feature to sync files from Windows's filesystem to the ones on WSL through SSH. At first, that setup seemed a bit over the top, since an alternative might have been to use the built-in remote interpreter of PHPStorm to directly access WSL's filesystem (\$wsl), but when I tried it, that proved to be slow as well, and it didn't resolve my Sourcetree issue, so I decided to give it a go.

So, while you may refer to the article above for a summary, I'll describe a bit more in depth the steps I took to perform that kind of setup, what modifications I made, and what problems you might expect.

Initial setup

I've been using Windows 10 with 16GB of RAM, Docker for Windows v4.15.0, and PhpStorm v2023, but this kind of setup should work on Windows 11 and other newer versions of Docker that support WSL integration. In the final implementation, I was able to reduce the page load times from 5-8s to 200-300ms, which was a significant improvement. At the same time, I eliminated any issues with the performance of my other tools, like PhpStorm and Sourcetree. But this approach does come with some caveats, which we will explore a bit later.

Before we start, please note that this setup requires you to use PhpStorm as your IDE or a similar tool from JetBrains. Other tools might have similar functionalities you can use, but they won't be addressed in this article.

Installing WSL and Docker setup

The first step is to install WSL2 and set up Docker to run inside it. If you don't have WSL2 installed already, you can follow the instructions from Microsoft's website. On that link, you can also read about additional helpful commands.

The most important things to note here are that you can install WSL by running wsl --install or update an existing installation by running wsl --update. Currently, the latest version is Ubuntu 22.04.2 LTS. Use wsl -l -v to check your WSL version, and you should set the default WSL version to WSL 2 with wsl --set-default-version 2. When typing just 'wsl', you should be able to access the distribution, and you can shut it down with wsl --shutdown. You will be asked to create a username and password when you launch Ubuntu for the first time; make sure to save them as we are going to use them later on.

After WSL is installed, restart your PC, finish the installation, then run Docker, go to Settings > General, and enable the Use the WSL 2 based engine option. Next, go to resources and enable integration for your distribution like so:

Resources for the WSL and Docker are managed through the .wslconfig file. More about that here. What you should do is create the .wslconfig file in your text editor and add these values:

[wsl2]
memory=4GB
processors=3
localhostForwarding=true

and paste the file inside the C:\Users\<UserName> folder. You can adjust the memory and processor variables to fit your needs. For the changes from the file to be acknowledged you need to restart WSL by running wsl --shutdown and running wsl again.

Note: After these actions, Windows might act up and freeze all running programs. I am not yet sure why this is happening, but if that happens, restarting your PC should resolve the issue. Or you could just restart your PC right away, just in case, after you finish restarting WSL.

Install Windows Terminal from the Microsoft Store, it will allow you to easily access Ubuntu's terminal inside WSL.

Installing SSH

The next step is to install SSH inside Ubuntu. Inside the Ubuntu terminal, run these commands to install the SSH server:

sudo apt update
sudo apt install openssh-server

Check if SSH is running with:

sudo systemctl status ssh

Then run this command to allow connections to the SSH through the firewall:

sudo ufw allow ssh

Find your IP address with:

ip a

Save the address, you will use your IP address in the next step.

Make a folder that will hold your project in Ubuntu in /home/<username> with:

mkdir folder-name

That will be the destination folder in the next step to which the files will be copied from Windows's filesystem.

Connecting everything through PhpStorm

We will now connect PhpStorm and our Windows project files with Ubuntu through SSH and basically copy any project files from Windows to Ubuntu any time a file is changed. Before we start, make sure that you have your IP address from the previous step and your Ubuntu username and password ready. Open PhpStorm to create a new deployment and SSH configuration.

First, go to File > Settings > Build, Execution, Deployment > Deployment. Click on the plus icon (+) to add a new server, name your server, and choose SFTP as the connection type. Next click on the three dots (...) to add a new SSH configuration. In the newly opened modal, enter the Host, which is the IP address you saved earlier, set the auth type to Password, and enter your Ubuntu username and password. Test the connection and save the settings.

We are now back in the Connection tab of the Deployment modal. The only thing left to add in that tab is Root path and it should point to the location of your project inside WSL, for example: /home/farscape/blog. Now switch to the Mappings tab. The local path should point to the location of your project on Windows's filesystem, for example: C:\blog. Deployment and Web path can point to the root folder of the Ubuntu project, like so /.

Afterwards, go to Deployment > Options. There, find the Upload changed files automatically to the default server and set it to Always. You can also tick the Delete remote files when local are deleted checkbox.

Since this setup includes quite a few steps, here are some screenshots of what everything might look like in the end:

Now, right-click on the root folder of your project and upload all of the current project files to Ubuntu:

That might take some time the first time, but later on, the files will be automatically uploaded and synced. You can enable the Remote host window in PhpStorm by going to Tools > Deployment > Browse remote host.

In the end, access your project's folder within the Ubuntu terminal and build the Docker project as you usually would with the docker-compose build and docker-compose up commands. Alternatively, if you are using Laravel Sail, just build and run your project with the corresponding commands. Wait until the project is built and the containers are up. That's it. You should be able to access your app at the URL you usually would and connect to your DB with the same credentials as before. You can also start and stop containers from the Docker Desktop app. Only this time around, everything should work smoothly, and your page load times should be drastically improved.

By using this approach, we are getting the best of both worlds. This kind of setup allows us to use the advantages of Docker inside WSL without disrupting the usage of native Windows apps that are interacting with the codebase.

Caveats

Now about those caveats I mentioned. There are some issues that you should be aware of. For example, PhpStorm provides a one way connection that copies files automatically from your hard drive to the project located in WSL. So, if any files are changed inside WSL, they won't be automatically synced back to your main hard drive. Which in turn means that your version control tool won't pick up those new file changes.

So if you were to access your PHP container inside Docker and type:

php artisan make:model Test

That file would be created inside WSL only. Luckily, there is a solution, but it includes a bit of manual labor. If you right-click on any folder located on WSL inside PhpStorm, you can sync the files from WSL back to the main filesystem. You can also use options like Upload here or Download from here to upload or download files from entire folders on both sides of the connection.

From that same drop-down menu, you can also exclude folders you might not want synced.

When it comes to caveats, that's actually the main problem: from time to time, you will have to manually sync some of the files back and forth.

Conclusion

While this whole approach may seem a bit tedious in the beginning, once you familiarize yourself with the setup, make the necessary adjustments the first time, and experiment a bit, later on you will be able to configure each new project more quickly and with ease. Most importantly, you'll be able to enjoy the performance boost without having to move your native apps to WSL.

This method isn't ideal; you might think it's too troublesome to sync the files from time to time manually, it might be an overkill for your particular use case, and that's perfectly fine. On the other hand, it might be just right for you and your projects. For now, I accepted the good with the bad, its shortcomings don't actually bother me that much anymore, and I really enjoy the better page load times and being able to use my tools the same as before, without any issues.

Bonus step

Now that your setup is up and running, you might want to check out how you can interact with Docker containers without ever having to leave PhpStorm and how we can configure a PHP CLI interpreter using the Docker compose file: Interact with Docker containers without leaving PhpStorm.

Enjoyed the article? Consider subscribing to my newsletter for future updates.

Originally published at geoligard.com.

Using Laravel to interact with OpenAI's Assistants API (with Vision)

Goran Popović — Tue, 13 Feb 2024 23:45:07 +0000

A couple of months ago Open AI released their Assistant API which is at the time of writing this article still in beta. In short, Assistants are a new and (hopefully) better way of utilizing OpenAI models. Before, when using the Chat Completions API, you had to keep a history of each message that was exchanged between the user and model, and then send that whole history each time back to the API, because Chat Completions API isn't stateful.

Enter Assistants. Assistants are stateful and will keep a history for you, so you can easily send just the last user's message, and receive back an answer. Besides Function Calling, they also include cool tools like Code Interpreter and Knowledge Retrieval.

Getting Started

Now, to interact with OpenAI API through Laravel we are going to use an already popular package developed by Nuno Maduro and Sandro Gehri: https://github.com/openai-php/client and a Laravel specific wrapper of that package: https://github.com/openai-php/laravel.

First, simply require the Laravel wrapper package:

composer require openai-php/laravel

That will install the required dependencies as well, including the OpenAI PHP Client package. After that execute the install command:

php artisan openai:install

Next, you should add your OpenAI API key inside your .env file:

OPENAI_API_KEY=sk-...
OPENAI_ORGANIZATION=org-...

Find or create your API key in the API keys section:

Now we are ready to use the package to interact with the API. But, before that, let's create an Assistant. Bare in mind that Assistant can also be created through API, but for simplicity in speed we are going to create an assistant in OpenAI's Playgound. Head to: https://platform.openai.com/playground and create an Assistant. Give him any name you like, enter any instructions you may have, select a model and you may or may not enable additional tools. When you do save your changes, make sure to copy the assistant's ID, we are going to need it later.

Ok, now, imagine we are developing an app where we are in charge of the backend. User will enter a chat message on the frontend, typically some kind of a question for our Assistant to answer, frontend will then use our app's internal API, and send us the message the user entered. On the backend side, we are going to make a request to the Assistant and await his response. When we get the response, we are going to return it to the frontend to display it to the user. This article will just focus on the backend side of the process. I mentioned that in theory some frontend would be calling our backend API, but we could use Postman just as well to simulate that process, which we will actually do later.

Let's create just one route and an AssistantController.php in which we will perform our logic.

php artisan make:controller AssistantController

// api.php

Route::post('/assistant', [AssistantController::class, 'generateAssistantsResponse']);

Creating and running threads

Before we create our main generateAssistantsResponse function, let's create a few helper functions. The way the Assistant's flow works, we would have to create a thread using our Assistant's ID, which is a type of holder for any messages exchanged between a user and an assistant, then we need to submit an actual user's message, and trigger a run. When the run finishes successfuly we should get our response back.

// AssistantController.php

use OpenAI\Laravel\Facades\OpenAI;

class AssistantController extends Controller
{
    private function submitMessage($assistantId, $threadId, $userMessage)
    {
        $message = OpenAI::threads()->messages()->create($threadId, [
            'role' => 'user',
            'content' => $userMessage,
        ]);

        $run = OpenAI::threads()->runs()->create(
            threadId: $threadId,
            parameters: [
                'assistant_id' => $assistantId,
            ],
        );

        return [
            $message,
            $run
        ];
    }

    private function createThreadAndRun($assistantId, $userMessage) 
    {
        $thread = OpenAI::threads()->create([]);

        [$message, $run] = $this->submitMessage($assistantId, $thread->id, $userMessage);

        return [
            $thread,
            $message,
            $run
        ];
    }

    private function waitOnRun($run, $threadId)
    {
        while ($run->status == "queued" || $run->status == "in_progress")
        {
            $run = OpenAI::threads()->runs()->retrieve(
                threadId: $threadId,
                runId: $run->id,
            );

            sleep(1);
        }

        return $run;
    }

    private function getMessages($threadId, $order = 'asc', $messageId = null)
    {
        $params = [
            'order' => $order,
            'limit' => 10
        ];

        if($messageId) {
            $params['after'] = $messageId;
        }

        return OpenAI::threads()->messages()->list($threadId, $params);
    }
}

In short, we will use the createThreadAndRun function to create a thread, submit a message to the thread, and create a run. There is an equivalent createAndRun function in the package we are using, but this function we created might help you initially to better understand what is going on. We will then use waitOnRun function to wait for the run to complete and finally we can use getMessages function to get the response from the assistant.

Merging the pieces together

Now, we can create our main function generateAssistantsResponse as defined in the assistant route we created previously.

public function generateAssistantsResponse(Request $request)
{
    // hard coded assistant id
    $assistantId = 'asst_someId'; 
    $userMessage = $request->message;

    // create new thread and run it
    [$thread, $message, $run] = $this->createThreadAndRun($assistantId, $userMessage); 

    // wait for the run to finish
    $run = $this->waitOnRun($run, $thread->id); 

    if($run->status == 'completed') {
        // get the latest messages after user's message
        $messages = $this->getMessages($run->threadId, 'asc', $message->id); 

        $messagesData = $messages->data;

        if (!empty($messagesData)) {
            $messagesCount = count($messagesData);
            $assistantResponseMessage = '';

            // check if assistant sent more than 1 message
            if ($messagesCount > 1) { 
                foreach ($messagesData as $message) {
                    // concatenate multiple messages
                    $assistantResponseMessage .= $message->content[0]->text->value . "\n\n"; 
                }

                // remove the last new line
                $assistantResponseMessage = rtrim($assistantResponseMessage); 
            } else {
                // take the first message
                $assistantResponseMessage = $messagesData[0]->content[0]->text->value;
            }

            return response()->json([
                "assistant_response" => $assistantResponseMessage,
            ]);
        } else {
            \Log::error('Something went wrong; assistant didn\'t respond');
        }
    } else {
        \Log::error('Something went wrong; assistant run wasn\'t completed successfully');
    }
}

So, we take the user's message from the request, and use that data along with our assistant's ID to generate a new thread, submit a message, and start the run. From the createThreadAndRun function we are getting all of the necessary data back to us which we can use further in the process. After the run has started we will periodically check if the run has been completed.

After a few seconds the status of the run will be set to completed. As soon as that happens, we are getting the latest messages after the one the user sent. Since (per OpenAI docs) assistant can sometimes send more than one message (never happened to me, but just in case) we are checking the number of messages sent and concatenating them into a single response for simplicity. Otherwise, if there is just one message, we just get the first message. In the end the assistant's message is returned in a JSON response.

Using assistant functions to send images to the Vision API

Note: before we start using the Vision API, please bare in mind that while you can use the Chat and Assistants API with GPT-3 models, you will need access to GPT-4 models to use Vision, and you will need to spend $1 in order to unlock access to GPT-4 models: https://help.openai.com/en/articles/7102672-how-can-i-access-gpt-4.

Ok, we are ready to talk about assistant functions and how we can utilize them to pass different data (3rd party or from our own app) to the assistant. With Vision API you can for example allow your user to upload an image, and then the GPT-4 model will be able to take in that image and answer different questions about it. Now, the thing is that Vision isn't yet available for Assistants API. If you try to upload an image and send it to the assistant it won't be able to describe the contents of that image. But there is a workaround.

Enter function calling. Using assistant functions, we are able to tell the assistant to call a specific function which will in turn call another API - Chat Completions API: https://platform.openai.com/docs/api-reference/chat/create which does have Vision available. Later on we will feed that data from the Chat API to our assistant so he can respond accordingly.

Back in our AssistantController.php, let's start with another helper function. We will create a processRunFunctions method that checks if our assistant run requires any action to be performed, in this case if any function should be called. If the assistant decides that the describe_image function should be called we will fire up the Chat API and ask it to provide us with the image description based on the message and the image user has already provided. Then we will submit the Vision related data back to the assistant and wait for that run to complete. Bare in mind that we are increasing the default value for max_tokens so the response is not cut off.

private function processRunFunctions($run)
{
    // check if the run requires any action
    while ($run->status == 'requires_action' && $run->requiredAction->type == 'submit_tool_outputs')
    {
        // Extract tool calls
        // multiple calls possible
        $toolCalls = $run->requiredAction->submitToolOutputs->toolCalls; 
        $toolOutputs = [];

        foreach ($toolCalls as $toolCall) {
            $name = $toolCall->function->name;
            $arguments = json_decode($toolCall->function->arguments);

            if ($name == 'describe_image') {
                $visionResponse = OpenAI::chat()->create([
                    'model' => 'gpt-4-vision-preview',
                    'messages' => [
                        [
                            'role' => 'user',
                            'content' => [
                                [
                                    "type" => "text",
                                    "text" => $arguments?->user_message
                                ],
                                [
                                    "type" => "image_url",
                                    "image_url" => [
                                        "url" => $arguments?->image,
                                    ],
                                ],
                            ]
                        ],
                    ],
                    'max_tokens' => 2048
                ]);

                // you get 1 choice by default
                $toolOutputs[] = [
                    'tool_call_id' => $toolCall->id,
                    'output' => $visionResponse?->choices[0]?->message?->content
                ];
            }
        }

        $run = OpenAI::threads()->runs()->submitToolOutputs(
            threadId: $run->threadId,
            runId: $run->id,
            parameters: [
                'tool_outputs' => $toolOutputs,
            ]
        );

        $run = $this->waitOnRun($run, $run->threadId);
    }

    return $run;
}

We can now amend our main method generateAssistantsResponse to process the image user uploaded, and process any functions the assistant may call. I won't get into detail on how to validate and save the image user provided, just bare in mind that the image can be sent as an URL or base64 to the Vision, but an URL is preferred.

public function generateAssistantsResponse(Request $request)
{
    $assistantId = 'asst_someId';
    $userMessage = $request->message;

    // check if user uploaded a file
    if($request->file('image')) {
        // validate image

        // store the image and get the url - url hard coded for this example
        $imageURL = 'https://images.unsplash.com/photo-1575936123452-b67c3203c357';

        // concatenate the URL to the message to simplify things
        $userMessage = $userMessage . ' ' . $imageURL;
    }

    [$thread, $message, $run] = $this->createThreadAndRun($assistantId, $userMessage);

    $run = $this->waitOnRun($run, $thread->id);

    // check if any assistant functions should be processed
    $run = $this->processRunFunctions($run);

    if($run->status == 'completed') {
        $messages = $this->getMessages($run->threadId, 'asc', $message->id);

The last thing to do is to add a function definition. You can add a function definition through the API, but again, since it is more straightforward for this example we will add the function definition through Playground. Here is the definition we will use:

{
  "name": "describe_image",
  "description": "Describe an image user uploaded, understand the art style, and use it as an inspiration for constructing an appropriate prompt that will be later used to generate a skybox.",
  "parameters": {
    "type": "object",
    "properties": {
      "user_message": {
        "type": "string",
        "description": "Message the user sent along with the image, without the URL itself"
      },
      "image": {
        "type": "string",
        "description": "URL of the image user provided"
      }
    },
    "required": [
      "user_message",
      "image"
    ]
  }
}

And here is how that might look like in the Playground.

And here is how the whole API request/response flow might look like in Postman.

In case you want to copy the whole code from AssistantController.php head out to Gist.

Conclusion

In conclusion, bare in mind that this is just a basic example to showcase some of the possibilities, and that the code can and should be improved in many ways. For example, you probably shouldn't hard code your Assistant ID, instead you could keep it in your database model. Currently the only way to check if a run has been completed is to periodically check if that has happened, which is far from ideal, but in the documentation is it mentioned that will change in the future: https://platform.openai.com/docs/assistants/how-it-works/limitations. Instead of waiting for the runs to complete in a single request you could dispatch parts of code to a Laravel Job and run it asynchronously. After a Job is completed it could broadcast an event through Websockets and send a notification to the frontend with the response from the assistant, or you could use Webhooks to send results to other users.

Also, as I already mentioned the Assistants API is in beta and it will probably change and evolve in the coming weeks or months.

That's it for this article, hope it provided you with a good starting point for using the Assistants API.

Happy building!

Enjoyed the article? Consider subscribing to my newsletter for future updates.

Originally published at geoligard.com.