Rychlý začátek¶

Tato stránka obsahuje stručný úvod do systému Guzzle a úvodní příklady. Pokud jste ještě Guzzle nenainstalovali, přejděte na stránku Instalace na stránku.

Podání žádosti¶

Požadavky můžete pomocí Guzzle odesílat pomocí objektu GuzzleHttp\ClientInterface.

Vytvoření klienta¶

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 jsou v systému Guzzle neměnní, což znamená, že výchozí hodnoty používané klientem nelze po jeho vytvoření změnit.

Konstruktor klienta přijímá asociativní pole možností:

base_uri

(string|UriInterface) Základní URI klienta, který je sloučen do relativního. URI. Může to být řetězec nebo instance UriInterface. Když relativní URI je klientovi poskytnuto základní URI, klient spojí základní URI s URI relativním URI podle pravidel popsaných v části RFC 3986, sekce 5.2

// Vytvoření klienta se základním URI.
$client = new GuzzleHttp\Client(['base_uri' => 'https://foo.com/api/']);
// Odeslání požadavku na adresu https://foo.com/api/test
$response = $client->request('GET', 'test');
// Odeslání požadavku na adresu https://foo.com/root
$response = $client->request('GET', '/root');

Nechce se vám číst RFC 3986? Zde je několik rychlých příkladů, jak se base_uri překládá pomocí jiného URI.

base_uri	URI	Výsledek
`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

(volatelný) Funkce, která přenáší požadavky HTTP po drátě. Adresa se volá pomocí Psr7\Http\Message\RequestInterface a pole možností přenosu a musí vrátit GuzzleHttp\Promise\PromiseInterface, který je splněn pomocí funkce Psr7\Http\Message\ResponseInterface při úspěchu.

...

(mixed) Všechny ostatní volby předané konstruktoru jsou použity jako výchozí. u každého požadavku vytvořeného klientem.

Zasílání požadavků¶

Magické metody na klientovi usnadňují odesílání synchronních požadavků:

$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 vytvořit požadavek a poté jej odeslat spolu s klientem, až budete připraveni:

use GuzzleHttp\Psr7\Request;

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

Klientské objekty poskytují velkou flexibilitu v tom, jak jsou požadavky včetně výchozích možností přenosu požadavků, výchozího middlewaru zásobníku obsluhy které jsou použity pro každý požadavek, a základního URI, který umožňuje odesílat požadavky. s relativními URI.

Více informací o klientském middlewaru najdete na stránce Handlery a middleware dokumentace.

Asynchronní požadavky¶

Asynchronní požadavky můžete odesílat pomocí magických metod poskytovaných klientem:

$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 také použít metody 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');

Příslib vrácený těmito metodami implementuje funkci specifikaci Promises/A+, kterou poskytuje nástroj Guzzle promises library. To znamená, že že můžete řetězit then() volání ze slibu. Tato volání then jsou buď splněny úspěšným Psr\Http\Message\ResponseInterface nebo odmítnuta s výjimkou.

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

Souběžné požadavky¶

Pomocí slibů a asynchronních požadavků můžete odesílat více požadavků současně.

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žít, pokud chcete odeslat neurčité množství požadavků.

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

Nebo pomocí uzávěru, který vrátí slib, jakmile fond zavolá uzávěr.

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

Použití odpovědí¶

V předchozích příkladech jsme načítali proměnnou $response nebo jsme byli byla doručena odpověď ze slibu. Objekt response implementuje PSR-7 response, Psr\Http\Message\ResponseInterface, a obsahuje spoustu prvků. užitečných informací.

Můžete získat stavový kód a důvodovou frázi odpovědi:

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

Z odpovědi můžete načíst 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";
}

Tělo odpovědi lze získat pomocí metody getBody. Tělo lze použít jako řetězec, převést na řetězec nebo použít jako 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();

Parametry dotazovacího řetězce¶

Parametry řetězce dotazu můžete zadat několika způsoby.

V URI požadavku můžete nastavit parametry řetězce dotazu:

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

Parametry řetězce dotazu můžete zadat pomocí možnosti požadavku query jako pole.

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

Poskytnutí možnosti jako pole použije k formátování řetězce dotazu funkci PHP http_build_query.

A nakonec můžete zadat možnost požadavku query jako řetězec.

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

Nahrávání dat¶

Služba Guzzle nabízí několik způsobů nahrávání dat.

Požadavky, které obsahují proud dat, můžete odeslat předáním řetězce, zdroj vrácený z fopen, nebo instanci Psr\Http\Message\StreamInterface k možnosti body požadavku.

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ý způsob, jak nahrát data JSON a nastavit příslušnou hlavičku, je použití možnosti požadavku json:

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

POST/Formulářové požadavky¶

Kromě zadání surových dat požadavku pomocí možnosti body požadavku poskytuje Guzzle užitečné abstrakce pro odesílání dat POST.

Pole odesílacího formuláře¶

Odesílání application/x-www-form-urlencoded POST požadavků vyžaduje zadání POST polí jako pole v form_params možnostech požadavku.

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

Odesílání formulářových souborů¶

Spolu s formulářem můžete odeslat soubory (multipart/form-data POST požadavky), pomocí možnosti multipart request. multipart přijímá pole typu asociativních polí, kde každé asociativní pole obsahuje následující klíče:

name: (povinné, řetězec) klíč mapující název pole formuláře.
obsah: (povinné, smíšené) Zadejte řetězec pro odeslání obsahu souboru. jako řetězec, zadejte prostředek fopen pro přenos obsahu ze serveru PHP, nebo poskytněte Psr\Http\Message\StreamInterface pro streamování z proudu 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'
            ]
        ]
    ]
]);

Cookies¶

Aplikace Guzzle může udržovat relaci souborů cookie za vás, pokud k tomu dostanete pokyn pomocí příkazu cookies možnost požadavku. Při odesílání požadavku se použije možnost cookies. musí být nastavena na instanci GuzzleHttp\Cookie\CookieJarInterface.

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

Pokud chcete používat sdílenou nádobu se soubory cookie pro všechny požadavky, můžete v konstruktoru klienta nastavit hodnotu cookies na true.

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

Pro rozhraní GuzzleHttp\Cookie\CookieJarInterface existují různé implementace:

Třída GuzzleHttp\Cookie\CookieJar ukládá cookies jako pole.
Třída GuzzleHttp\Cookie\FileCookieJar uchovává soubory cookie, které nejsou soubory relací. pomocí souboru ve formátu JSON.
Třída GuzzleHttp\Cookie\SessionCookieJar uchovává soubory cookie v databázi. klientské relaci.

Soubory cookie můžete ručně nastavit do nádoby na soubory cookie pomocí pojmenovaného konstruktoru fromArray(array $cookies, $domain).

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

Soubor cookie můžete získat podle jeho názvu pomocí metody getCookieByName($name), která vrátí instanci GuzzleHttp\Cookie\SetCookie.

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

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

Cookies lze také načíst do pole díky metodě toArray(). Rozhraní GuzzleHttp\Cookie\CookieJarInterface rozšiřuje rozhraní Traversable, takže jej lze iterovat v cyklu foreach.

Přesměrování¶

Guzzle bude automaticky sledovat přesměrování, pokud mu neřeknete, aby to nedělal. Chování přesměrování můžete upravit pomocí volby allow_redirects request.

Nastavte na true pro povolení normálních přesměrování s maximálním počtem 5. přesměrování. Toto je výchozí nastavení.
Nastavte na false pro vypnutí přesměrování.
Předání asociativního pole obsahujícího klíč 'max' pro zadání maximální hodnoty přesměrování a volitelně hodnotu klíče "strict", která určuje počet přesměrování. zda se mají používat striktní přesměrování v souladu s RFC (což znamená přesměrování POST požadavky s POST požadavky oproti tomu, co dělá většina prohlížečů, což je přesměrování POST požadavků pomocí GET požadavků).

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

Následující příklad ukazuje, že přesměrování lze zakázat.

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

Výjimky¶

Zobrazení stromu

Následující stromové zobrazení popisuje vzájemnou závislost výjimek Guzzle.

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

Guzzle vyhodí výjimky pro chyby, které se vyskytnou během přenosu.

V příkazu GuzzleHttp\Exception\ConnectException je vyhodnocena výjimka GuzzleHttp\Exception\ConnectException. v případě chyby při připojení k síti. Tato výjimka se rozšiřuje z GuzzleHttp\Exception\TransferException.
Je vyhozena GuzzleHttp\Exception\ClientException pro 400. úrovně, pokud je volba http_errors požadavku nastavena na true. Toto se rozšiřuje z GuzzleHttp\Exception\BadResponseException a GuzzleHttp\Exception\BadResponseException rozšiřuje 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());
}
```
Pro úroveň 500 je vyhozena GuzzleHttp\Exception\ServerException. pokud je volba http_errors požadavku nastavena na true. Toto se rozšiřuje z GuzzleHttp\Exception\BadResponseException.
Výjimka GuzzleHttp\Exception\TooManyRedirectsException se vyhodí, když je příliš mnoho adres. následuje příliš mnoho přesměrování. Tato výjimka se rozšiřuje z GuzzleHttp\Exception\RequestException.

