Snelstart¶

Deze pagina geeft een snelle inleiding tot Guzzle en inleidende voorbeelden. Als je Guzzle nog niet hebt geïnstalleerd, ga dan naar de Installation pagina.

Een verzoek indienen¶

Je kunt verzoeken sturen met Guzzle door gebruik te maken van een GuzzleHttpClientInterface object.

Een klant maken¶

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,
]);

Clients zijn onveranderlijk in Guzzle, wat betekent dat je de standaardwaarden die door een client worden gebruikt niet kunt wijzigen nadat deze is gemaakt.

De client constructor accepteert een associatieve array van opties:

base_uri

(string|UriInterface) Basis URI van de client die wordt samengevoegd in relatieve URI's. Kan een string of een instantie van UriInterface zijn. Wanneer een relatieve URI wordt verstrekt aan een client, zal de client de basis-URI combineren met de relatieve URI met behulp van de regels beschreven in RFC 3986, sectie 5.2.

// Maak een client met een basis URI
$client = new GuzzleHttpClient(['base_uri' => 'https://foo.com/api/']);
// Stuur een verzoek naar https://foo.com/api/test
$response = $client->request('GET', 'test');
// Stuur een verzoek naar https://foo.com/root
$response = $client->request('GET', '/root');

Geen zin om RFC 3986 te lezen? Hier zijn enkele snelle voorbeelden over hoe een base_uri wordt opgelost met een andere URI.

base_uri	URI	Resultaat
`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

(opvraagbaar) Functie die HTTP-verzoeken over de draad doorstuurt. De functie wordt aangeroepen met een Psr7HttpMessageRequestInterface en een array van overdrachtsopties, en moet een GuzzleHttpBoodschapBoodschapInterface die vervuld is met een Psr7HttpMessageResponseInterface op succes.

...

(gemengd) Alle andere opties die aan de constructor zijn doorgegeven worden gebruikt als standaard verzoekopties bij elk verzoek dat door de cliënt wordt aangemaakt.

Verzoeken verzenden¶

Magic methods op de client maken het makkelijk om synchrone verzoeken te sturen:

$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');

Je kunt een verzoek aanmaken en dan het verzoek met de cliënt versturen als je klaar bent:

use GuzzleHttp\Psr7\Request;

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

Client-objecten bieden een grote mate van flexibiliteit in hoe verzoeken worden worden verzonden, inclusief standaard verzoekopties, standaard handler stack middleware die door elk verzoek worden gebruikt, en een basis URI die je in staat stelt verzoeken te sturen met relatieve URI's.

Je kan meer te weten komen over client middleware in de Handlers and Middleware pagina van de documentatie.

Async-verzoeken¶

U kunt asynchrone verzoeken verzenden met behulp van de magische methoden die door een cliënt worden verschaft:

$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');

Je kunt ook de sendAsync() en requestAsync() methoden van een client gebruiken:

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');

De belofte die door deze methodes geretourneerd wordt, implementeert de Promises/A+ spec, geleverd door de Guzzle promises library. Dit betekent dat je then() oproepen kan koppelen aan de belofte. Deze dan-oproepen worden ofwel vervuld met een succesvolle PsrHttpMessageResponseInterface of afgewezen met een 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();
    }
);

Samenlopende verzoeken¶

Je kunt meerdere verzoeken tegelijk sturen met promises en asynchrone verzoeken.

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];

Je kan het GuzzleHttp object gebruiken wanneer je een onbepaald aantal requests wil versturen.

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();

Of een sluiting gebruiken die een belofte teruggeeft zodra de pool de sluiting oproept.

$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));

Reacties gebruiken¶

In de vorige voorbeelden haalden we een $response variabele op of kregen we een antwoord van een belofte afgeleverd. Het antwoordobject implementeert een PSR-7 respons, PsrttpMessageResponseInterface, en bevat veel nuttige informatie.

U kunt de statuscode en de redenzin van het antwoord krijgen:

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

U kunt headers uit het antwoord ophalen:

// 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";
}

De body van een antwoord kan opgehaald worden met de getBody methode. De body kan gebruikt worden als een string, gecast worden naar een string, of gebruikt worden als een stream-achtig object.

$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();

Query String Parameters¶

U kunt op verschillende manieren query string parameters meegeven met een verzoek.

U kunt query string parameters instellen in de URI van het verzoek:

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

Je kan de query string parameters opgeven met de query request optie als een array.

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

Door de optie als een array aan te bieden zal PHP's http_build_query functie gebruikt worden om de query string op te maken.

En tenslotte kan je de query verzoekoptie als een string opgeven.

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

Gegevens uploaden¶

Guzzle biedt verschillende methoden voor het uploaden van gegevens.

Je kunt verzoeken sturen die een stroom van gegevens bevatten door een string door te geven, bron geretourneerd door fopen, of een instantie van een PsrttpMessageStreamInterface aan de body verzoekoptie.

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]);

Een gemakkelijke manier om JSON data te uploaden en de juiste header in te stellen is door gebruik te maken van de json request optie:

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

POST/Form Requests¶

Naast het specificeren van de ruwe data van een verzoek met behulp van de body verzoekoptie, biedt Guzzle nuttige abstracties over het verzenden van POST data.

Formuliervelden verzenden¶

Het verzenden van application/x-www-form-urlencoded POST verzoeken vereist dat je de POST velden als een array specificeert in de form_params verzoek opties.

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

Formulierbestanden verzenden¶

Je kan bestanden meesturen met een formulier (multipart/form-data POST verzoeken), met behulp van de multipart verzoekoptie. multipart aanvaardt een array van associatieve arrays, waarbij elke associatieve array de volgende sleutels bevat:

name: (vereist, string) sleutel die de naam van het formulierveld weergeeft.
inhoud: (vereist, gemengd) Geef een string om de inhoud van het bestand als een string te sturen, geef een fopen resource om de inhoud van een PHP stream, of geef een PsrHttpMessageStreamInterface om de inhoud te streamen de inhoud van een PSR-7 stream te streamen.

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 kan een cookie sessie voor je bijhouden als je dat vraagt met de cookies verzoekoptie. Bij het verzenden van een verzoek moet de cookies optie ingesteld worden op een instantie van GuzzleHttpCookieJarInterface.

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

Je kan cookies op true zetten in een client constructor als je een gedeelde cookiepot wil gebruiken voor alle requests.

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

Er bestaan verschillende implementaties voor de GuzzleHttpCookieJarInterface :

De GuzzleHttpCookieCookieJar klasse slaat cookies op als een array.
De GuzzleHttpCookieFileCookieJar klasse bewaart niet-sessie cookies met behulp van een JSON geformatteerd bestand.
De GuzzleHttpCookieSessionCookieJar klasse bewaart cookies in de client sessie.

Je kan handmatig cookies in een cookie jar plaatsen met de named constructor fromArray(array $cookies, $domain).

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

Je kan een cookie bij zijn naam opvragen met de getCookieByName($naam) methode die een GuzzleHttpCookieSetCookie instantie oplevert.

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

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

De cookies kunnen ook opgehaald worden in een array dankzij de toArray() methode. De GuzzleHttpCookieJarInterface interface breidt Traversable zodat hij in een foreach-lus kan doorlopen worden.

Redirects¶

Guzzle zal automatisch redirects volgen tenzij je zegt dat het niet mag. Je kan het omleidinggedrag aanpassen met de allow_redirects verzoekoptie.

Zet op true om normale redirects in te schakelen met een maximum aantal van 5 redirects. Dit is de standaard instelling.
Zet op false om redirects uit te schakelen.
Geef een associatieve array door die de 'max' sleutel bevat om het maximum aantal redirects te specificeren en optioneel een 'strict' sleutelwaarde mee te geven om te specificeren om al dan niet strikte RFC-conforme redirects te gebruiken (d.w.z. redirect POST verzoeken met POST verzoeken vs. doen wat de meeste browsers doen, namelijk POST verzoeken omleiden met GET verzoeken).

$response = $client->request('GET', 'http://github.com');
echo $response->getStatusCode();
// 200

Het volgende voorbeeld toont dat redirects kunnen worden uitgeschakeld.

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

Uitzonderingen¶

Tree View

De volgende boomstructuur beschrijft hoe de Guzzle Exceptions van elkaar afhangen.

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

Guzzle werpt excepties voor fouten die optreden tijdens een overdracht.

Een GuzzleHttpExceptionConnectException uitzondering wordt gegooid in het in het geval van een netwerkfout. Deze uitzondering is een uitbreiding van GuzzleHttpExceptionTransferException.
Een GuzzleHttpExceptionClientException wordt gegooid voor 400 niveau als de http_errors verzoekoptie op true is gezet. Deze uitzondering is een uitbreiding van de GuzzleHttpExceptionBadResponseException en GuzzleHttp\Exception is een uitbreiding van GuzzleHttpExceptionRequestException.
```
gebruik GuzzleHttp;
gebruik GuzzleHttpExceptionClientException;

