Quickstart

Cette page fournit une introduction rapide à Guzzle et des exemples d'introduction. Si vous n'avez pas encore installé Guzzle, rendez-vous sur la page Installation page.

Faire une demande

Vous pouvez envoyer des demandes avec Guzzle en utilisant un objet GuzzleHttp\ClientInterface.

Créer un client

use GuzzleHttp\Client;

$client = new Client([
    // Base URI is used with relative requests
    'base_uri' => 'http://httpbin.org',
    // You can set any number of default request options.
    'timeout'  => 2.0,
]);

Les clients sont immuables dans Guzzle, ce qui signifie que vous ne pouvez pas modifier les valeurs par défaut utilisées par un client après sa création.

Le constructeur du client accepte un tableau associatif d'options :

base_uri

(string|UriInterface) URI de base du client qui est fusionné dans des URI relatifs. Peut être une chaîne ou une instance de UriInterface. Lorsqu'un URI relatif relative est fournie à un client, ce dernier combinera l'URI de base avec l'URI URI relatif en utilisant les règles décrites dans RFC 3986, section 5.2.

// Créer un client avec un URI de base
$client = new GuzzleHttp\Client([ 'base_uri' => ; 'https://foo.com/api/']) ;
// Envoi d'une requête à https://foo.com/api/test
$response = $client->request('GET', 'test') ;
// Envoi d'une requête à https://foo.com/root
$response = $client->request('GET', '/root') ;

Vous n'avez pas envie de lire la RFC 3986 ? Voici quelques exemples rapides de la façon dont un base_uri est résolu par un autre URI.

base_uri URI Résultat
http://foo.com /bar http://foo.com/bar
http://foo.com/foo /bar http://foo.com/bar
http://foo.com/foo bar http://foo.com/bar
http://foo.com/foo/ bar http://foo.com/foo/bar
http://foo.com http://baz.com http://baz.com
http://foo.com/?bar bar http://foo.com/bar
handler
(appelable) Fonction qui transfère les requêtes HTTP sur le fil. La fonction fonction est appelée avec une Psr7\Http\Message\RequestInterface et une matrice d'options de transfert, et doit retourner un GuzzleHttp\Promise\PromiseInterface qui est rempli avec un Psr7\Http\Message\ResponseInterface en cas de succès.
...
(mixte) Toutes les autres options passées au constructeur sont utilisées par défaut par défaut avec chaque requête créée par le client.

Envoyer des demandes

Les méthodes magiques sur le client facilitent l'envoi de requêtes synchrones :

$response = $client->get('http://httpbin.org/get');
$response = $client->delete('http://httpbin.org/delete');
$response = $client->head('http://httpbin.org/get');
$response = $client->options('http://httpbin.org/get');
$response = $client->patch('http://httpbin.org/patch');
$response = $client->post('http://httpbin.org/post');
$response = $client->put('http://httpbin.org/put');

Vous pouvez créer une demande, puis l'envoyer avec le client lorsque vous êtes prêt :

use GuzzleHttp\Psr7\Request;

$request = new Request('PUT', 'http://httpbin.org/put');
$response = $client->send($request, ['timeout' => 2]);

Les objets clients offrent une grande souplesse dans la manière dont les demandes sont transférées, y compris les options de demande par défaut, les intergiciels de pile de gestionnaires qui sont utilisés par chaque demande, et un URI de base qui vous permet d'envoyer des demandes avec des URI relatifs.

Pour en savoir plus sur les intergiciels clients, consultez la page Handlers and Middleware de la documentation.

Demandes asynchrones

Vous pouvez envoyer des demandes asynchrones en utilisant les méthodes magiques fournies par un client :

$promise = $client->getAsync('http://httpbin.org/get');
$promise = $client->deleteAsync('http://httpbin.org/delete');
$promise = $client->headAsync('http://httpbin.org/get');
$promise = $client->optionsAsync('http://httpbin.org/get');
$promise = $client->patchAsync('http://httpbin.org/patch');
$promise = $client->postAsync('http://httpbin.org/post');
$promise = $client->putAsync('http://httpbin.org/put');

