Client Http¶

Faire des Requêtes¶

Faire des requêtes est simple et direct. Faire une requête GET ressemble à ceci:

use Cake\Http\Client;

$http = new Client();

// Simple GET
$response = $http->get('http://example.com/test.html');

// Simple GET avec querystring
$response = $http->get('http://example.com/search', ['q' => 'widget']);

// Simple GET avec querystring & headers supplémentaires
$response = $http->get('http://example.com/search', ['q' => 'widget'], [
  'headers' => ['X-Requested-With' => 'XMLHttpRequest']
]);

Faire des requêtes POST et PUT est également simple:

// Envoi d'une requête POST avec des données encodées application/x-www-form-urlencoded
$http = new Client();
$response = $http->post('http://example.com/posts/add', [
  'title' => 'testing',
  'body' => 'content in the post'
]);

// Envoi d'une requête PUT avec des données encodées application/x-www-form-urlencoded
$response = $http->put('http://example.com/posts/add', [
  'title' => 'testing',
  'body' => 'content in the post'
]);

// Autres méthodes.
$http->delete(...);
$http->head(...);
$http->patch(...);

Créer des Requêtes Multipart avec des Fichiers¶

Vous pouvez inclure des fichiers dans des corps de requête en incluant un gestionnaire de fichier dans le tableau de données:

$http = new Client();
$response = $http->post('http://example.com/api', [
  'image' => fopen('/path/to/a/file', 'r'),
]);

Le gestionnaire de fichiers sera lu jusqu’à sa fin, il ne sera pas rembobiné avant d’être lu.

Cette fonctionnalité est dépréciée depuis CakePHP 3.0.5 et sera retirée dans une version future. Avant que cela n’arrive, les données d’utilisateur passées au Client Http devront être nettoyées comme suit:

$response = $http->post('http://example.com/api', [
    'search' => ltrim($this->request->getData('search'), '@'),
]);

S’il est nécessaire de garder les caractères du début @ dans les chaînes de la requête, vous pouvez passer une chaîne de requête pré-encodée avec http_build_query():

$response = $http->post('http://example.com/api', http_build_query([
    'search' => $this->request->getData('search'),
]));

use Cake\Http\Client\FormData;

$data = new FormData();

// Création d'une partie XML
$xml = $data->newPart('xml', $xmlString);
// Définit le type de contenu.
$xml->type('application/xml');
$data->add($xml);

// Création d'un fichier upload avec addFile()
// Ceci va aussi ajouter le fichier aux données du formulaire.
$file = $data->addFile('upload', fopen('/some/file.txt', 'r'));
$file->contentId('abc123');
$file->disposition('attachment');

// Envoi de la requête.
$response = $http->post(
    'http://example.com/api',
    (string)$data,
    ['headers' => ['Content-Type' => $data->contentType()]]
);

Envoyer des Corps de Requête¶

Lorsque vous utilisez des REST API, vous avez souvent besoin d’envoyer des corps de requête qui ne sont pas encodés. Http\Client le permet grâce à l’option type:

// Envoi d'un body JSON.
$http = new Client();
$response = $http->post(
  'http://example.com/tasks',
  json_encode($data),
  ['type' => 'json']
);

La clé type peut être soit “json”, soit “xml” ou bien un mime type complet. Quand vous utilisez l’option type, vous devrez fournir les données en chaîne de caractères. Si vous faîtes une requête GET qui a besoin des deux paramètres querystring et d’un corps de requête, vous pouvez faire comme ce qui suit:

// Envoi d'un body JSON dans une requête GET avec des paramètres query string.
$http = new Client();
$response = $http->get(
  'http://example.com/tasks',
  ['q' => 'test', '_content' => json_encode($data)],
  ['type' => 'json']
);

Options de la Méthode Request¶

Chaque méthode HTTP prend un paramètre $options qui est utilisé pour fournir des informations de requête supplémentaires. les clés suivantes peuvent être utilisées dans $options:

• headers - Tableau de headers supplémentaires

• cookie - Tableau de cookies à utiliser.

• proxy - Tableau d’informations proxy.

• auth - Tableau de données d’authentification, la clé type est utilisée pour déléguer à une stratégie d’authentification. Par défaut l’Auth Basic est utilisée.

• ssl_verify_peer - par défaut à true. Définie à false pour désactiver la certification SSL (non recommandé)

• ssl_verify_peer_name - par défaut à true. Définie à false pour désactiver la vérification du nom d’hôte quand lors des vérifications des certificats SSL (non recommandé).

• ssl_verify_depth - par défaut à 5. Depth to traverse in the CA chain.

• ssl_verify_host - par défaut à true. Valide le certificat SSL pour un nom d’hôte.

• ssl_cafile - par défaut pour construire dans cafile. Ecrasez-le pour utiliser des bundles CA personnalisés.

• timeout - Durée d’attente avant le timing out en secondes.

• type - Envoi un corps de requête dans un type de contenu personnalisé. Nécessite que $data soit une chaîne ou que l’option _content soit définie quand vous faîtes des requêtes GET.

• redirect - Nombre de redirections à suivre. false par défaut.

Le paramètre options est toujours le 3ème paramètre dans chaque méthode HTTP. Elles peuvent aussi être utilisées en construisant Client pour créer des clients scoped.

Authentification¶

Cake\Http\Client intègre plusieurs systèmes d’authentification. Les différentes stratégies d’authentification peuvent être ajoutées par les développeurs. Les stratégies d’Authentification sont appelées avant que la requête ne soit envoyée, et permettent aux headers d’être ajoutés au contexte de la requête.

