Version: CANARY 🚧

Client HTTP

Introduction

Le client HTTP de BowPHP est un composant puissant et flexible permettant de réaliser des requêtes HTTP vers des API ou des services distants. Il utilise la bibliothèque cURL pour offrir des fonctionnalités avancées tout en simplifiant leur utilisation.

Fonctionnalités principales

Méthodes HTTP supportées : GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS.
Gestion des en-têtes personnalisés.
Support des fichiers attachés pour les requêtes multipart/form-data.
Encodage JSON natif des données.
Définition d'une URL de base (base_url) pour simplifier la gestion des endpoints API.
Authentification intégrée (Basic, Bearer, HTTP Auth).
Configuration des timeouts et vérification SSL.
Gestion des erreurs avec des exceptions spécifiques.

Utilisation

Pour utiliser le client HTTP, créez simplement une nouvelle instance ou injectez-le dans un service ou un contrôleur :

use Bow\Http\Client\HttpClient;

$client = new HttpClient();

info

Le constructeur accepte un paramètre optionnel $base_url. Si l'URL de base est définie, l'appel des endpoints devient plus simple :

$client = new HttpClient('https://api.example.com');

astuce

Si vous n'avez pas défini l'URL de base lors de la création de l'instance, utilisez setBaseUrl pour le faire ultérieurement :

$client->setBaseUrl('https://api.example.com');

Méthodes HTTP

`get`

Effectue une requête GET pour récupérer des ressources.

Paramètres :

$url : Le chemin relatif ou l'URL complète
$data : Tableau de paramètres ajoutés à l'URL sous forme de query string

Retourne : Une instance de Response

Exemple :

use Bow\Http\Client\HttpClient;

$client = new HttpClient('https://api.example.com');
$response = $client->get('/users', ['page' => 2, 'limit' => 10]);

echo $response->getContent();
// Accéder aux données JSON
$users = $response->toArray();

`post`

Effectue une requête POST pour créer ou envoyer des données.

Paramètres :

$url : Le chemin relatif ou l'URL complète
$data : Tableau de données à envoyer (JSON ou form-urlencoded selon la configuration)

Retourne : Une instance de Response

Exemple :

use Bow\Http\Client\HttpClient;

$client = new HttpClient('https://api.example.com');
$response = $client->acceptJson()->post('/users', [
  'name' => 'John Doe',
  'email' => 'john.doe@example.com',
  'role' => 'admin'
]);

// Vérifier le succès
if ($response->isSuccessful()) {
  $user = $response->toArray();
  echo "Utilisateur créé avec l'ID: {$user['id']}";
}

`put`

Effectue une requête PUT pour mettre à jour une ressource existante.

Paramètres :

$url : Le chemin relatif ou l'URL complète
$data : Tableau de données à envoyer pour la mise à jour

Retourne : Une instance de Response

Exemple :

use Bow\Http\Client\HttpClient;

$client = new HttpClient('https://api.example.com');
$response = $client->acceptJson()->put('/users/123', [
  'name' => 'Jane Doe',
  'email' => 'jane.doe@example.com'
]);

if ($response->isSuccessful()) {
  echo "Utilisateur mis à jour avec succès";
}

`delete`

Effectue une requête DELETE pour supprimer une ressource.

Paramètres :

$url : Le chemin relatif ou l'URL complète
$data : Tableau de données optionnelles à envoyer

Retourne : Une instance de Response

Exemple :

use Bow\Http\Client\HttpClient;

$client = new HttpClient('https://api.example.com');
$response = $client->delete('/users/123');

if ($response->isSuccessful()) {
  echo "Utilisateur supprimé avec succès";
}

`patch`

Effectue une requête PATCH pour mettre à jour partiellement une ressource.

Paramètres :

$url : Le chemin relatif ou l'URL complète
$data : Tableau de données à envoyer pour la mise à jour partielle

Retourne : Une instance de Response

Exemple :

use Bow\Http\Client\HttpClient;

$client = new HttpClient('https://api.example.com');
$response = $client->acceptJson()->patch('/users/123', [
  'email' => 'newemail@example.com'
]);

if ($response->isSuccessful()) {
  echo "Email mis à jour avec succès";
}

`head`

Effectue une requête HEAD pour récupérer uniquement les en-têtes HTTP sans le corps de la réponse. Utile pour vérifier l'existence d'une ressource ou obtenir des métadonnées.

Paramètres :

$url : Le chemin relatif ou l'URL complète
$data : Tableau de paramètres ajoutés à l'URL sous forme de query string

Retourne : Une instance de Response

Exemple :

use Bow\Http\Client\HttpClient;

