Ta strona zawiera szybkie wprowadzenie do Guzzle'a oraz przykłady wprowadzające. Jeśli jeszcze nie zainstalowałeś Guzzle'a, przejdź na stronę Instalacja stronę.
Zapytania do Guzzle'a można wysyłać za pomocą obiektu GuzzleHttpClientInterface
.
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,
]);
Klienci są niezmienne w Guzzle, co oznacza, że nie możesz zmienić domyślnych ustawień klienta po jego utworzeniu.
Konstruktor klienta przyjmuje tablicę asocjacyjną z opcjami:
base_uri
(string|UriInterface) Bazowy URI klienta, który jest łączony z relatywnymi URI. Może być ciągiem znaków lub instancją UriInterface. Gdy względny URI jest dostarczony do klienta, klient połączy bazowy URI z względnym URI, używając reguł opisanych w RFC 3986, sekcja 5.2.
// Utwórz klienta z bazowym URI
$client = new GuzzleHttp\Client(['base_uri' => 'https://foo.com/api/']);
// Wyślij żądanie do https://foo.com/api/test
$response = $client->request('GET', 'test');
// Wyślij żądanie do https://foo.com/root
$response = $client->request('GET', '/root');
Nie masz ochoty czytać RFC 3986? Oto kilka szybkich przykładów, jak base_uri
jest rozwiązywany z innym URI.
base_uri | URI | URI | Result | Result |
---|---|---|---|---|
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
i tablicą
opcji transferu, i musi zwrócić
GuzzleHttpPromisePromiseInterface
, który jest spełniony za pomocą
Psr7Http\Message\ResponseInterface
w przypadku sukcesu....
Metody magiczne na kliencie ułatwiają wysyłanie synchronicznych żądań:
$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');
Możesz utworzyć żądanie, a następnie wysłać je z klientem, gdy będziesz gotowy:
use GuzzleHttp\Psr7\Request;
$request = new Request('PUT', 'http://httpbin.org/put');
$response = $client->send($request, ['timeout' => 2]);
Obiekty klienckie zapewniają dużą elastyczność w sposobie przekazywania żądań w tym domyślne opcje żądania, domyślne oprogramowanie pośredniczące stosu obsługi które są używane przez każde żądanie, oraz bazowy URI, który pozwala na wysyłanie żądań z relatywnymi URI.
Możesz dowiedzieć się więcej o klienckim oprogramowaniu pośredniczącym w Handlers and Middleware stronie dokumentacji.
Możesz wysyłać asynchroniczne żądania używając magicznych metod dostarczanych przez klienta:
$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');
Możesz również użyć metod sendAsync() i requestAsync() klienta:
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');
Obietnica zwracana przez te metody implementuje specyfikację
Promises/A+ spec, dostarczoną przez
bibliotekę obietnic Guzzle. Oznacza to.
że z obietnicy można utworzyć łańcuch then()
wywołań. Te wywołania then są
spełnione z powodzeniem Psr\Message\ResponseInterface
lub
odrzucony z wyjątkiem.
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();
}
);
Możesz wysyłać wiele żądań jednocześnie używając obietnic i żądań asynchronicznych.
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];
Możesz użyć obiektu GuzzleHttpPool
, gdy masz nieokreśloną ilość żądań, które chcesz wysłać.
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();
Lub używając zamknięcia, które zwróci obietnicę, gdy pula wywoła zamknięcie.
$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));
W poprzednich przykładach, pobieraliśmy zmienną $response
lub byliśmy
dostarczono nam odpowiedź z obietnicy. Obiekt response implementuje PSR-7
odpowiedź, Psr\Message\ResponseInterface
, i zawiera wiele
pomocnych informacji.
Możesz uzyskać kod statusu i uzasadnienie odpowiedzi:
$code = $response->getStatusCode(); // 200
$reason = $response->getReasonPhrase(); // OK
Możesz pobrać nagłówki z odpowiedzi:
// 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";
}
Ciało odpowiedzi może zostać pobrane za pomocą metody getBody
. Ciało może być użyte jako ciąg znaków, rzutowane na ciąg znaków lub użyte jako obiekt podobny do strumienia.
$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();
Możesz dostarczyć parametry łańcucha zapytania wraz z żądaniem na kilka sposobów.
Możesz ustawić parametry łańcucha zapytania w URI żądania:
$response = $client->request('GET', 'http://httpbin.org?foo=bar');
Parametry łańcucha zapytania można określić za pomocą opcji żądania query
jako tablicę.
$client->request('GET', 'http://httpbin.org', [
'query' => ['foo' => 'bar']
]);
Podanie opcji w postaci tablicy spowoduje użycie funkcji PHP http_build_query
do sformatowania łańcucha zapytania.
I wreszcie, możesz podać opcję żądania query
jako ciąg znaków.
$client->request('GET', 'http://httpbin.org', ['query' => 'foo=bar']);
Guzzle udostępnia kilka metod przesyłania danych.
Możesz wysyłać żądania, które zawierają strumień danych poprzez przekazanie łańcucha znaków,
zasób zwrócony z fopen
, lub instancję Psr
Psr\Message\StreamInterface
do opcji body
żądania.
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]);
Łatwym sposobem na przesłanie danych JSON i ustawienie odpowiedniego nagłówka jest użycie opcji żądania json
:
$r = $client->request('PUT', 'http://httpbin.org/put', [
'json' => ['foo' => 'bar']
]);
Oprócz określania surowych danych żądania za pomocą opcji body
, Guzzle dostarcza pomocnych abstrakcji do wysyłania danych POST.
Wysyłanie żądań application/x-www-form-urlencoded
POST wymaga określenia pól POST jako tablicy w opcjach żądania form_params
.
$response = $client->request('POST', 'http://httpbin.org/post', [
'form_params' => [
'field_name' => 'abc',
'other_field' => '123',
'nested_field' => [
'nested' => 'hello'
]
]
]);
Możesz wysyłać pliki wraz z formularzem (multipart/form-data
żądania POST),
używając opcji multipart
żądania. multipart
przyjmuje tablicę
tablic asocjacyjnych, gdzie każda tablica asocjacyjna zawiera następujące klucze:
Psr\Http\Message\StreamInterface
do strumienia
zawartość z 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 może utrzymywać dla Ciebie sesję cookie, jeśli zostaniesz o tym poinformowany za pomocą opcji
cookies
opcji żądania. Podczas wysyłania żądania, opcja cookies
musi być ustawiona na instancję GuzzleHttpCookieJarInterface
.
// Use a specific cookie jar
$jar = new \GuzzleHttp\Cookie\CookieJar;
$r = $client->request('GET', 'http://httpbin.org/cookies', [
'cookies' => $jar
]);
Możesz ustawić cookies
na true
w konstruktorze klienta, jeśli chcesz użyć wspólnego słoika z ciasteczkami dla wszystkich żądań.
// Use a shared client cookie jar
$client = new \GuzzleHttp\Client(['cookies' => true]);
$r = $client->request('GET', 'http://httpbin.org/cookies');
Istnieją różne implementacje dla GuzzleHttp\CookieJarInterface
:
GuzzleHttp\Cookie\CookieJar
przechowuje ciasteczka jako tablicę.GuzzleHttpFileCookieJar
przechowuje pliki cookie nie będące plikami sesyjnymi
za pomocą pliku w formacie JSON.GuzzleHttp\Cookie\SessionCookieJar
przechowuje ciasteczka w sesji klienta.
sesji klienta.Możesz ręcznie ustawić ciasteczka w słoiku z ciasteczkami za pomocą nazwanego konstruktora fromArray(array $cookies, $domain)
.
$jar = \GuzzleHttp\Cookie\CookieJar::fromArray(
[
'some_cookie' => 'foo',
'other_cookie' => 'barbaz1234'
],
'example.org'
);
Możesz uzyskać plik cookie po jego nazwie za pomocą metody getCookieByName($name)
, która zwraca instancję GuzzleHttp\Cookie\SetCookie
.
$cookie = $jar->getCookieByName('some_cookie');
$cookie->getValue(); // 'foo'
$cookie->getDomain(); // 'example.org'
$cookie->getExpires(); // expiration date as a Unix timestamp
Ciasteczka mogą być również pobierane do tablicy dzięki metodzie toArray().
Interfejs GuzzleHttpCookieJarInterface
rozszerza.
Traversable
, więc można go iterować w pętli foreach.
Guzzle będzie automatycznie podążał za przekierowaniami, chyba że zabronisz mu tego. Możesz dostosować zachowanie przekierowań, używając opcji żądania allow_redirects
.
true
, aby włączyć normalne przekierowania z maksymalną liczbą 5
przekierowań. Jest to ustawienie domyślne.false
aby wyłączyć przekierowania.$response = $client->request('GET', 'http://github.com');
echo $response->getStatusCode();
// 200
Poniższy przykład pokazuje, że przekierowania mogą być wyłączone.
$response = $client->request('GET', 'http://github.com', [
'allow_redirects' => false
]);
echo $response->getStatusCode();
// 301
Widok drzewa
Poniższy widok drzewa opisuje, w jaki sposób wyjątki Guzzle'a zależą od siebie nawzajem.
. \RuntimeException
└── TransferException (implements GuzzleException)
├── ConnectException (implements NetworkExceptionInterface)
└── RequestException
├── BadResponseException
│ ├── ServerException
│ └── ClientException
└── TooManyRedirectsException
Guzzle rzuca wyjątkami dla błędów, które wystąpią podczas transferu.
Wyjątek GuzzleHttpConnectException
jest rzucany w
w przypadku wystąpienia błędu sieciowego. Wyjątek ten wywodzi się z
code class="docutils literal">GuzzleHttpException.
Wyjątek GuzzleHttp
jest rzucany dla błędów poziomu 400
jeśli opcja żądania http_errors
jest ustawiona na true. Ten
wywodzi się z wyjątków GuzzleHttp\Exception\BadResponseException
oraz GuzzleHttp\Exception.
GuzzleHttp\Exception\BadResponseException
extends from
GuzzleHttp\Exception\RequestException
.
użyj GuzzleHttp
Wyjątek GuzzleHttp
jest rzucany dla błędów poziomu 500
błędów, jeśli opcja żądania http_errors
jest ustawiona na true. Ten
wywodzi się z wyjątku GuzzleHttp\Exception\BadResponseException
.
A GuzzleHttpExceptionTooManyRedirectsException
jest rzucany, gdy zbyt
zbyt wiele przekierowań. Wyjątek ten rozszerza się z GuzzleHttpException
.
Wszystkie powyższe wyjątki pochodzą z GuzzleHttpException
.
Guzzle udostępnia kilka zmiennych środowiskowych, które mogą być użyte do dostosowania zachowania biblioteki.
GUZZLE_CURL_SELECT_TIMEOUT
curl_multi_select()
. Niektóre systemy
mają problemy z implementacją w PHP curl_multi_select()
, gdzie
wywołanie tej funkcji zawsze powoduje oczekiwanie przez maksymalny czas trwania
timeout.HTTP_PROXY
Określa proxy do użycia podczas wysyłania żądań przy użyciu protokołu "http".
Uwaga: ponieważ zmienna HTTP_PROXY może zawierać arbitralne dane wejściowe użytkownika w niektórych środowiskach (CGI), zmienna ta jest używana tylko w CLI SAPI. Zobacz https://httpoxy.org po więcej informacji.
HTTPS_PROXY
NO_PROXY
Guzzle może wykorzystywać ustawienia PHP ini podczas konfigurowania klientów.
openssl.cafile