Avec Laravel, les interactions avec les API sont un jeu d’enfant pour les développeurs web, qu’ils soient nouveaux ou expérimentés. Le client HTTP Larvel est construit au-dessus du client HTTP Guzzle de PHP pour offrir aux développeurs une expérience plus fluide lors des requêtes HTTP. Ses principales fonctionnalités sont l’authentification, le routage et le mappage objet-relationnel (ORM).

Cet article explore l’utilisation du client HTTP de Laravel pour effectuer des requêtes, déboguer les réponses, créer des middlewares et des macros, et plus encore.

Le client HTTP de Laravel fait le travail difficile à votre place pour les API

Guzzle est un client HTTP simple pour PHP. Il offre des fonctionnalités pour différentes requêtes de formulaire, y compris GET, POST, PUT, et DELETE, ainsi que des capacités de streaming et des requêtes multipartites. Le client HTTP Guzzle permet d’envoyer des requêtes synchrones et asynchrones au serveur. En outre, il est accompagné d’un middleware décent permettant de personnaliser le comportement du client.

Le client HTTP de Laravel est un wrapper construit sur Guzzle mais avec des fonctionnalités supplémentaires. Il prend en charge la relance des requêtes qui ont échoué et quelques fonctions d’aide pour les données JSON. La plupart des fonctionnalités des clients HTTP de Laravel sont similaires à celles de Guzzle.

Pré-requis

Dans les sections suivantes, vous en apprendrez plus sur le client HTTP de Laravel. Pour suivre, vous aurez besoin de :

  • Connaissances de base sur Laravel, PHP et les API
  • PHP et Composer installés
  • Postman

Comment faire des requêtes

Pour comprendre comment utiliser un client HTTP pour effectuer une requête, vous pouvez vous appuyer sur de nombreuses API hébergées, telles que ReqRes.

Commencez par importer le package HTTP inclus lors de la création de l’application. Dans le fichier App/Http/Controllers/UserController.php, ajoutez le code suivant, en commençant par l’instruction use au début du fichier et le reste du code dans la fonction index.

use Illuminate\Support\Facades\Http;
return Http::get("https://reqres.in/api/users?page=2");

Remarque : pour les cas d’utilisation complexes, vous pouvez également envoyer la requête avec des en-têtes en utilisant la méthode withHeaders.

Dans le même fichier, créez une nouvelle méthode post en utilisant le code ci-dessous :

function post()
{
    $response = Http::withHeaders([
        'Content-Type' => 'application/json',
    ])->post('https://reqres.in/api/users', [
        'name' => 'morpheus',
        'job' => 'leader',
    ]);
    return $response;
}

Ajoutez ensuite une route pour cette méthode dans le fichier routes/web.php :

Route::get('post',[UserController::class,'post']);

Maintenant, Postman peut être utilisé pour tester cette route. Ouvrez Postman et ajoutez http://127.0.0.1:8000/post comme URL, avec le type de requête GET. Une fois que vous aurez cliqué sur envoyer, vous verrez la réponse suivante :

Effectuer des requêtes à l'aide de Postman
Effectuer des requêtes à l’aide de Postman

Requêtes simultanées

Les requêtes parallèles améliorent considérablement les performances car vous pouvez récupérer plus de données dans le même laps de temps. Le client HTTP de Laravel permet d’effectuer des requêtes concurrentes en utilisant la méthode pool.

Dans App/Http/Controllers/UserController.php, ajoutez le code suivant :

use Illuminate\Http\Client\Pool;
function concurrent()
{
    $responses = Http::pool(fn (Pool $pool) => [
        $pool->get('https://reqres.in/api/users?page=2'),
        $pool->get('https://reqres.in/api/users/2'),
        $pool->get('https://reqres.in/api/users?page=2'),
    ]);

    return $responses[0]->ok() &&
        $responses[1]->ok() &&
        $responses[2]->ok();
}

Ensuite, ajoutez la route de support dans le fichier routes/web.php.

Route::get('concurrent',[UserController::class,'concurrent']);

Le navigateur donne la réponse suivante lorsque la route est visitée :

Requêtes simultanées
Requêtes simultanées

Macros de requête

Les macros de requête sont utiles pour interagir avec des chemins d’accès communs à l’API.

Pour créer la macro, vous devez la définir dans la méthode boot du fichier app/Http/Providers/AppServiceProvider.php en utilisant le code ci-dessous :

use Illuminate\Support\Facades\Http;
Http::macro('reqres', function () {
    return Http::baseUrl('https://reqres.in/api');
});

Remarque : assurez-vous d’ajouter l’instruction use au début du fichier.

Ensuite, utilisez la macro à l’intérieur de UserController en ajoutant le code suivant :

function macro()
{
    $response = Http::reqres()->get('/users?page=2');
    return $response;
}

Comme vous pouvez le constater, la macro étant déjà créée, il n’est pas nécessaire d’ajouter à nouveau l’URL complète.

