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.
Vous pouvez envoyer des demandes avec Guzzle en utilisant un objet GuzzleHttp\ClientInterface
.
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
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....
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.
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();
}
);
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));
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();
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']);
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']
]);
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.
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'
]
]
]);
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 :
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'
]
]
]
]);
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
:
GuzzleHttp\Cookie\CookieJar
stocke les cookies sous forme de tableau.GuzzleHttp\Cookie\FileCookieJar
fait persister les cookies non liés à la session
en utilisant un fichier au format JSON.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.
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
.
true
pour activer les redirections normales avec un nombre maximal de 5
redirections. Il s'agit du paramètre par défaut.false
pour désactiver les redirections.$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
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
.
Guzzle expose quelques variables d'environnement qui peuvent être utilisées pour personnaliser le comportement de la bibliothèque.
GUZZLE_CURL_SELECT_TIMEOUT
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
NO_PROXY
Guzzle peut utiliser les paramètres PHP ini lors de la configuration des clients.
openssl.cafile