Snabbstart¶

Den här sidan ger en snabb introduktion till Guzzle och inledande exempel. Om du inte redan har installerat Guzzle kan du gå till Installation sidan.

Gör en begäran¶

Du kan skicka förfrågningar med Guzzle genom att använda ett GuzzleHttp\ClientInterface objekt.

Skapa en klient¶

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 är oföränderliga i Guzzle, vilket innebär att du inte kan ändra de standardvärden som används av en klient efter att den har skapats.

Klientkonstruktören tar emot en associativ matris av alternativ:

base_uri

(string|UriInterface) Bas-URI för den klient som slås samman till en relativ URI. URI:er. Kan vara en sträng eller en instans av UriInterface. När en relativ URI tillhandahålls en klient kommer klienten att kombinera bas-URI:n med den relativa URI:n. relativa URI med hjälp av de regler som beskrivs i RFC 3986, avsnitt 5.2.

// Skapa en klient med en bas-URI
$client = new GuzzleHttp\Client(['base_uri' => 'https://foo.com/api/']);
// Skicka en begäran till https://foo.com/api/test
$response = $client->request('GET', 'test');
// Skicka en begäran till https://foo.com/root
$response = $client->request('GET', '/root');

Känner du inte för att läsa RFC 3986? Här är några snabba exempel på hur en base_uri löses med en annan 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

(anropsbar) Funktion som överför HTTP-begäranden via kabeln. funktionen anropas med ett Psr7\Http\Message\RequestInterface och ett array av överföringsalternativ, och måste returnera en GuzzleHttp\Promise\PromiseInterface som uppfylls med en Psr7\Http\Message\ResponseInterface vid framgång.

...

(mixed) Alla andra alternativ som överlämnats till konstruktören används som standard. begärsalternativ vid varje begäran som skapas av klienten.

Skicka förfrågningar¶

Magiska metoder på klienten gör det enkelt att skicka synkrona förfrågningar:

$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 skapa en begäran och sedan skicka begäran med klienten när du är redo:

use GuzzleHttp\Psr7\Request;

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

Klientobjekt ger stor flexibilitet när det gäller hur begäranden överföringen, inklusive standardalternativ för begäran, standard handläggare och middleware för stacken. som används av varje begäran och en bas-URI som gör det möjligt att skicka begäranden. med relativa URI:er.

Du kan läsa mer om klientmedelprogram på sidan Handlers and Middleware i dokumentationen.

Async Requests¶

Du kan skicka asynkrona begäranden med hjälp av de magiska metoder som tillhandahålls av 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 också använda metoderna sendAsync() och requestAsync() för 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 som returneras av dessa metoder implementerar Promises/A+ spec, som tillhandahålls av Guzzle promises library. Detta innebär att att du kan kedja then() anrop från löftet. Dessa then-anrop är antingen uppfyllda med ett framgångsrikt Psr\Http\Message\ResponseInterface eller avvisas med ett undantag.

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

Samtida förfrågningar¶

Du kan skicka flera förfrågningar samtidigt med hjälp av löften och asynkrona förfrågningar.

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 använda GuzzleHttp\Pool objektet när du har ett obestämt antal begäranden som du vill skicka.

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 använda ett avslut som returnerar ett löfte när poolen anropar avslutet.

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

Användning av svar¶

I de tidigare exemplen hämtade vi en $response variabel eller så var vi fick ett svar från ett löfte. Svarsobjektet implementerar en PSR-7 svar, Psr\Http\Message\ResponseInterface, och innehåller massor av information.

Du kan få fram statuskoden och orsaksfrasen i svaret:

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

Du kan hämta rubriker från 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 i ett svar kan hämtas med hjälp av metoden getBody. Kroppen kan användas som en sträng, kastas till en sträng eller användas som ett strömliknande 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();

Parametrar för söksträngar¶

Du kan ange parametrar för frågesträngar i en begäran på flera olika sätt.

Du kan ange parametrar för frågesträngar i begäranens URI:

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

Du kan ange parametrarna för frågesträngen med hjälp av query som en array.

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

Om du anger alternativet som en array används PHP:s http_build_query funktion för att formatera frågesträngen.

Slutligen kan du ange query som en sträng.

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

Ladda upp data¶

Guzzle erbjuder flera metoder för att ladda upp data.

Du kan skicka begäranden som innehåller en dataström genom att skicka en sträng, resurs som returneras från fopen, eller en instans av en Psr\Http\Message\StreamInterface till body som begärsalternativ.

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

Ett enkelt sätt att ladda upp JSON-data och ställa in lämplig rubrik är att använda json:

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

POST/Formulärförfrågningar¶

Förutom att ange rådata för en begäran med hjälp av body erbjuder Guzzle användbara abstraktioner för att skicka POST-data.

Skicka formulärfält¶

För att skicka application/x-www-form-urlencoded POST-begäranden krävs att du anger POST-fälten som en array i form_params-begäringsalternativen.

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

Skicka formulärfiler¶

Du kan skicka filer tillsammans med ett formulär (multipart/form-data POST-förfrågningar), med hjälp av alternativet multipart request. multipart accepterar en matris av associativa matriser, där varje associativ matris innehåller följande nycklar:

