Skip to content

Commit d030063

Browse files
papacpapac
authored
Merge pull request #115 from bowphp/feat/add-docs
Update routing and http docs
2 parents 22def63 + c440970 commit d030063

4 files changed

Lines changed: 811 additions & 39 deletions

File tree

‎docs/http-client.mdx‎

Lines changed: 231 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -11,12 +11,14 @@ Le client HTTP de BowPHP est un composant puissant et flexible permettant de ré
1111

1212
## Fonctionnalités principales
1313

14-
1. Méthodes HTTP supportées : `GET`, `POST`, `PUT`, `DELETE`.
14+
1. Méthodes HTTP supportées : `GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `HEAD`, `OPTIONS`.
1515
2. Gestion des en-têtes personnalisés.
1616
3. Support des fichiers attachés pour les requêtes multipart/form-data.
1717
4. Encodage JSON natif des données.
1818
5. Définition d'une URL de base (`base_url`) pour simplifier la gestion des endpoints API.
19-
6. Gestion des erreurs avec des exceptions spécifiques.
19+
6. Authentification intégrée (Basic, Bearer, HTTP Auth).
20+
7. Configuration des timeouts et vérification SSL.
21+
8. Gestion des erreurs avec des exceptions spécifiques.
2022

2123
## Utilisation
2224

@@ -86,15 +88,15 @@ use Bow\Http\Client\HttpClient;
8688

8789
$client = new HttpClient('https://api.example.com');
8890
$response = $client->acceptJson()->post('/users', [
89-
'name' => 'John Doe',
90-
'email' => 'john.doe@example.com',
91-
'role' => 'admin'
91+
'name' => 'John Doe',
92+
'email' => 'john.doe@example.com',
93+
'role' => 'admin'
9294
]);
9395

9496
// Vérifier le succès
9597
if ($response->isSuccessful()) {
96-
$user = $response->toArray();
97-
echo "Utilisateur créé avec l'ID: {$user['id']}";
98+
$user = $response->toArray();
99+
echo "Utilisateur créé avec l'ID: {$user['id']}";
98100
}
99101
```
100102

@@ -115,12 +117,12 @@ use Bow\Http\Client\HttpClient;
115117

116118
$client = new HttpClient('https://api.example.com');
117119
$response = $client->acceptJson()->put('/users/123', [
118-
'name' => 'Jane Doe',
119-
'email' => 'jane.doe@example.com'
120+
'name' => 'Jane Doe',
121+
'email' => 'jane.doe@example.com'
120122
]);
121123

122124
if ($response->isSuccessful()) {
123-
echo "Utilisateur mis à jour avec succès";
125+
echo "Utilisateur mis à jour avec succès";
124126
}
125127
```
126128

@@ -143,10 +145,80 @@ $client = new HttpClient('https://api.example.com');
143145
$response = $client->delete('/users/123');
144146

145147
if ($response->isSuccessful()) {
146-
echo "Utilisateur supprimé avec succès";
148+
echo "Utilisateur supprimé avec succès";
149+
}
150+
```
151+
152+
### `patch`
153+
154+
Effectue une requête PATCH pour mettre à jour partiellement une ressource.
155+
156+
**Paramètres :**
157+
- `$url` : Le chemin relatif ou l'URL complète
158+
- `$data` : Tableau de données à envoyer pour la mise à jour partielle
159+
160+
**Retourne :** Une instance de `Response`
161+
162+
**Exemple :**
163+
164+
```php
165+
use Bow\Http\Client\HttpClient;
166+
167+
$client = new HttpClient('https://api.example.com');
168+
$response = $client->acceptJson()->patch('/users/123', [
169+
'email' => 'newemail@example.com'
170+
]);
171+
172+
if ($response->isSuccessful()) {
173+
echo "Email mis à jour avec succès";
174+
}
175+
```
176+
177+
### `head`
178+
179+
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.
180+
181+
**Paramètres :**
182+
- `$url` : Le chemin relatif ou l'URL complète
183+
- `$data` : Tableau de paramètres ajoutés à l'URL sous forme de query string
184+
185+
**Retourne :** Une instance de `Response`
186+
187+
**Exemple :**
188+
189+
```php
190+
use Bow\Http\Client\HttpClient;
191+
192+
$client = new HttpClient('https://api.example.com');
193+
$response = $client->head('/large-file.zip');
194+
195+
if ($response->isSuccessful()) {
196+
$headers = $response->getHeaders();
197+
echo "Taille du fichier : " . ($headers['download_content_length'] ?? 'inconnue');
147198
}
148199
```
149200

