Demo image sallon code

Wat is Saloon?

Saloon biedt een vloeiende, objectgeoriënteerde wrapper om uw volgende API-integratie of PHP SDK te bouwen. Het maakt het delen van API-requests in je applicatie een fluitje van een cent. Je hoeft geen HTTP-client te configureren, dus je kan heel snel beginnen met het sturen van requests.

Als je request faking nodig hebt voor jouw tests, heeft Saloon dit out of the box naast vele andere nuttige tools zoals OAuth2 boilerplate en caching. Als je Laravel gebruikt, is er ook een speciale Laravel package met artisan console-commands om je te helpen nog sneller tot een goed resultaat te komen.

SDK Toerisme Vlaanderen

Als proof of concept hebben we de API van Toerisme Vlaanderen genomen. Deze API heeft 400+ publiek toegankelijke endpoints waar je verschillende soorten data hebt zoals: Vlaamse Logies, Stadsrondleidingen, ...

De API waar in dit voorbeeld over gesproken zal worden is de API van Vlaamse stadslogies.

File structuur saloon template

Saloon heeft zelf een template dat ze voorzien voor SDK's. Hier voorzien ze de nodige voorbeelden zodat we vanuit een overzichtelijke boilerplate kunnen starten.

Als we deze template van dichtbij bestuderen zien we dat er vanalles in steekt zoals:

  • Auth
  • Data
  • Exceptions
  • Requests
  • Collections
  • Responses

Wat we in de POC gaan doen is een wrapper schrijven die de mogelijkheid heeft om met query parameters de Vlaamse logies op te halen per stad of van heel Vlaanderen.

Console configuratie template Saloon

Stap 1 - Personaliseer de template

De template is voorzien van een configure PHP script waarmee we onze template kunnen gaan renamen naar ons doeleinde. Dit script zal eenmaal je door alle stappen bent gelopen van het script alle nodige files renamen naar jouw ingestelde naam waarodoor er geen manueel import / configuratie werk meer nodig zal zijn. Eveneens zal het de composer install doorlopen en resterende intallaties!

 

In je root map run je dit commando:

php configure.php

 

Stap 2 - Setup van de SDK

We beginnen bij de DemoSaloonSdk.php file. Dit is de centrale file van je SDK. Hier worden de basis parameters ingevuld zoals de base_url. Deze gaat ook als connector dienen voor jouw requests die te maklen zullen hebben met de Toerisme Vlaanderen API.

Wat we als eerste doen bij deze API is de trait/plugin AcceptsJson usen. Dit is een plugin die voorzien is door Saloon die er voor zorgt dat je op deze connector altijd een JSON header mee stuurt.

Hierna vullen we onze baseUrl in. In dit geval is dat

https://opendata.visitflanders.org

 

Als we wat verder kijken zien we dat er een $requests array is. Wat we hieron kunnen doen is onze collecties definiëren zodat we deze achteraf via een magic method kunnen oproepen en onze request kunnen uitvoeren.

Onze magic method gaan we lodgings noemen en hier hangen we dan de LodgingsCollection aan als volgt:

    /**
     * The requests/services on the DemoSaloonSdk.
     *
     * @var array
     * @method LodgingsCollection lodgings
     */
    protected array $requests = [
        'lodgings' => LodgingsCollection::class,
    ];

Voor de rest in de file is alles eigenlijk standaard geconfigureerd. Mocht je een defaultConfig willen toevoegen of defaultHeaders kan dat onderaan in de file.

Stap 3 - Collecties

Nu onze connector is opgezet, moeten we de collectie opmaken die we in $requests hebben ingevoerd. Aangezien dat er maar 1 endpoint is op de logies API kiezen we ervoor om in de file een functie te maken all(). Omdat deze alles gaat ophalen van de API.

Als je in de Requests map gaat zien zal je zien dat er een ExampleCollection.php aanwezig is. We gaan deze renamen deze naar LodgingsCollection.php.

Als wer hierin dan de afgesproken all() functie maken en de nodige query parameters aan mee sturen zodat we deze kunnen gebruiken in de request dan kunnen we de request beginnen opbouwen.

 /**
     * @throws ReflectionException
     * @throws GuzzleException
     * @throws SaloonException
     */

    public function all(?string $city = null, int $limit = -1, int $page = -1) : array
    {
        $request = $this->connector->request(new GetLodgingsRequest($city, $limit, $page));
        return $request->send()->json();
    }

 