$client = new HttpClient('https://api.example.com');
$response = $client->head('/large-file.zip');

if ($response->isSuccessful()) {
  $headers = $response->getHeaders();
  echo "Taille du fichier : " . ($headers['download_content_length'] ?? 'inconnue');
}

`options`

Effectue une requête OPTIONS pour découvrir les méthodes HTTP autorisées sur une ressource. Souvent utilisé pour les requêtes CORS préliminaires.

Paramètres :

$url : Le chemin relatif ou l'URL complète

Retourne : Une instance de Response

Exemple :

use Bow\Http\Client\HttpClient;

$client = new HttpClient('https://api.example.com');
$response = $client->options('/users');

// Les méthodes autorisées sont généralement dans l'en-tête Allow
$headers = $response->getHeaders();

Configuration avancée

`addAttach`

Attache un ou plusieurs fichiers à une requête multipart/form-data.

Paramètres :

$attach : Chemin du fichier (string) ou tableau de chemins de fichiers

Retourne : L'instance du client pour un chaînage fluide

Exemple :

use Bow\Http\Client\HttpClient;

$client = new HttpClient('https://api.example.com');

// Upload d'un seul fichier
$response = $client->addAttach('/path/to/document.pdf')
  ->post('/upload');

// Upload de plusieurs fichiers
$response = $client->addAttach([
  '/path/to/image1.jpg',
  '/path/to/image2.jpg'
])->post('/upload-multiple');

`withHeaders`

Ajoute des en-têtes HTTP personnalisés à la requête.

Paramètres :

$headers : Tableau associatif d'en-têtes

Retourne : L'instance du client pour un chaînage fluide

Exemple :

use Bow\Http\Client\HttpClient;

$client = new HttpClient('https://api.example.com');
$response = $client
  ->withHeaders([
    'Authorization' => 'Bearer your-api-token',
    'X-Custom-Header' => 'custom-value'
  ])
  ->get('/protected-endpoint');

echo $response->getContent();

`setUserAgent`

Définit l'agent utilisateur (User-Agent) pour la requête.

Paramètres :

$user_agent : Chaîne représentant l'agent utilisateur

Retourne : L'instance du client pour un chaînage fluide

Exemple :

use Bow\Http\Client\HttpClient;

$client = new HttpClient('https://api.example.com');
$response = $client
    ->setUserAgent('MyApp/1.0 (BowPHP)')
    ->get('/users');

echo $response->getContent();

`acceptJson`

Configure le client pour envoyer et accepter des données au format JSON. Ajoute automatiquement les en-têtes Content-Type: application/json et Accept: application/json.

Retourne : L'instance du client pour un chaînage fluide

Exemple :

use Bow\Http\Client\HttpClient;

$client = new HttpClient('https://api.example.com');
$response = $client
  ->acceptJson()
  ->post('/users', [
    'name' => 'John Doe',
    'email' => 'john@example.com'
  ]);

// Les données seront automatiquement encodées en JSON
$result = $response->toArray();

`withJson`

Configure le client pour envoyer des données au format JSON, sans imposer le format de la réponse. Ajoute uniquement l'en-tête Content-Type: application/json.

Utilisez withJson lorsque l'API distante accepte du JSON en entrée mais renvoie un autre format (XML, HTML, texte brut). Utilisez acceptJson quand l'échange est JSON dans les deux sens.

Retourne : L'instance du client pour un chaînage fluide

Exemple :

use Bow\Http\Client\HttpClient;

$client = new HttpClient('https://api.example.com');
$response = $client
  ->withJson()
  ->post('/webhook', ['event' => 'order.created', 'order_id' => 42]);

`hasHeader`

Vérifie si un en-tête spécifique (clé et valeur) a déjà été ajouté à la requête. Pratique pour éviter d'ajouter deux fois le même en-tête conditionnel.

Paramètres :

$key : Nom de l'en-tête
$value : Valeur attendue

Retourne : bool

Exemple :

$client = new HttpClient('https://api.example.com');
$client->withHeaders(['X-Trace-Id' => 'abc-123']);

if (!$client->hasHeader('X-Trace-Id', 'abc-123')) {
    $client->withHeaders(['X-Trace-Id' => 'abc-123']);
}

Authentification

`basicAuth`

Configure l'authentification HTTP Basic avec encodage Base64 des identifiants.

Paramètres :

$key : Clé ou nom d'utilisateur
$secret : Secret ou mot de passe

Retourne : L'instance du client pour un chaînage fluide

Exemple :

use Bow\Http\Client\HttpClient;

$client = new HttpClient('https://api.example.com');
$response = $client
  ->basicAuth('api_key', 'api_secret')
  ->get('/protected-resource');