$http = new Client();
$response = $http->get('http://example.com/profile/1', [], [
  'auth' => ['username' => 'mark', 'password' => 'secret']
]);

$http = new Client();
$response = $http->get('http://example.com/profile/1', [], [
  'auth' => [
    'type' => 'digest',
    'username' => 'mark',
    'password' => 'secret',
    'realm' => 'myrealm',
    'nonce' => 'onetimevalue',
    'qop' => 1,
    'opaque' => 'someval'
  ]
]);

$http = new Client();
$response = $http->get('http://example.com/profile/1', [], [
  'auth' => [
    'type' => 'oauth',
    'consumerKey' => 'bigkey',
    'consumerSecret' => 'secret',
    'token' => '...',
    'tokenSecret' => '...',
    'realm' => 'tickets',
  ]
]);

$http = new Client([
    'headers' => ['Authorization' => 'Bearer ' . $accessToken]
]);
$response = $http->get('https://example.com/api/profile/1');

$http = new Client();
$response = $http->get('http://example.com/test.php', [], [
  'proxy' => [
    'username' => 'mark',
    'password' => 'testing',
    'proxy' => '127.0.0.1:8080',
  ]
]);

Créer des Scoped Clients¶

Devoir retaper le nom de domaine, les paramètres d’authentification et de proxy peut devenir fastidieux et source d’erreurs. Pour réduire ce risque d’erreur et être moins pénible, vous pouvez créer des clients scoped:

// Création d'un client scoped.
$http = new Client([
  'host' => 'api.example.com',
  'scheme' => 'https',
  'auth' => ['username' => 'mark', 'password' => 'testing']
]);

// Faire une requête vers api.example.com
$response = $http->get('/test.php');

Les informations suivantes peuvent être utilisées lors de la création d’un client scoped:

• host

• scheme

• proxy

• auth

• port

• cookies

• timeout

• ssl_verify_peer

• ssl_verify_depth

• ssl_verify_host

Chacune de ces options peut être remplacées en les spécifiant quand vous faîtes des requêtes. host, scheme, proxy, port sont remplacées dans l’URL de la requête:

// Utilisation du client scoped que nous avons créé précédemment.
$response = $http->get('http://foo.com/test.php');

Ce qui est au-dessus va remplacer le domaine, le scheme, et le port. Cependant, cette requête va continuer à utiliser toutes les autres options définies quand le client scoped a été créé. Consultez Options de la Méthode Request pour plus d’informations sur les options intégrées.

Configurer et Gérer les Cookies¶

Http\Client peut aussi accepter les cookies quand on fait des requêtes. En plus d’accepter les cookies, il va aussi automatiquement stocker les cookies valides définis dans les responses. Toute response avec des cookies, les verra stockés dans l’instance d’origine de Http\Client. Les cookies stockés dans une instance Client sont automatiquement inclus dans les futures requêtes vers le domaine + combinaisons de chemin qui correspondent:

$http = new Client([
    'host' => 'cakephp.org'
]);

// Création d'une requête qui définit des cookies
$response = $http->get('/');

// Cookies à partir de la première requête seront inclus par défaut.
$response2 = $http->get('/changelogs');

Vous pouvez toujours remplacer les cookies auto-inclus en les définissant dans les paramètres $options de la requête:

// Personalisation d'un cookie existant.
$response = $http->get('/changelogs', [], [
    'cookies' => ['sessionid' => '123abc']
]);

Vous pouvez ajouter des cookies au client après l’avoir créé en utilisant la méthode addCookie():

use Cake\Http\Cookie\Cookie;

$http = new Client([
    'host' => 'cakephp.org'
]);
$http->addCookie(new Cookie('session', 'abc123'));

Objets Response¶

class Cake\Http\Client\Response¶

Les objets Response ont un certain nombre de méthodes pour parcourir les données de réponse.

// Lit le corps entier de la réponse en chaîne de caractères.
$response->body();

// En propriété
$response->body;

// Récupère une Psr\Http\Message\StreamInterface contenant le corps de la réponse
$stream = $response->getBody();

// Lit un stream de 100 bytes en une fois.
while (!$stream->eof()) {
    echo $stream->read(100);
}

// Récupération du XML.
$http = new Client();
$response = $http->get('http://example.com/test.xml');
$xml = $response->xml;

// Récupération du JSON.
$http = new Client();
$response = $http->get('http://example.com/test.json');
$json = $response->json;

// Récupère les en-têtes sous la forme d'un tableau associatif array.
$response->getHeaders();

// Récupère un en-tête unique sous la forme d'un tableau.
$response->getHeader('content-type');

// Récupère un en-tête sous la forme d'une chaîne de caractères
$response->getHeaderLine('content-type');

// Récupère la réponse encodée
$response->getEncoding();

// Récupère un tableau de key=>value pour tous les en-têtes
$response->headers;

// Récupère tous les cookies (toutes les données)
$response->getCookies();

// Récupère une valeur d'une unique cookie.
$response->getCookie('session_id');

// Récupère les données complètes pour un unique cookie
// includes value, expires, path, httponly, secure keys.
$response->getCookieData('session_id');

// Accède aux données complètes pour tous les cookies.
$response->cookies;

// La réponse était-elle 20x
$response->isOk();

// La réponse était-elle 30x
$response->isRedirect();

// Récupère le code de statut
$response->getStatusCode();

// helper __get()
$response->code;