Vous pouvez également utiliser les méthodes sendAsync() et requestAsync() d'un client :

use GuzzleHttp\Psr7\Request;

// Create a PSR-7 request object to send
$headers = ['X-Foo' => 'Bar'];
$body = 'Hello!';
$request = new Request('HEAD', 'http://httpbin.org/head', $headers, $body);
$promise = $client->sendAsync($request);

// Or, if you don't need to pass in a request instance:
$promise = $client->requestAsync('GET', 'http://httpbin.org/get');

La promesse renvoyée par ces méthodes met en œuvre la spécification suivante Promises/A+ spec, fournie par la bibliothèque de Bibliothèque de promesses Guzzle. Cela signifie que vous pouvez enchaîner des appels then() à partir de la promesse. Ces appels then sont soit satisfaits avec une Psr\Http\Message\ResponseInterface, soit rejetés avec une exception.

use Psr\Http\Message\ResponseInterface;
use GuzzleHttp\Exception\RequestException;

$promise = $client->requestAsync('GET', 'http://httpbin.org/get');
$promise->then(
    function (ResponseInterface $res) {
        echo $res->getStatusCode() . "\n";
    },
    function (RequestException $e) {
        echo $e->getMessage() . "\n";
        echo $e->getRequest()->getMethod();
    }
);

Demandes simultanées

Vous pouvez envoyer plusieurs demandes simultanément en utilisant des promesses et des demandes asynchrones.

use GuzzleHttp\Client;
use GuzzleHttp\Promise;

$client = new Client(['base_uri' => 'http://httpbin.org/']);

// Initiate each request but do not block
$promises = [
    'image' => $client->getAsync('/image'),
    'png'   => $client->getAsync('/image/png'),
    'jpeg'  => $client->getAsync('/image/jpeg'),
    'webp'  => $client->getAsync('/image/webp')
];

// Wait for the requests to complete; throws a ConnectException
// if any of the requests fail
$responses = Promise\Utils::unwrap($promises);

// You can access each response using the key of the promise
echo $responses['image']->getHeader('Content-Length')[0];
echo $responses['png']->getHeader('Content-Length')[0];

// Wait for the requests to complete, even if some of them fail
$responses = Promise\Utils::settle($promises)->wait();

// Values returned above are wrapped in an array with 2 keys: "state" (either fulfilled or rejected) and "value" (contains the response)
echo $responses['image']['state']; // returns "fulfilled"
echo $responses['image']['value']->getHeader('Content-Length')[0];
echo $responses['png']['value']->getHeader('Content-Length')[0];

Vous pouvez utiliser l'objet GuzzleHttp\Pool lorsque vous avez un nombre indéterminé de demandes à envoyer.

use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;
use GuzzleHttp\Pool;
use GuzzleHttp\Psr7\Request;
use GuzzleHttp\Psr7\Response;

$client = new Client();

$requests = function ($total) {
    $uri = 'http://127.0.0.1:8126/guzzle-server/perf';
    for ($i = 0; $i < $total; $i++) {
        yield new Request('GET', $uri);
    }
};

$pool = new Pool($client, $requests(100), [
    'concurrency' => 5,
    'fulfilled' => function (Response $response, $index) {
        // this is delivered each successful response
    },
    'rejected' => function (RequestException $reason, $index) {
        // this is delivered each failed request
    },
]);

// Initiate the transfers and create a promise
$promise = $pool->promise();

// Force the pool of requests to complete.
$promise->wait();

Ou utiliser une fermeture qui renverra une promesse une fois que le pool aura appelé la fermeture.

$client = new Client();

$requests = function ($total) use ($client) {
    $uri = 'http://127.0.0.1:8126/guzzle-server/perf';
    for ($i = 0; $i < $total; $i++) {
        yield function() use ($client, $uri) {
            return $client->getAsync($uri);
        };
    }
};

$pool = new Pool($client, $requests(100));