name: (krävs, sträng) Nyckelmappning till formulärfältets namn.
innehåll: (krävs, blandad) Ange en sträng för att skicka innehållet i filen som en sträng, ange en fopen-resurs för att strömma innehållet från en PHP-ström, eller tillhandahålla en Psr\Http\Message\StreamInterface för att strömma innehållet från en PSR-7-ström.

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 upprätthålla en cookiesession för dig om du får instruktioner om du använder cookies. När du skickar en begäran kan alternativet cookies användas. måste ställas in till en instans av 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 ställa in cookies till true i en klientkonstruktör om du vill använda en gemensam kakburk för alla begäranden.

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

Det finns olika implementeringar för GuzzleHttp\Cookie\CookieJarInterface :

Klassen GuzzleHttp\Cookie\CookieJar lagrar cookies som en array.
Klassen GuzzleHttp\Cookie\FileCookieJar behåller cookies som inte är sessioner. med hjälp av en JSON-formaterad fil.
Klassen GuzzleHttp\Cookie\SessionCookieJar lagrar kakor i klientsessionen.

Du kan manuellt ställa in kakor i en kakburk med den namngivna konstruktören fromArray(array $cookies, $domain).

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

Du kan hämta en cookie genom dess namn med metoden getCookieByName($name) som returnerar 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

Kakorna kan också hämtas till en array tack vare metoden toArray(). Gränssnittet GuzzleHttp\Cookie\CookieJarInterface utökar Traversable så att det kan genomgås i en foreach-slinga.

Omdirigeringar¶

Guzzle följer automatiskt omdirigeringar om du inte säger åt den att inte göra det. Du kan anpassa omdirigeringsbeteendet med hjälp av allow_redirects.

Ställ in true för att aktivera normala omdirigeringar med ett maximalt antal på 5. omdirigeringar. Detta är standardinställningen.
Ange false för att inaktivera omdirigeringar.
Överlämna en associativ matris som innehåller nyckeln "max" för att ange det maximala värdet. antal omdirigeringar och eventuellt ett nyckelvärde "strict" för att ange det högsta antalet omdirigeringar. om man ska använda strikta RFC-kompatibla omdirigeringar eller inte (vilket innebär att omdirigera POST förfrågningar med POST-förfrågningar, istället för att göra det som de flesta webbläsare gör, dvs. omdirigera POST-förfrågningar med GET-förfrågningar).

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

Följande exempel visar att omdirigeringar kan inaktiveras.

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

Undantag¶

Trädvy

I följande trädvy beskrivs hur Guzzle Exceptions är beroende av varandra.

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

Guzzle kastar undantag för fel som inträffar under en överföring.

Ett GuzzleHttp\Exception\ConnectException undantag kastas i om det uppstår ett nätverksfel. Detta undantag är en förlängning av GuzzleHttp\Exception\TransferException.

Ett GuzzleHttp\Exception\ClientException kastas för 400 om http_errors är satt till true. Detta undantag är en förlängning av GuzzleHttp\Exception\BadResponseException och GuzzleHttp\Exception\BadResponseException är en förlängning av GuzzleHttp\Exception\RequestException.


use GuzzleHttp\Psr7;
use GuzzleHttp\Exception\ClientException;

försök {
    $client->request('GET', 'https://github.com/_abc_123_404');
} catch (ClientException $e) {
    echo Psr7\Message::toString($e->getRequest());
    echo Psr7\Message::toString($e->getResponse());
}

Ett GuzzleHttp\Exception\ServerException kastas för 500 nivåer. om http_errors är satt till true. Detta undantag är en förlängning av GuzzleHttp\Exception\BadResponseException.
Ett GuzzleHttp\Exception\TooManyRedirectsException kastas när för många många omdirigeringar följs. Detta undantag är en förlängning av GuzzleHttp\Exception\RequestException.

Alla ovanstående undantag är en förlängning av GuzzleHttp\Exception\TransferException.

Miljövariabler¶

Guzzle har några miljövariabler som kan användas för att anpassa bibliotekets beteende.

GUZZLE_CURL_SELECT_TIMEOUT

Kontrollerar varaktigheten i sekunder som en curl_multi_*-hanterare ska använda när välja på curl-hanterare med hjälp av curl_multi_select(). Vissa system har problem med PHP:s implementering av curl_multi_select() där anrop av denna funktion alltid resulterar i att man väntar i den maximala längden på timeout.

HTTP_PROXY

Definierar vilken proxy som ska användas när du skickar förfrågningar med http-protokollet.

Observera: eftersom variabeln HTTP_PROXY kan innehålla godtycklig användarinmatning i vissa (CGI) miljöer används variabeln endast i CLI SAPI. Se https://httpoxy.org för mer information.

HTTPS_PROXY

Definierar den proxy som ska användas när du skickar begäranden med https-protokollet.

NO_PROXY

Definierar webbadresser för vilka en proxy inte ska användas. Se proxy för användning.

Relevanta ini-inställningar¶

Guzzle kan använda PHP ini-inställningar när du konfigurerar klienter.

openssl.cafile: Anger sökvägen på disken till en CA-fil i PEM-format som ska användas vid sändning av förfrågningar via "https". Se: https://wiki.php.net/rfc/tls-peer-verification#phpini_defaults

Innehållsförteckning