`bearerAuth`

Configure l'authentification par token Bearer (OAuth2, JWT, etc.).

Paramètres :

$token : Le token d'authentification

Retourne : L'instance du client pour un chaînage fluide

Exemple :

use Bow\Http\Client\HttpClient;

$client = new HttpClient('https://api.example.com');
$response = $client
  ->bearerAuth('eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...')
  ->get('/user/profile');

`auth`

Configure l'authentification HTTP native de cURL.

Paramètres :

$username : Nom d'utilisateur
$password : Mot de passe

Retourne : L'instance du client pour un chaînage fluide

Exemple :

use Bow\Http\Client\HttpClient;

$client = new HttpClient('https://api.example.com');
$response = $client
  ->auth('username', 'password')
  ->get('/protected');

Timeouts et SSL

`timeout`

Définit le temps maximum autorisé pour l'exécution de la requête complète.

Paramètres :

$seconds : Durée en secondes

Retourne : L'instance du client pour un chaînage fluide

Exemple :

use Bow\Http\Client\HttpClient;

$client = new HttpClient('https://api.example.com');
$response = $client
  ->timeout(30) // 30 secondes maximum
  ->get('/slow-endpoint');

`connectTimeout`

Définit le temps maximum pour établir la connexion au serveur.

Paramètres :

$seconds : Durée en secondes

Retourne : L'instance du client pour un chaînage fluide

Exemple :

use Bow\Http\Client\HttpClient;

$client = new HttpClient('https://api.example.com');
$response = $client
  ->connectTimeout(5) // 5 secondes pour établir la connexion
  ->timeout(30)
  ->get('/endpoint');

`disableSslVerification`

Désactive la vérification des certificats SSL. Attention : à utiliser uniquement en environnement de développement.

Retourne : L'instance du client pour un chaînage fluide

Exemple :

use Bow\Http\Client\HttpClient;

$client = new HttpClient('https://localhost:8443');
$response = $client
  ->disableSslVerification()
  ->get('/api/test');

attention

Ne jamais désactiver la vérification SSL en production. Cela expose votre application à des attaques man-in-the-middle.

Gestion des exceptions

Il faut distinguer deux niveaux d'erreur :

Erreur de transport — la requête n'a pas pu aboutir du tout (connexion refusée, hôte introuvable, timeout dépassé, échec de la négociation SSL). Dans ce cas, le client lève une Bow\Http\Client\HttpClientException portant le message et le code d'erreur cURL.
Réponse HTTP en erreur — la requête a abouti mais le serveur répond avec un statut d'erreur (404, 500, …). Aucune exception n'est levée : vous obtenez une instance Response et inspectez son statut via isFailed() / getCode().

use Bow\Http\Client\HttpClient;
use Bow\Http\Client\HttpClientException;

$client = new HttpClient('https://api.example.com');

try {
    $response = $client->acceptJson()->get('/users');

    // La requête a abouti : vérifier le statut HTTP renvoyé
    if ($response->isFailed()) {
        // 4xx / 5xx — pas d'exception, on lit le code
        logger()->warning('API a répondu ' . $response->getCode());
        return;
    }

    $users = $response->toArray();
} catch (HttpClientException $e) {
    // Échec réseau / SSL / timeout : la requête n'a jamais abouti
    logger()->error('Échec HTTP: ' . $e->getMessage(), ['code' => $e->getCode()]);
}

Extension cURL requise

Le client repose sur l'extension curl. Si elle n'est pas chargée, instancier HttpClient lève une BadFunctionCallException.

La classe `Response`

La classe Response encapsule toutes les informations retournées par une requête HTTP : contenu, en-têtes, code de statut et métriques de performance. Elle offre une interface simple et intuitive pour manipuler les réponses.

Méthodes principales

`getContent`

public function getContent(): ?string

Retourne le contenu brut de la réponse HTTP sous forme de chaîne. Retourne null si aucun contenu n'est disponible.

Exemple :

$content = $response->getContent();
echo $content;

`toJson`

public function toJson(?bool $associative = null): object|array

Décode le contenu JSON de la réponse en objet ou tableau PHP.

Paramètres :

$associative : true pour un tableau associatif, false pour un objet (défaut)

Exemple :

// Retourne un objet
$user = $response->toJson();
echo $user->name;

// Retourne un tableau
$userData = $response->toJson(true);
echo $userData['name'];

`toArray`

public function toArray(): array

Alias de toJson(true). Retourne le contenu JSON sous forme de tableau associatif.

Exemple :

$users = $response->toArray();
foreach ($users as $user) {
  echo $user['name'];
}

`getHeaders`

public function getHeaders(): array