probeer {
    $client->request('GET', 'https://github.com/_abc_123_404');
} catch (ClientException $e) {
    echo Psr7\Message::toString($e->getRequest());
    echo Psr7\Message::toString($e->getResponse());
}
```
Een GuzzleHttpExceptionServerException wordt gegooid voor 500 level fouten als de http_errors verzoekoptie op true is gezet. Deze exceptie is een uitbreiding van de GuzzleHttpExceptionBadResponseException.
Een GuzzleHttpExceptionTooManyRedirectsException wordt afgeworpen wanneer te te veel redirects gevolgd worden. Deze exceptie is een uitbreiding van de GuzzleHttp\ExceptionRequestException.

Alle bovenstaande uitzonderingen zijn een uitbreiding van GuzzleHttpExceptionTransferException.

Omgevingsvariabelen¶

Guzzle stelt een paar omgevingsvariabelen ter beschikking die kunnen worden gebruikt om het gedrag van de bibliotheek aan te passen.

GUZZLE_CURL_SELECT_TIMEOUT

Regelt de tijdsduur in seconden die een curl_multi_* handler zal gebruiken bij selecteren op curl handles met curl_multi_select(). Sommige systemen hebben problemen met PHP's implementatie van curl_multi_select() waar het aanroepen van deze functie altijd resulteert in het wachten op de maximale duur van van de timeout.

HTTP_PROXY

Bepaalt de proxy die gebruikt moet worden bij het versturen van requests via het "http" protocol.

Opmerking: omdat de HTTP_PROXY variabele op sommige (CGI) omgevingen arbitraire gebruikersinvoer kan bevatten, wordt de variabele enkel gebruikt op de CLI SAPI. Zie https://httpoxy.org voor meer informatie.

HTTPS_PROXY

Bepaalt de proxy die moet worden gebruikt bij het verzenden van verzoeken via het "https" protocol.

NO_PROXY

Definieert URL's waarvoor geen proxy gebruikt mag worden. Zie proxy voor gebruik.

Relevante ini-instellingen¶

Guzzle kan gebruik maken van PHP ini instellingen bij het configureren van clients.

openssl.cafile: Specificeert het pad op schijf naar een CA-bestand in PEM-formaat om te gebruiken bij het verzenden van verzoeken over "https". Zie: https://wiki.php.net/rfc/tls-peer-verification#phpini_defaults

Inhoudsopgave