Utilisation des réponses

Dans les exemples précédents, nous avons récupéré une variable $response ou nous avons été réponse à partir d'une promesse. L'objet response implémente une réponse PSR-7 réponse, Psr\Http\Message\ResponseInterface, et contient un grand nombre de informations utiles.

Vous pouvez obtenir le code d'état et la phrase de raison de la réponse :

$code = $response->getStatusCode(); // 200
$reason = $response->getReasonPhrase(); // OK

Vous pouvez récupérer les en-têtes de la réponse :

// Check if a header exists.
if ($response->hasHeader('Content-Length')) {
    echo "It exists";
}

// Get a header from the response.
echo $response->getHeader('Content-Length')[0];

// Get all of the response headers.
foreach ($response->getHeaders() as $name => $values) {
    echo $name . ': ' . implode(', ', $values) . "\r\n";
}

Le corps d'une réponse peut être récupéré à l'aide de la méthode getBody. Le corps peut être utilisé comme une chaîne de caractères, converti en une chaîne de caractères ou utilisé comme un objet de type flux.

$body = $response->getBody();
// Implicitly cast the body to a string and echo it
echo $body;
// Explicitly cast the body to a string
$stringBody = (string) $body;
// Read 10 bytes from the body
$tenBytes = $body->read(10);
// Read the remaining contents of the body as a string
$remainingBytes = $body->getContents();

Paramètres des chaînes de requête

Vous pouvez fournir des paramètres de chaîne de requête avec une requête de plusieurs façons.

Vous pouvez définir les paramètres de la chaîne de requête dans l'URI de la demande :

$response = $client->request('GET', 'http://httpbin.org?foo=bar');

Vous pouvez spécifier les paramètres de la chaîne de requête en utilisant l'option de requête query sous forme de tableau.

$client->request('GET', 'http://httpbin.org', [
    'query' => ['foo' => 'bar']
]);

Si l'option est fournie sous forme de tableau, la fonction http_build_query de PHP sera utilisée pour formater la chaîne de requête.

Et enfin, vous pouvez fournir l'option de requête query sous forme de chaîne.

$client->request('GET', 'http://httpbin.org', ['query' => 'foo=bar']);

Téléchargement des données

Guzzle propose plusieurs méthodes pour télécharger des données.

Vous pouvez envoyer des requêtes qui contiennent un flux de données en passant une chaîne, ressource retournée par fopen, ou une instance d'une Psr\Http\Message\StreamInterface à l'option de requête body.

use GuzzleHttp\Psr7;

// Provide the body as a string.
$r = $client->request('POST', 'http://httpbin.org/post', [
    'body' => 'raw data'
]);

// Provide an fopen resource.
$body = Psr7\Utils::tryFopen('/path/to/file', 'r');
$r = $client->request('POST', 'http://httpbin.org/post', ['body' => $body]);

// Use the Utils::streamFor method to create a PSR-7 stream.
$body = Psr7\Utils::streamFor('hello!');
$r = $client->request('POST', 'http://httpbin.org/post', ['body' => $body]);

Un moyen simple de télécharger des données JSON et de définir l'en-tête approprié consiste à utiliser l'option de requête json :

$r = $client->request('PUT', 'http://httpbin.org/put', [
    'json' => ['foo' => 'bar']
]);

POST/Demandes de formulaires

Outre la possibilité de spécifier les données brutes d'une requête à l'aide de l'option de requête body, Guzzle fournit des abstractions utiles pour l'envoi de données POST.

Envoi de champs de formulaire

Pour envoyer des requêtes POST application/x-www-form-urlencoded, vous devez spécifier les champs POST sous forme de tableau dans les options de requête form_params.

$response = $client->request('POST', 'http://httpbin.org/post', [
    'form_params' => [
        'field_name' => 'abc',
        'other_field' => '123',
        'nested_field' => [
            'nested' => 'hello'
        ]
    ]
]);

Envoi de fichiers de formulaire