Všechny výše uvedené výjimky vycházejí z GuzzleHttp\Exception\TransferException.

Proměnné prostředí¶

Guzzle nabízí několik proměnných prostředí, které lze použít k přizpůsobení chování knihovny.

GUZZLE_CURL_SELECT_TIMEOUT

Řídí dobu trvání v sekundách, kterou obslužná rutina curl_multi_* použije, když. při výběru na handlech curl pomocí curl_multi_select(). Některé systémy mají problémy s implementací curl_multi_select() v jazyce PHP, kdy volání této funkce má vždy za následek čekání na maximální dobu trvání funkce. timeoutu.

HTTP_PROXY

Definuje proxy server, který se použije při odesílání požadavků pomocí protokolu "http"

Poznámka: protože proměnná HTTP_PROXY může v některých prostředích (CGI) obsahovat libovolný uživatelský vstup, používá se tato proměnná pouze v CLI SAPI. Více informací naleznete v https://httpoxy.org.

HTTPS_PROXY

Definuje proxy server, který se použije při odesílání požadavků pomocí protokolu https.

NO_PROXY

Definuje adresy URL, pro které by se neměl používat proxy server. Použití viz proxy.

Relevantní nastavení ini¶

Guzzle může při konfiguraci klientů využívat nastavení PHP ini.

openssl.cafile: Určuje cestu na disku k souboru certifikační autority ve formátu PEM, který se má použít při odesílání. požadavků přes "https". Viz: https://wiki.php.net/rfc/tls-peer-verification#phpini_defaults

Obsah