Táto stránka obsahuje stručný úvod do aplikácie Guzzle a úvodné príklady. Ak ste ešte Guzzle nenainštalovali, prejdite na stránku Inštalácia stránku.
Pomocou Guzzle môžete posielať požiadavky pomocou objektu 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,
]);
Klienti sú v systéme Guzzle nemenní, čo znamená, že po vytvorení klienta nemôžete zmeniť jeho predvolené nastavenia.
Konštruktor klienta prijíma asociatívne pole možností:
base_uri
(string|UriInterface) Základný URI klienta, ktorý je zlúčený do relatívneho URI. Môže to byť reťazec alebo inštancia UriInterface. Keď sa relatívny URI sa klientovi poskytne základný URI, klient spojí základný URI s relatívnym URI pomocou pravidiel opísaných v časti RFC 3986, časť 5.2
// Vytvorenie klienta so základným URI
$client = new GuzzleHttp\Client(['base_uri' => 'https://foo.com/api/']);
// Odoslanie požiadavky na adresu https://foo.com/api/test
$response = $client->request('GET', 'test');
// Odoslanie požiadavky na adresu https://foo.com/root
$response = $client->request('GET', '/root');
Nechce sa vám čítať RFC 3986? Tu je niekoľko rýchlych príkladov, ako sa base_uri
vyrieši pomocou iného URI.
base_uri | URI | Výsledok |
---|---|---|
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
a poľa
možností prenosu a musí vrátiť
GuzzleHttp\Promise\PromiseInterface
, ktorý je splnený pomocou
Psr7\Http\Message\ResponseInterface
v prípade úspechu....
Magické metódy na klientovi uľahčujú odosielanie synchrónnych požiadaviek:
$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');
Môžete vytvoriť požiadavku a potom ju poslať spolu s klientom, keď budete pripravení:
use GuzzleHttp\Psr7\Request;
$request = new Request('PUT', 'http://httpbin.org/put');
$response = $client->send($request, ['timeout' => 2]);
Klientské objekty poskytujú veľkú flexibilitu v tom, ako sú požiadavky vrátane predvolených možností požiadaviek, predvoleného obslužného middleware zásobníka ktoré sa používajú pri každej požiadavke, a základného URI, ktorý umožňuje odosielať požiadavky s relatívnymi URI.
Viac informácií o klientskom middleware nájdete na stránke Handlers and Middleware dokumentácie.
Asynchrónne požiadavky môžete odosielať pomocou magických metód, ktoré poskytuje klient:
$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');
Môžete tiež použiť metódy sendAsync() a 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');
Prísľub vrátený týmito metódami implementuje
špecifikáciu Promises/A+, ktorú poskytuje
Guzzle promises library. To znamená, že
že môžete reťaziť then()
volania z prísľubu. Tieto volania then sú
buď splnené úspešným Psr\Http\Message\ResponseInterface
alebo
odmietnuté s výnimkou.
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();
}
);
Pomocou sľubov a asynchrónnych požiadaviek môžete posielať viacero požiadaviek súčasne.
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];
Objekt GuzzleHttp\Pool
môžete použiť, ak máte neurčitý počet požiadaviek, ktoré chcete odoslať.
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();
Alebo pomocou uzáveru, ktorý vráti prísľub, keď fond zavolá uzáver.
$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));
V predchádzajúcich príkladoch sme získali premennú $response
alebo sme
doručená odpoveď z prísľubu. Objekt response implementuje PSR-7
response, Psr\Http\Message\ResponseInterface
, a obsahuje množstvo
užitočných informácií.
Môžete získať stavový kód a dôvodovú frázu odpovede:
$code = $response->getStatusCode(); // 200
$reason = $response->getReasonPhrase(); // OK
Z odpovede môžete získať hlavičky:
// 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";
}
Telo odpovede možno získať pomocou metódy getBody
. Telo možno použiť ako reťazec, previesť na reťazec alebo použiť ako objekt typu stream.
$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();
Parametre reťazca dopytu môžete pri požiadavke poskytnúť niekoľkými spôsobmi.
Parametre reťazca dopytu môžete nastaviť v URI požiadavky:
$response = $client->request('GET', 'http://httpbin.org?foo=bar');
Parametre reťazca dotazu môžete zadať pomocou možnosti query
požiadavky ako pole.
$client->request('GET', 'http://httpbin.org', [
'query' => ['foo' => 'bar']
]);
Poskytnutie možnosti ako poľa použije funkciu PHP http_build_query
na formátovanie reťazca dotazu.
A nakoniec môžete zadať možnosť požiadavky query
ako reťazec.
$client->request('GET', 'http://httpbin.org', ['query' => 'foo=bar']);
Aplikácia Guzzle poskytuje niekoľko metód na nahrávanie údajov.
Požiadavky, ktoré obsahujú prúd údajov, môžete odoslať odovzdaním reťazca,
zdroj vrátený z fopen
alebo inštanciu
Psr\Http\Message\StreamInterface
k možnosti body
požiadavky.
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]);
Jednoduchým spôsobom, ako nahrať údaje JSON a nastaviť príslušnú hlavičku, je použitie možnosti požiadavky json
:
$r = $client->request('PUT', 'http://httpbin.org/put', [
'json' => ['foo' => 'bar']
]);
Okrem špecifikácie surových údajov požiadavky pomocou možnosti body
požiadavky poskytuje Guzzle užitočné abstrakcie pre odosielanie údajov POST.
Odosielanie application/x-www-form-urlencoded
POST požiadaviek vyžaduje, aby ste zadali POST polia ako pole v form_params
možnostiach požiadavky.
$response = $client->request('POST', 'http://httpbin.org/post', [
'form_params' => [
'field_name' => 'abc',
'other_field' => '123',
'nested_field' => [
'nested' => 'hello'
]
]
]);
Spolu s formulárom môžete odoslať súbory (multipart/form-data
POST požiadavky),
pomocou možnosti multipart
request. multipart
akceptuje pole
asociatívnych polí, pričom každé asociatívne pole obsahuje nasledujúce kľúče:
Psr\Http\Message\StreamInterface
na streamovanie
obsah z prúdu 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 môže udržiavať reláciu súborov cookie, ak dostanete pokyn pomocou
cookies
možnosť požiadavky. Pri odosielaní požiadavky sa použije možnosť cookies
musí byť nastavená na inštanciu GuzzleHttp\Cookie\CookieJarInterface
.
// Use a specific cookie jar
$jar = new \GuzzleHttp\Cookie\CookieJar;
$r = $client->request('GET', 'http://httpbin.org/cookies', [
'cookies' => $jar
]);
Ak chcete použiť zdieľanú nádobu na súbory cookie pre všetky požiadavky, môžete nastaviť cookies
na true
v konštruktore klienta.
// Use a shared client cookie jar
$client = new \GuzzleHttp\Client(['cookies' => true]);
$r = $client->request('GET', 'http://httpbin.org/cookies');
Pre GuzzleHttp\Cookie\CookieJarInterface
existujú rôzne implementácie:
GuzzleHttp\Cookie\CookieJar
ukladá cookies ako pole.GuzzleHttp\Cookie\FileCookieJar
uchováva súbory cookie, ktoré nie sú súčasťou relácie
pomocou súboru vo formáte JSON.GuzzleHttp\Cookie\SessionCookieJar
uchováva súbory cookie v
relácii klienta.Súbory cookie môžete ručne nastaviť do nádoby na súbory cookie pomocou pomenovaného konštruktora fromArray(array $cookies, $domain)
.
$jar = \GuzzleHttp\Cookie\CookieJar::fromArray(
[
'some_cookie' => 'foo',
'other_cookie' => 'barbaz1234'
],
'example.org'
);
Súbor cookie môžete získať podľa jeho názvu pomocou metódy getCookieByName($name)
, ktorá vráti inštanciu GuzzleHttp\Cookie\SetCookie
.
$cookie = $jar->getCookieByName('some_cookie');
$cookie->getValue(); // 'foo'
$cookie->getDomain(); // 'example.org'
$cookie->getExpires(); // expiration date as a Unix timestamp
Súbory cookie možno tiež načítať do poľa vďaka metóde toArray().
Rozhranie GuzzleHttp\Cookie\CookieJarInterface
rozširuje
Traversable
, takže ho možno iterovať v cykle foreach.
Aplikácia Guzzle bude automaticky sledovať presmerovania, pokiaľ jej to nepoviete. Správanie presmerovania môžete prispôsobiť pomocou možnosti allow_redirects
požiadavky.
true
, aby ste povolili normálne presmerovania s maximálnym počtom 5
presmerovaní. Toto je predvolené nastavenie.false
pre vypnutie presmerovania.$response = $client->request('GET', 'http://github.com');
echo $response->getStatusCode();
// 200
Nasledujúci príklad ukazuje, že presmerovanie môže byť zakázané.
$response = $client->request('GET', 'http://github.com', [
'allow_redirects' => false
]);
echo $response->getStatusCode();
// 301
Zobrazenie stromu
Nasledujúce stromové zobrazenie opisuje, ako výnimky Guzzle navzájom závisia.
. \RuntimeException
└── TransferException (implements GuzzleException)
├── ConnectException (implements NetworkExceptionInterface)
└── RequestException
├── BadResponseException
│ ├── ServerException
│ └── ClientException
└── TooManyRedirectsException
Guzzle vyhodí výnimky v prípade chýb, ktoré sa vyskytnú počas prenosu.
Výnimka GuzzleHttp\Exception\ConnectException
je vyhodená v
v prípade chyby v sieti. Táto výnimka sa rozširuje z
GuzzleHttp\Exception\TransferException
.
Je vyhodená GuzzleHttp\Exception\ClientException
pre 400
úrovne, ak je možnosť http_errors
požiadavky nastavená na true. Táto
sa rozširuje z GuzzleHttp\Exception\BadResponseException
a
GuzzleHttp\Exception\BadResponseException
rozširuje z
GuzzleHttp\Exception\RequestException
.
use GuzzleHttp\Psr7;
use 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());
}
Je vyhodená GuzzleHttp\Exception\ServerException
pre úroveň 500
ak je možnosť http_errors
požiadavky nastavená na true. Táto
sa rozširuje z GuzzleHttp\Exception\BadResponseException
.
Výnimka GuzzleHttp\Exception\TooManyRedirectsException
je vyhodená, keď je príliš veľa
nasleduje príliš veľa presmerovaní. Táto výnimka sa rozširuje z GuzzleHttp\Exception\RequestException
.
Všetky vyššie uvedené výnimky sa rozširujú z GuzzleHttp\Exception\TransferException
.
Guzzle ponúka niekoľko premenných prostredia, ktoré možno použiť na prispôsobenie správania knižnice.
GUZZLE_CURL_SELECT_TIMEOUT
curl_multi_select()
. Niektoré systémy
majú problémy s implementáciou curl_multi_select()
v PHP, kde
volanie tejto funkcie vždy vedie k čakaniu na maximálne trvanie
časového limitu.HTTP_PROXY
Definuje proxy server, ktorý sa má použiť pri odosielaní požiadaviek pomocou protokolu "http"
Poznámka: pretože premenná HTTP_PROXY môže v niektorých prostrediach (CGI) obsahovať ľubovoľný vstup používateľa, premenná sa používa len v CLI SAPI. Viac informácií nájdete v https://httpoxy.org.
HTTPS_PROXY
NO_PROXY
Guzzle môže pri konfigurácii klientov využívať nastavenia PHP ini.
openssl.cafile