Version: Canary 🚧

🚀 Http Client

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.
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.
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";
}

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 (Bow Framework)')
    ->get('/users');

echo $response->getContent();

`acceptJson`

Configure le client pour envoyer et accepter des données au format JSON. Ajoute automatiquement l'en-tête Content-Type: 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();

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 les en-têtes HTTP de la réponse sous forme de tableau. Ce tableau contient des informations telles que le code de statut HTTP, le type de contenu, le temps d'exécution, etc.

`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	`?int` (secondes)
`getConnexionTime()`	Temps d'établissement de la connexion	`?float` (secondes)
`getUploadSize()`	Taille des données envoyées	`?int` (octets)
`getUploadSpeed()`	Vitesse d'upload	`?float` (octets/sec)
`getDownloadSize()`	Taille des données reçues	`?int` (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

`getHeaders`

public function getHeaders(): array

Retourne tous les en-têtes HTTP de la réponse sous forme de tableau.

`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 sur directement sur le github.

Introduction​

Fonctionnalités principales​

Utilisation​

Méthodes HTTP​

get​

post​

put​

delete​

Configuration avancée​

addAttach​

withHeaders​

setUserAgent​

acceptJson​

La classe Response​

Méthodes principales​

getContent​

toJson​

toArray​

getHeaders​

getCode / statusCode​

isSuccessful​

isFailed​

Métriques de performance​

Gestion des erreurs​

Autres méthodes​

getHeaders​

getContentType​

Il manque quelque chose ?

Introduction

Fonctionnalités principales

Utilisation

Méthodes HTTP

`get`

`post`

`put`

`delete`

Configuration avancée

`addAttach`

`withHeaders`

`setUserAgent`

`acceptJson`

La classe `Response`

Méthodes principales

`getContent`

`toJson`

`toArray`

`getHeaders`

`getCode` / `statusCode`

`isSuccessful`

`isFailed`

Métriques de performance

Gestion des erreurs

Autres méthodes

`getHeaders`

`getContentType`