Vous pouvez envoyer des fichiers avec un formulaire (multipart/form-data requêtes POST), en utilisant l'option de requête multipart. Le multipart accepte un tableau de tableaux associatifs, où chaque tableau associatif contient les clés suivantes :

  • name : (obligatoire, chaîne de caractères) mappage de la clé avec le nom du champ du formulaire.
  • contenu : (obligatoire, mixte) Fournir une chaîne pour envoyer le contenu du fichier sous la forme d'une chaîne, fournir une ressource fopen pour transmettre le contenu d'un flux PHP, ou fournir une Psr\Http\Message\StreamInterface pour transmettre le contenu d'un flux le contenu d'un flux PSR-7.
use GuzzleHttp\Psr7;

$response = $client->request('POST', 'http://httpbin.org/post', [
    'multipart' => [
        [
            'name'     => 'field_name',
            'contents' => 'abc'
        ],
        [
            'name'     => 'file_name',
            'contents' => Psr7\Utils::tryFopen('/path/to/file', 'r')
        ],
        [
            'name'     => 'other_file',
            'contents' => 'hello',
            'filename' => 'filename.txt',
            'headers'  => [
                'X-Foo' => 'this is an extra header to include'
            ]
        ]
    ]
]);

Cookies

Guzzle peut maintenir une session de cookies pour vous si vous le demandez à l'aide de l'option de requête cookies option de requête. Lors de l'envoi d'une demande, l'option cookies doit être définie comme une instance de . doit être définie comme une instance de GuzzleHttp\Cookie\CookieJarInterface.

// Use a specific cookie jar
$jar = new \GuzzleHttp\Cookie\CookieJar;
$r = $client->request('GET', 'http://httpbin.org/cookies', [
    'cookies' => $jar
]);

Vous pouvez définir cookies à true dans un constructeur client si vous souhaitez utiliser une boîte à cookies partagée pour toutes les demandes.

// Use a shared client cookie jar
$client = new \GuzzleHttp\Client(['cookies' => true]);
$r = $client->request('GET', 'http://httpbin.org/cookies');

Différentes implémentations existent pour la GuzzleHttp\Cookie\CookieJarInterface :

  • La classe GuzzleHttp\Cookie\CookieJar stocke les cookies sous forme de tableau.
  • La classe GuzzleHttp\Cookie\FileCookieJar fait persister les cookies non liés à la session en utilisant un fichier au format JSON.
  • La classe GuzzleHttp\Cookie\SessionCookieJar fait persister les cookies dans la session du client.

Vous pouvez placer manuellement des cookies dans une boîte à cookies avec le constructeur nommé fromArray(array $cookies, $domain).

$jar = \GuzzleHttp\Cookie\CookieJar::fromArray(
    [
        'some_cookie' => 'foo',
        'other_cookie' => 'barbaz1234'
    ],
    'example.org'
);

Vous pouvez obtenir un cookie par son nom avec la méthode getCookieByName($name) qui renvoie une instance GuzzleHttp\Cookie\SetCookie.

$cookie = $jar->getCookieByName('some_cookie');

$cookie->getValue(); // 'foo'
$cookie->getDomain(); // 'example.org'
$cookie->getExpires(); // expiration date as a Unix timestamp

Les cookies peuvent également être récupérés dans un tableau grâce à la méthode toArray(). L'interface GuzzleHttp\Cookie\CookieJarInterface étend Traversable afin qu'elle puisse être itérée dans une boucle foreach.

Redirections

Guzzle suit automatiquement les redirections, sauf si vous lui demandez de ne pas le faire. Vous pouvez personnaliser le comportement des redirections à l'aide de l'option de requête allow_redirects.

  • Défini à true pour activer les redirections normales avec un nombre maximal de 5 redirections. Il s'agit du paramètre par défaut.
  • Défini à false pour désactiver les redirections.
  • Passer un tableau associatif contenant la clé 'max' pour spécifier le nombre maximum de maximum de redirections et, éventuellement, une valeur de clé 'strict' pour spécifier l'utilisation ou non de redirections strictes conformes à la RFC (c'est-à-dire rediriger les demandes POST avec des requêtes POST plutôt que de faire ce que la plupart des navigateurs font, à savoir rediriger les requêtes POST avec les requêtes GET).