Stap 4 - Request

Eerst en vooral renamen we de Example folder in Requests naar Lodgings. In Lodgings renamen we ook ineens de request dat we gaan gebruiken naar GetLodgingsRequest.php.

In de request file gaan we de volledige request opbouwen. Zie het een beetje als de body samenstellen.

In onze construct geven we de nodige waardes mee die we hebben meegegeven in de collectie:

    /**
     * Define constructor.
     *
     * @param string|null $city City you'd like to request lodgings from, leaving it empty will return all lodgings from Flanders.
     * @param int $limit Amount per page in pagination. -1 is the default (unlimited).
     * @param int $page current page in pagination. -1 is the default (disable pagination).
     */
    public function __construct(protected ?string $city, protected int $limit, protected int $page)
    {
        $this->city = $city;
        $this->limit = $limit;
        $this->page = $page;
    }

We definen ons endpoint:

/sector/accommodation/base_registry.json

Onze query parameters voegen we ook nog toe:

public function defaultQuery(): array
    {
        return [
            'city' => $this->city,
            'limit' => $this->limit,
            'page' => $this->page
        ];
    }

en dan zijn we klaar met de request!

Nu hebben we een basis collection waar we een request in kunnen aanroepen in onze Laravel/PHP applicatie.

Gebruik in Laravel

Als we onze package installeren op een test project zullen we onze request kunnen aanroepen als volgt:

        $toerismeVlaanderenSdk = new DemoSaloonSdk();
        /* Specifiek voor Antwerpen zonder paginatie */
        $lodgings = $toerismeVlaanderenSdk->lodgings()->all('Antwerpen');

        /* Alle logies in Antwerpen, per 10 gepagineerd op pagina 1*/
        $lodgings = $toerismeVlaanderenSdk->lodgings()->all('Antwerpen', 10, 1);

        /* Alle logies in Vlaanderen*/
        $lodgings = $toerismeVlaanderenSdk->lodgings()->all();

 

Conclusie

Nu kan je zien dat je op een relatief snelle manier een API kan packagen die je misschien in volgende projecten ook nog kan gebruiken! Saloon opent heel wat mogelijkheden voor zowel open-source als closed-source en kan er dus effectief voor zorgen dat de DX heel wat aangenamer wordt en de werksnelheid heel wat verhoogd achteraf.

Source code?

Bekijk het demo project

Auteur: Noah Gillard
PHP / Laravel Developer
Noah Gillard AI generated Face

More insights

Codana wint Digital Champ of the year award 2022

Codana is de winnaar van de FeWeb Digital Champ award 2022

Auteur: Joris De Groot
Strategic Director and Managing Partner
Joris De Groot
FeWeb Digital Champ award Codana

De ideale eerste werkplek

Ik ben Ward Vandevoort, 22 jaar en begin november 2021 ben ik gestart bij Codana als junior backend developer. Ontdek mijn verhaal bij Codana! 

Auteur: Ward Vandevoort
Developer
Ward Vandevoort
groepsfoto

Teambuilding met internationale collega's

Een zalige teambuilding in Antwerpen!

Auteur: Noah Gillard
PHP / Laravel Developer
Noah Gillard AI generated Face
groepsfoto codana burgerij

Het leven als React developer bij Codana: 1 jaar in dienst

“U kan bij ons aan de slag als React developer!”. Wow, zalig! Ik was natuurlijk super blij dit te horen! Maar, ik had nog nooit een lijn React geschreven.

Auteur: Thomas Timmermans
Frontend Developer
Thomas Timmermans
Ik na 1 jaar in dienst

Nova 4.0 is er!

De belangrijkste nieuwigheden uitgelicht.

Auteur: Noah Gillard
PHP / Laravel Developer
Noah Gillard AI generated Face
Thumbnail Blog Nova 4 Release Codana Styled

Laracon Online Winter 2022

Wat zijn de key take aways?

Author: Tom Van den Eynden
Web Architect | Coordinator
Tom Van den Eynden
Laracon winter 2022 Codana Banner