201+
### `options`
202+
203+
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.
204+
205+
**Paramètres :**
206+
- `$url` : Le chemin relatif ou l'URL complète
207+
208+
**Retourne :** Une instance de `Response`
209+
210+
**Exemple :**
211+
212+
```php
213+
use Bow\Http\Client\HttpClient;
214+
215+
$client = new HttpClient('https://api.example.com');
216+
$response = $client->options('/users');
217+
218+
// Les méthodes autorisées sont généralement dans l'en-tête Allow
219+
$headers = $response->getHeaders();
220+
```
221+
150222
## Configuration avancée
151223

152224
### `addAttach`
@@ -167,12 +239,12 @@ $client = new HttpClient('https://api.example.com');
167239

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

172244
// Upload de plusieurs fichiers
173245
$response = $client->addAttach([
174-
'/path/to/image1.jpg',
175-
'/path/to/image2.jpg'
246+
'/path/to/image1.jpg',
247+
'/path/to/image2.jpg'
176248
])->post('/upload-multiple');
177249
```
178250

@@ -192,11 +264,11 @@ use Bow\Http\Client\HttpClient;
192264

193265
$client = new HttpClient('https://api.example.com');
194266
$response = $client
195-
->withHeaders([
196-
'Authorization' => 'Bearer your-api-token',
197-
'X-Custom-Header' => 'custom-value'
198-
])
199-
->get('/protected-endpoint');
267+
->withHeaders([
268+
'Authorization' => 'Bearer your-api-token',
269+
'X-Custom-Header' => 'custom-value'
270+
])
271+
->get('/protected-endpoint');
200272

201273
echo $response->getContent();
202274
```
@@ -237,16 +309,144 @@ use Bow\Http\Client\HttpClient;
237309

238310
$client = new HttpClient('https://api.example.com');
239311
$response = $client
240-
->acceptJson()
241-
->post('/users', [
242-
'name' => 'John Doe',
243-
'email' => 'john@example.com'
244-
]);
312+
->acceptJson()
313+
->post('/users', [
314+
'name' => 'John Doe',
315+
'email' => 'john@example.com'
316+
]);
245317

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

