Saloon A PHP Package

Why This is Important?

Well, I'm working at sku.io and in there we have many sales-channels integration since it's an Inventory Management System. So, it makes sense that we are going to have many API integrations to download products,orders and shipping information etc.

So, I have got assigned this ticket to refactor the old pattern (in which we were using abstraction to manage the API integrations) to Saloon way. So, the one advantage anybody can see, it has documentation but when you create your own way to manage integration you'll have to create documentation or may be you'll modify it later so you'll have to maintain the documentation along the way. That's an awful situation in my point of view.

So, we decided to use it.

Why Saloon

We are using Laravel as backend so the saloon is ideal package here, because it comes with Laravel plugin. You can also use Artisan commands to make it's standard files.

It has built-in authentications, request hooks, middleware and caching. So, you don't need worry about them.

Let me give an example:

Let's take an example of walmart. In Walmart we use Token Authentication to authenticate the request. So, what would you do?

In your code you'll have to define a header with whatever token header is allowed. It doesn't sound to difficult right? So, why saloon is useful in this situation that you can define an Authenticator called "TokenAuthenticator('token header name' , token)".

This short of reasons, makes you use saloon.

Saloon is here

Features and Usage

Saloon has two main things in it. I would say things because they are important as they play the main role. Things means the short of actor. The Connector file and the Request file.

Whenever you create an authentication, you create an Integration folder in Http and then you create Connector in Integration and Request/** requests. So, for each single request you create a request file that will be dispatched through the connector.

Let me show some example:

ExampleApiConnector.php

namespace App\Integrations;

use Saloon\Http\Connector;
use Saloon\Http\Auth\BasicAuthenticator;

class ExampleApiConnector extends Connector
{
    protected string $baseUrl = 'https://api.example.com';

    public function defaultAuth(): ?BasicAuthenticator
    {
        return new BasicAuthenticator(config('services.example_api.client_id'), config('services.example_api.client_secret'));
    }

    protected function defaultHeaders(): array
    {
        return [
            'Accept' => 'application/json',
            'Authorization' => 'Bearer ' . $this->getAccessToken(),
        ];
    }

}

                
                Copy
            

And similarly a request will look like this

namespace App\Integrations\Requests;

use Saloon\Http\Request;
use Saloon\Enums\Method;

class GetOrdersRequest extends Request
{
    protected Method $method = Method::GET;
    protected string $endpoint = '/orders';

    public function __construct(private array $filters = [])
    {
    }

    protected function defaultQuery(): array
    {
        return $this->filters;
    }
}


                
                Copy
            

This is how a request method will look like in your Connector.

 public function getOrders(array $filters = []): OrderResponseDto
  {
    if (!isset($filters['lastModifiedStartDate'])) {
      $filters['lastModifiedStartDate'] = $this->orderRepo->getStartDateForNew();
    }

    $request = new GetOrdersRequest($filters);
    $response = $this->send($request);

    return OrderResponseDto::from($response->json());
  }

                
                Copy
            

You are also allowed to stabilize your structure using services, but rest depends on you how feel comfortable.

This is just a basic example of how you can use saloon. It's way large that this, but this is what I've used so far. I thought that it may will help someone to organize their API integrations.

Thanks for reading. ❤️ 

                
                Copy