Enfin, ajoutez une route dans le fichier routes/web.php en utilisant le code ci-dessous :

Route::get('macro',[UserController::class,'macro']);
Requête de macro
Requête de macro

Comment décoder les réponses

Pour décoder une réponse et vous assurer qu’une requête d’API a abouti, vous utilisez la méthode status incluse dans le client. Cette méthode récupère le code d’état envoyé par le serveur et l’affiche.

Pour tester cette méthode, remplacez le code macro précédent par le code ci-dessous dans le fichier App/Http/Controllers/UserController.php:

function macro()
{
    $response = Http::reqres()->get('/users?page=2');
    return $response->status();
}

Ici, le code d’état 200 signifie que la requête a abouti.

Réponse de décodage réussie
Réponse de décodage réussie

Comment tester les API JSON

Laravel dispose de plusieurs aides pour tester les API JSON et leurs réponses. Les fonctions d’aide comprennent json, getJson, postJson, putJson, patchJson, deleteJson, etc.

Pour mieux comprendre le test, créez un scénario de test pour la route de l’utilisateur GET. Lorsque vous démarrez l’application Laravel, l’exemple de test est déjà créé. Dans le fichier tests/Feature/ExampleTest.php, remplacez le code existant par ce qui suit :

<?php
namespace Tests\Feature;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;
class ExampleTest extends TestCase
{
    /**
     * A basic test example.
     *
     * @return void
     */
    public function test_example()
    {
        $response = $this->getJson('/users');

        $response->assertStatus(200);
    }
}

Le code ajouté récupère les données JSON sur la route de l’utilisateur et vérifie si le code d’état est 200 ou non.

Une fois le code de test ajouté, exécutez la commande suivante dans votre terminal pour lancer les tests :

./vendor/bin/phpunit

Une fois les tests terminés, vous verrez qu’il a exécuté deux tests, qui ont tous deux réussi.

Test des API JSON
Test des API JSON

De la même manière, vous pouvez vérifier différents types de requêtes et utiliser d’autres méthodes d’aide pour des tests plus sophistiqués.

Comment gérer les évènements

Laravel propose trois événements à déclencher lorsque vous traitez des requêtes HTTP.

  • RequestSending, qui précède l’envoi de la requête.
  • ResponseReceived, quand une réponse est reçue.
  • ConnectionFailed, quand aucune réponse n’est reçue.

Les trois événements comprennent la propriété $request qui permet d’inspecter l’instance Illuminate\Http\Client\Request, et ResponseReceived dispose d’une propriété supplémentaire $response property. Ces propriétés sont particulièrement utiles pour effectuer des actions après un événement. Par exemple, vous pouvez envoyer un e-mail après avoir reçu une réponse positive.

Pour créer un événement et un écouteur, accédez au fichier app/Providers/EventServiceProvider.php et remplacez le tableau listen par le code suivant.

protected $listen = [
    Registered::class => [
        SendEmailVerificationNotification::class,
    ],
    'Illuminate\Http\Client\Events\ResponseReceived' => [
        'App\Listeners\LogResponseReceived',
    ],
];

Exécutez ensuite la commande suivante dans votre terminal :

php artisan event:generate

La commande ci-dessus créera le fichier app/Listeners/LogResponseReceived.php. Remplacez le code de ce fichier par le code ci-dessous :

<?php
namespace App\Listeners;
use Illuminate\Http\Client\Events\ResponseReceived;
use Illuminate\Http\Request;
use Illuminate\Http\Response;
use Illuminate\Support\Facades\Log;
class LogResponseReceived
{
    /**
     * Create the event listener.
     *
     * @return void
     */
    public function __construct(Request $request, Response $response)
    {
        Log::channel('stderr')->info($response->status());
    }

    /**
     * Handle the event.
     *
     * @param  \Illuminate\Http\Client\Events\ResponseReceived  $event
     * @return void
     */
    public function handle(ResponseReceived $event)
    {
        
    }
}

Le journal d’information du code d’état est affiché dans le terminal.

Journaux du terminal affichant le code d'état
Journaux du terminal affichant le code d’état

Résumé

Qu’un site ou une application web soit créé par une organisation ou un développeur indépendant, les API sont la clé de leur succès. Cependant, leur utilisation peut s’avérer difficile.

De nombreux frameworks et bibliothèques promettent de simplifier ce processus, mais Laravel se distingue par l’importance qu’il accorde à la simplicité et à la facilité d’utilisation. Son client intégré prend en charge les appels d’API faciles, les appels d’API simultanés, les macros d’API, les méthodes d’aide pour les API basées sur JSON, et bien plus encore.

Steve Bonisteel Kinsta

Steve Bonisteel est un rédacteur technique chez Kinsta qui a commencé sa carrière d'écrivain en tant que journaliste de presse écrite, chassant les ambulances et les camions de pompiers. Il couvre les technologies similaires à l'Internet depuis la fin des années 1990.