322+
## Authentification
323+
324+
### `basicAuth`
325+
326+
Configure l'authentification HTTP Basic avec encodage Base64 des identifiants.
327+
328+
**Paramètres :**
329+
- `$key` : Clé ou nom d'utilisateur
330+
- `$secret` : Secret ou mot de passe
331+
332+
**Retourne :** L'instance du client pour un chaînage fluide
333+
334+
**Exemple :**
335+
336+
```php
337+
use Bow\Http\Client\HttpClient;
338+
339+
$client = new HttpClient('https://api.example.com');
340+
$response = $client
341+
->basicAuth('api_key', 'api_secret')
342+
->get('/protected-resource');
343+
```
344+
345+
### `bearerAuth`
346+
347+
Configure l'authentification par token Bearer (OAuth2, JWT, etc.).
348+
349+
**Paramètres :**
350+
- `$token` : Le token d'authentification
351+
352+
**Retourne :** L'instance du client pour un chaînage fluide
353+
354+
**Exemple :**
355+
356+
```php
357+
use Bow\Http\Client\HttpClient;
358+
359+
$client = new HttpClient('https://api.example.com');
360+
$response = $client
361+
->bearerAuth('eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...')
362+
->get('/user/profile');
363+
```
364+
365+
### `auth`
366+
367+
Configure l'authentification HTTP native de cURL.
368+
369+
**Paramètres :**
370+
- `$username` : Nom d'utilisateur
371+
- `$password` : Mot de passe
372+
373+
**Retourne :** L'instance du client pour un chaînage fluide
374+
375+
**Exemple :**
376+
377+
```php
378+
use Bow\Http\Client\HttpClient;
379+
380+
$client = new HttpClient('https://api.example.com');
381+
$response = $client
382+
->auth('username', 'password')
383+
->get('/protected');
384+
```
385+
386+
## Timeouts et SSL
387+
388+
### `timeout`
389+
390+
Définit le temps maximum autorisé pour l'exécution de la requête complète.
391+
392+
**Paramètres :**
393+
- `$seconds` : Durée en secondes
394+
395+
**Retourne :** L'instance du client pour un chaînage fluide
396+
397+
**Exemple :**
398+
399+
```php
400+
use Bow\Http\Client\HttpClient;
401+
402+
$client = new HttpClient('https://api.example.com');
403+
$response = $client
404+
->timeout(30) // 30 secondes maximum
405+
->get('/slow-endpoint');
406+
```
407+
408+
### `connectTimeout`
409+
410+
Définit le temps maximum pour établir la connexion au serveur.
411+
412+
**Paramètres :**
413+
- `$seconds` : Durée en secondes
414+
415+
**Retourne :** L'instance du client pour un chaînage fluide
416+
417+
**Exemple :**
418+
419+
```php
420+
use Bow\Http\Client\HttpClient;
421+
422+
$client = new HttpClient('https://api.example.com');
423+
$response = $client
424+
->connectTimeout(5) // 5 secondes pour établir la connexion
425+
->timeout(30)
426+
->get('/endpoint');
427+
```
428+
429+
### `disableSslVerification`
430+
431+
Désactive la vérification des certificats SSL. **Attention : à utiliser uniquement en environnement de développement.**
432+
433+
**Retourne :** L'instance du client pour un chaînage fluide
434+
435+
**Exemple :**
436+
437+
```php
438+
use Bow\Http\Client\HttpClient;
439+
440+
$client = new HttpClient('https://localhost:8443');
441+
$response = $client
442+
->disableSslVerification()
443+
->get('/api/test');
444+
```
445+
446+
:::warning
447+
Ne jamais désactiver la vérification SSL en production. Cela expose votre application à des attaques man-in-the-middle.
448+
:::
449+
250450
## La classe `Response`
251451

252452
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.
@@ -304,7 +504,7 @@ Alias de `toJson(true)`. Retourne le contenu JSON sous forme de tableau associat
304504
```php
305505
$users = $response->toArray();
306506
foreach ($users as $user) {
307-
echo $user['name'];
507+
echo $user['name'];
308508
}
309509
```
310510

@@ -333,7 +533,7 @@ $code = $response->getCode();
333533
$code = $response->statusCode();
334534

335535
if ($code === 200) {
336-
echo "Requête réussie";
536+
echo "Requête réussie";
337537
}
338538
```
339539

@@ -349,8 +549,8 @@ Retourne `true` si le code de statut indique un succès (200 ou 201).
349549

350550
```php
351551
if ($response->isSuccessful()) {
352-
$data = $response->toArray();
353-
// Traiter les données
552+
$data = $response->toArray();
553+
// Traiter les données
354554
}
355555
```
356556

@@ -366,7 +566,7 @@ Retourne `true` si la requête a échoué (code différent de 200 ou 201).
366566

367567
```php
368568
if ($response->isFailed()) {
369-
echo "Erreur : " . $response->getCode();
569+
echo "Erreur : " . $response->getCode();
370570
}
371571
```
372572

@@ -403,7 +603,7 @@ echo "Vitesse : " . $response->getDownloadSpeed() . " octets/s\n";
403603

404604
```php
405605
if ($response->isFailed()) {
406-
echo "Erreur #{$response->getErrorNumber()}: {$response->getErrorMessage()}";
606+
echo "Erreur #{$response->getErrorNumber()}: {$response->getErrorMessage()}";
407607
}
408608
```
409609

@@ -430,7 +630,7 @@ Retourne le type MIME du contenu (ex: `application/json`, `text/html`).
430630
```php
431631
$contentType = $response->getContentType();
432632
if ($contentType === 'application/json') {
433-
$data = $response->toArray();
633+
$data = $response->toArray();
434634
}
435635
```
436636

0 commit comments

Comments
 (0)