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 maken 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

Cross-platform applicaties met React Native

Nog nooit was het ontwikkelen van native mobiele applicaties zo toegankelijk als vandaag. Bij Codana doen we dit door gebruik te maken het React Native, een open-source framework dat werd ontwikkeld door Meta.

Auteur: Jinse Camps
Architect | Analyst
Jinse Camps
dev

Laracon EU 2024

Een fantastisch leerrijke ervaring om met een hoop Laravel gepassioneerde mensen te inspireren! Iets wat niet gemist kan worden en heel veel voeling geeft met de community. Wat een top evenement! Wie zien we volgende edities? šŸ˜®

Auteur: Noah Gillard
PHP / Laravel Developer
Noah Gillard AI generated Face
laracon codana persoon

Een efficiƫnt datamanagementsysteem voor toerisme

Een TDMS of Tourist Data Management System, is simpelweg een platform dat data uit verschillende bronnen ophaalt, intern al dan niet automatisch verwerkt en deze gegevens terug aanbiedt aan externe platformen.

Auteur: Tom Van den Eynden
Web Architect | Coordinator
Tom Van den Eynden
laptop

Systemen voor gegevensbeheer in toerisme

In dit artikel verkennen we wat een TDMS is, waarom het essentieel is voor de toerisme-industrie, en hoe technologieĆ«n zoals Laravel en ElasticSearch het verschil kunnen maken. 

Auteur: Tom Van den Eynden
Web Architect | Coordinator
Tom Van den Eynden
tdms

Beveiliging van Laravel 101

In deze blogpost gaan we dieper in op een aantal veelvoorkomende Laravel beveiligingsfouten.

Auteur: Robbe Reygel
PHP developer
laravel

Test Driven Development - toepassing op een project

TDD, of voluit Test Driven Development, is een aanpak van ontwikkeling waarbij we vertrekken van het schrijven van tests. 

Auteur: Sarah Jehin
PHP developer
Sarah Jehin
development