Denne side indeholder en hurtig introduktion til Guzzle og indledende eksempler. Hvis du ikke allerede har installeret Guzzle, kan du gå over til Installation side.
Du kan sende anmodninger med Guzzle ved hjælp af et GuzzleHttp\ClientInterface
objekt.
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,
]);
Klienter er uforanderlige i Guzzle, hvilket betyder, at du ikke kan ændre de standardindstillinger, der anvendes af en klient, efter at den er oprettet.
Klientkonstruktøren accepterer et associerende array af indstillinger:
base_uri
(string|UriInterface) Basis-URI for den klient, der er slået sammen til relativ URI'er. Kan være en streng eller en instans af UriInterface. Når en relativ URI leveres til en klient, vil klienten kombinere basis-URI'en med den relative URI ved hjælp af de regler, der er beskrevet i RFC 3986, afsnit 5.2.
// Opret en klient med en basis-URI
$client = new GuzzleHttp\Client(['base_uri' => 'https://foo.com/api/']);
// Send en anmodning til https://foo.com/api/test
$response = $client->request('GET', 'test');
// Send en anmodning til https://foo.com/root
$response = $client->request('GET', '/root');
Har du ikke lyst til at læse RFC 3986? Her er nogle hurtige eksempler på, hvordan en base_uri
opløses med en anden URI.
base_uri | URI | Resultat | |
---|---|---|---|
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
og array
af overførselsmuligheder, og skal returnere en
GuzzleHttp\Promise\PromiseInterface
, der er opfyldt med en
Psr7\Http\Message\ResponseInterface
ved succes....
Magiske metoder på klienten gør det nemt at sende synkrone anmodninger:
$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');
Du kan oprette en anmodning og derefter sende anmodningen med klienten, når du er klar:
use GuzzleHttp\Psr7\Request;
$request = new Request('PUT', 'http://httpbin.org/put');
$response = $client->send($request, ['timeout' => 2]);
Klientobjekter giver en stor fleksibilitet med hensyn til, hvordan anmodninger overføres, herunder standardforespørgselsindstillinger, standard håndtering af stak middleware der anvendes af hver anmodning, og en basis-URI, der gør det muligt at sende anmodninger med relative URI'er.
Du kan få mere at vide om klient-middleware på Handlers and Middleware siden i dokumentationen.
Du kan sende asynkrone anmodninger ved hjælp af de magiske metoder, der leveres af en 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');
Du kan også bruge sendAsync() og requestAsync() metoderne for en klient:
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');
Det løfte, der returneres af disse metoder, implementerer
Promises/A+ spec, som leveres af
Guzzle promises library. Det betyder
at du kan kæde then()
kald fra løftet. Disse then-opkald er
enten opfyldt med et vellykket Psr\Http\Message\ResponseInterface
eller
afvist med en undtagelse.
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();
}
);
Du kan sende flere anmodninger samtidig ved hjælp af løfter og asynkrone anmodninger.
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];
Du kan bruge GuzzleHttp\Pool
objektet, når du har et ubestemt antal anmodninger, som du ønsker at sende.
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();
Eller du kan bruge en lukning, der returnerer et løfte, når puljen kalder lukningen.
$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));
I de foregående eksempler hentede vi en $response
variabel, eller vi var
leveret et svar fra et løfte. Svarobjektet implementerer en PSR-7
respons, Psr\Http\Message\ResponseInterface
, og indeholder masser af
nyttige oplysninger.
Du kan få statuskoden og begrundelsen for svaret:
$code = $response->getStatusCode(); // 200
$reason = $response->getReasonPhrase(); // OK
Du kan hente overskrifter fra svaret:
// 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";
}
Kroppen af et svar kan hentes ved hjælp af getBody
metoden. Body'en kan bruges som en streng, kastes til en streng eller bruges som et stream-lignende objekt.
$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();
Du kan angive parametre for forespørgselsstrenge med en anmodning på flere måder.
Du kan angive parametre for forespørgselsstrenge i forespørgsels-URI'en:
$response = $client->request('GET', 'http://httpbin.org?foo=bar');
Du kan angive parametrene for forespørgselsstrengen ved hjælp af query
request option som et array.
$client->request('GET', 'http://httpbin.org', [
'query' => ['foo' => 'bar']
]);
Hvis du angiver indstillingen som et array, vil PHP's http_build_query
funktion blive brugt til at formatere forespørgselsstrengen.
Og endelig kan du angive query
request option som en streng.
$client->request('GET', 'http://httpbin.org', ['query' => 'foo=bar']);
Guzzle tilbyder flere metoder til at uploade data.
Du kan sende anmodninger, der indeholder en datastrøm, ved at sende en streng,
ressource returneret fra fopen
, eller en instans af en
Psr\Http\Message\StreamInterface
til body
anmodningsindstillingen.
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]);
En nem måde at uploade JSON-data og indstille den relevante header på er ved at bruge json
request option:
$r = $client->request('PUT', 'http://httpbin.org/put', [
'json' => ['foo' => 'bar']
]);
Ud over at angive de rå data i en anmodning ved hjælp af body
anmodningsindstillingen, tilbyder Guzzle nyttige abstraktioner for at sende POST-data.
Afsendelse af application/x-www-form-urlencoded
POST-anmodninger kræver, at du angiver POST-felterne som et array i form_params
anmodningsindstillingerne.
$response = $client->request('POST', 'http://httpbin.org/post', [
'form_params' => [
'field_name' => 'abc',
'other_field' => '123',
'nested_field' => [
'nested' => 'hello'
]
]
]);
Du kan sende filer sammen med en formular (multipart/form-data
POST-forespørgsler),
ved hjælp af multipart
request option. multipart
accepterer et array af
associerende arrays, hvor hvert associerende array indeholder følgende nøgler:
Psr\Http\Message\StreamInterface
til at streame
indholdet fra en PSR-7-stream.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 kan opretholde en cookie-session for dig, hvis du får instrukser om det ved hjælp af
cookies
anmodningsindstilling. Når du sender en anmodning, skal cookies
indstillingen cookies
skal være indstillet til en instans af GuzzleHttp\Cookie\CookieJarInterface
.
// Use a specific cookie jar
$jar = new \GuzzleHttp\Cookie\CookieJar;
$r = $client->request('GET', 'http://httpbin.org/cookies', [
'cookies' => $jar
]);
Du kan indstille cookies
til true
i en klientkonstruktør, hvis du ønsker at bruge en fælles cookiekrukke for alle anmodninger.
// Use a shared client cookie jar
$client = new \GuzzleHttp\Client(['cookies' => true]);
$r = $client->request('GET', 'http://httpbin.org/cookies');
Der findes forskellige implementeringer for GuzzleHttp\Cookie\CookieJarInterface
:
GuzzleHttp\Cookie\CookieJar
klassen gemmer cookies som et array.GuzzleHttp\Cookie\FileCookieJar
bevarer ikke-sessionscookies
ved hjælp af en JSON-formateret fil.GuzzleHttp\Cookie\SessionCookieJar
lagrer cookies i den
klientsession.Du kan manuelt indsætte cookies i en cookiekrukke med den navngivne konstruktør fromArray(array $cookies, $domain)
.
$jar = \GuzzleHttp\Cookie\CookieJar::fromArray(
[
'some_cookie' => 'foo',
'other_cookie' => 'barbaz1234'
],
'example.org'
);
Du kan hente en cookie ved hjælp af dens navn med getCookieByName($name)
metoden, som returnerer en GuzzleHttp\Cookie\SetCookie
instans.
$cookie = $jar->getCookieByName('some_cookie');
$cookie->getValue(); // 'foo'
$cookie->getDomain(); // 'example.org'
$cookie->getExpires(); // expiration date as a Unix timestamp
Cookies kan også hentes i et array takket være metoden toArray().
GuzzleHttp\Cookie\CookieJarInterface
interface udvider
Traversable
, så den kan itereres i en foreach-loop.
Guzzle vil automatisk følge omdirigeringer, medmindre du beder den om at lade være. Du kan tilpasse omdirigeringsadfærden ved hjælp af allow_redirects
request option.
true
for at aktivere normale omdirigeringer med et maksimalt antal på 5
omdirigeringer. Dette er standardindstillingen.false
for at deaktivere omdirigeringer.$response = $client->request('GET', 'http://github.com');
echo $response->getStatusCode();
// 200
Følgende eksempel viser, at omdirigeringer kan deaktiveres.
$response = $client->request('GET', 'http://github.com', [
'allow_redirects' => false
]);
echo $response->getStatusCode();
// 301
Trævisning
I følgende trædiagram beskrives det, hvordan Guzzle-undtagelserne afhænger af hinanden.
. \RuntimeException
└── TransferException (implements GuzzleException)
├── ConnectException (implements NetworkExceptionInterface)
└── RequestException
├── BadResponseException
│ ├── ServerException
│ └── ClientException
└── TooManyRedirectsException
Guzzle kaster undtagelser for fejl, der opstår under en overførsel.
En GuzzleHttp\Exception\ConnectException
undtagelse er kastet i
tilfælde af en netværksfejl. Denne undtagelse er en forlængelse af
GuzzleHttp\Exception\TransferException
.
En GuzzleHttp\Exception\ClientException
kastes for 400
niveau fejl, hvis http_errors
request option er sat til true. Denne
undtagelse er en forlængelse af GuzzleHttp\Exception\BadResponseException
og GuzzleHttp\Exception\BadResponseException.
GuzzleHttp\Exception\BadResponseException
udvider fra
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()));
}
En GuzzleHttp\Exception\ServerException
bliver kastet for 500 niveau
fejl, hvis http_errors
request option er sat til true. Denne
undtagelse er en forlængelse af GuzzleHttp\Exception\BadResponseException
.
En GuzzleHttp\Exception\TooManyRedirectsException
bliver kastet, når for
mange omdirigeringer følges. Denne undtagelse er en forlængelse af GuzzleHttp\Exception\RequestException
.
Alle de ovennævnte undtagelser er en forlængelse af GuzzleHttp\Exception\TransferException
.
Guzzle indeholder nogle få miljøvariabler, som kan bruges til at tilpasse bibliotekets opførsel.
GUZZLE_CURL_SELECT_TIMEOUT
curl_multi_select()
. Nogle systemer
har problemer med PHP's implementering af curl_multi_select()
hvor
kald af denne funktion altid resulterer i, at man venter i den maksimale varighed af
timeout.HTTP_PROXY
Definerer den proxy, der skal bruges, når der sendes anmodninger via "http"-protokollen.
Bemærk: da HTTP_PROXY-variablen kan indeholde vilkårlige brugerinput i nogle (CGI) miljøer, bruges variablen kun i CLI SAPI. Se https://httpoxy.org for yderligere oplysninger.
HTTPS_PROXY
NO_PROXY
Guzzle kan bruge PHP ini indstillinger, når du konfigurerer klienter.
openssl.cafile