$response = $client->request('GET', 'http://github.com');
echo $response->getStatusCode();
// 200

L'exemple suivant montre que les redirections peuvent être désactivées.

$response = $client->request('GET', 'http://github.com', [
    'allow_redirects' => false
]);
echo $response->getStatusCode();
// 301

Exceptions

Vue de l'arbre

L'arborescence suivante décrit comment les exceptions Guzzle dépendent les unes des autres.

. \RuntimeException
└── TransferException (implements GuzzleException)
    ├── ConnectException (implements NetworkExceptionInterface)
    └── RequestException
        ├── BadResponseException
        │   ├── ServerException
        │   └── ClientException
        └── TooManyRedirectsException

Guzzle lance des exceptions pour les erreurs qui se produisent pendant un transfert.

  • Une exception GuzzleHttp\Exception\ConnectException est levée en cas d'erreur de réseau. en cas d'erreur de réseau. Cette exception s'étend de GuzzleHttp\Exception\TransferException.

  • Une GuzzleHttp\Exception\ClientException est déclenchée pour les erreurs de niveau 400 si l'option de requête http_errors a la valeur true. Cette exception exception s'étend à partir de GuzzleHttp\Exception\BadResponseException et de GuzzleHttp\Exception\BadResponseException s'étend de GuzzleHttp\Exception\RequestException.

    utiliser GuzzleHttp\Psr7 ;
    utiliser GuzzleHttp\Exception\ClientException ;
    
    try {
        $client->request('GET', 'https://github.com/_abc_123_404') ;
    } catch (ClientException $e) {
        echo Psr7\Message::toString($e->getRequest()) ;
        echo Psr7\Message::toString($e->getResponse()) ;
    }
    
  • Une GuzzleHttp\Exception\ServerException est lancée pour les erreurs de niveau 500 si l'option de requête http_errors a la valeur true. Cette exception exception s'étend de GuzzleHttp\Exception\BadResponseException.

  • Une GuzzleHttp\Exception\TooManyRedirectsException est lancée lorsque trop de trop de redirections sont suivies. Cette exception est une extension de GuzzleHttp\Exception\RequestException.

Toutes les exceptions ci-dessus sont issues de GuzzleHttp\Exception\TransferException.

Variables d'environnement

Guzzle expose quelques variables d'environnement qui peuvent être utilisées pour personnaliser le comportement de la bibliothèque.

GUZZLE_CURL_SELECT_TIMEOUT
Contrôle la durée en secondes qu'un gestionnaire curl_multi_* utilisera lors de la sélectionne sur les handles curl en utilisant curl_multi_select(). Certains systèmes ont des problèmes avec l'implémentation de PHP de la fonction curl_multi_select() où l'appel de cette fonction entraîne toujours une attente pendant la durée maximale du le délai d'attente.
HTTP_PROXY

Définit le proxy à utiliser lors de l'envoi de requêtes utilisant le protocole "http".

Remarque : comme la variable HTTP_PROXY peut contenir des entrées utilisateur arbitraires dans certains environnements (CGI), elle n'est utilisée que dans l'interface CLI SAPI. Voir https://httpoxy.org pour plus d'informations.

HTTPS_PROXY
Définit le proxy à utiliser lors de l'envoi de requêtes utilisant le protocole "https".
NO_PROXY
Définit les URL pour lesquelles un proxy ne doit pas être utilisé. Voir proxy pour l'utilisation.

Paramètres ini pertinents

Guzzle peut utiliser les paramètres PHP ini lors de la configuration des clients.

openssl.cafile
Spécifie le chemin d'accès sur le disque à un fichier CA au format PEM à utiliser lors de l'envoi de des requêtes via "https". Voir : https://wiki.php.net/rfc/tls-peer-verification#phpini_defaults