Retourne le tableau de métadonnées produit par curl_getinfo() pour la requête. Ce tableau n'est pas la liste brute des en-têtes HTTP de réponse : il contient des clés cURL telles que http_code, content_type, total_time, connect_time, size_upload, size_download, download_content_length, etc.

remarque

Si vous avez besoin d'un en-tête HTTP brut spécifique (par ex. Location, X-Request-Id), parsez-le via CURLOPT_HEADERFUNCTION ou utilisez l'option de configuration cURL adéquate côté serveur distant.

`getCode` / `statusCode`

public function getCode(): ?int
public function statusCode(): ?int

Retournent le code de statut HTTP de la réponse (200, 404, 500, etc.). Retourne null si indisponible.

Exemple :

$code = $response->getCode();
// ou
$code = $response->statusCode();

if ($code === 200) {
  echo "Requête réussie";
}

`isSuccessful`

public function isSuccessful(): bool

Retourne true si le code de statut indique un succès (200 ou 201).

Exemple :

if ($response->isSuccessful()) {
  $data = $response->toArray();
  // Traiter les données
}

`isFailed`

public function isFailed(): bool

Retourne true si la requête a échoué (code différent de 200 ou 201).

Exemple :

if ($response->isFailed()) {
  echo "Erreur : " . $response->getCode();
}

Métriques de performance

Le client HTTP fournit plusieurs méthodes pour analyser les performances des requêtes :

Méthode	Description	Retour
`getExecutionTime()`	Temps total d'exécution de la requête (clé cURL `total_time`)	`mixed` (généralement `?float`, secondes)
`getConnexionTime()`	Temps d'établissement de la connexion	`?float` (secondes)
`getUploadSize()`	Taille des données envoyées	`?float` (octets)
`getUploadSpeed()`	Vitesse d'upload	`?float` (octets/sec)
`getDownloadSize()`	Taille des données reçues	`?float` (octets)
`getDownloadSpeed()`	Vitesse de download	`?float` (octets/sec)

Exemple d'utilisation :

$response = $client->get('/large-data');

echo "Temps d'exécution : " . $response->getExecutionTime() . "s\n";
echo "Taille téléchargée : " . $response->getDownloadSize() . " octets\n";
echo "Vitesse : " . $response->getDownloadSpeed() . " octets/s\n";

Gestion des erreurs

getErrorMessage : Retourne le message d'erreur cURL s'il y en a un, sinon une chaîne vide.

getErrorNumber : Retourne le code d'erreur cURL.

Exemple :

if ($response->isFailed()) {
  echo "Erreur #{$response->getErrorNumber()}: {$response->getErrorMessage()}";
}

Autres méthodes

`getContentType`

public function getContentType(): ?string

Retourne le type MIME du contenu (ex: application/json, text/html).

Exemple :

$contentType = $response->getContentType();
if ($contentType === 'application/json') {
  $data = $response->toArray();
}

Il manque quelque chose ?

Si vous rencontrez des problèmes avec la documentation ou si vous avez des suggestions pour améliorer la documentation ou le projet en général, veuillez déposer une issue pour nous, ou envoyer un tweet mentionnant le compte Twitter @bowframework ou directement sur le github.

Introduction​

Fonctionnalités principales​

Utilisation​

Méthodes HTTP​

get​

post​

put​

delete​

patch​

head​

options​

Configuration avancée​

addAttach​

withHeaders​

setUserAgent​

acceptJson​

withJson​

hasHeader​

Authentification​

basicAuth​

bearerAuth​

auth​

Timeouts et SSL​

timeout​

connectTimeout​

disableSslVerification​

Gestion des exceptions​

La classe Response​

Méthodes principales​

getContent​

toJson​

toArray​

getHeaders​

getCode / statusCode​

isSuccessful​

isFailed​

Métriques de performance​

Gestion des erreurs​

Autres méthodes​

getContentType​

Il manque quelque chose ?

Introduction

Fonctionnalités principales

Utilisation

Méthodes HTTP

`get`

`post`

`put`

`delete`

`patch`

`head`

`options`

Configuration avancée

`addAttach`

`withHeaders`

`setUserAgent`

`acceptJson`

`withJson`

`hasHeader`

Authentification

`basicAuth`

`bearerAuth`

`auth`

Timeouts et SSL

`timeout`

`connectTimeout`

`disableSslVerification`

Gestion des exceptions

La classe `Response`

Méthodes principales

`getContent`

`toJson`

`toArray`

`getHeaders`

`getCode` / `statusCode`

`isSuccessful`

`isFailed`

Métriques de performance

Gestion des erreurs

Autres méthodes

`getContentType`