Guzzle a PSR-7¶

Guzzle používá PSR-7 jako rozhraní pro zprávy HTTP. Díky tomu může Guzzle spolupracovat s jakoukoli jinou knihovnou, která využívá rozhraní zpráv PSR-7.

Guzzle je klient HTTP, který odesílá požadavky HTTP na server a přijímá odpovědi HTTP. Požadavky i odpovědi se označují jako zprávy.

Guzzle se spoléhá na guzzlehttp/psr7 balíček Composer pro implementaci PSR-7.

Požadavek můžete vytvořit pomocí třídy GuzzleHttp\Psr7\Request:

use GuzzleHttp\Psr7\Request;

$request = new Request('GET', 'http://httpbin.org/get');

// You can provide other optional constructor arguments.
$headers = ['X-Foo' => 'Bar'];
$body = 'hello!';
$request = new Request('PUT', 'http://httpbin.org/put', $headers, $body);

Odpověď můžete vytvořit pomocí třídy GuzzleHttp\Psr7\Response:

use GuzzleHttp\Psr7\Response;

// The constructor requires no arguments.
$response = new Response();
echo $response->getStatusCode(); // 200
echo $response->getProtocolVersion(); // 1.1

// You can supply any number of optional arguments.
$status = 200;
$headers = ['X-Foo' => 'Bar'];
$body = 'hello!';
$protocol = '1.1';
$response = new Response($status, $headers, $body, $protocol);

Nadpisy¶

Zprávy požadavku i odpovědi obsahují hlavičky HTTP.

Přístup k záhlaví¶

Pomocí metody hasHeader() můžete zjistit, zda požadavek nebo odpověď obsahuje určitou hlavičku.

use GuzzleHttp\Psr7;

$request = new Psr7\Request('GET', '/', ['X-Foo' => 'bar']);

if ($request->hasHeader('X-Foo')) {
    echo 'It is there';
}

Všechny hodnoty záhlaví můžete získat jako pole řetězců pomocí getHeader().

$request->getHeader('X-Foo'); // ['bar']

// Retrieving a missing header returns an empty array.
$request->getHeader('X-Bar'); // []

Záhlaví zprávy můžete iterovat pomocí metody getHeaders().

foreach ($request->getHeaders() as $name => $values) {
    echo $name . ': ' . implode(', ', $values) . "\r\n";
}

Komplexní záhlaví¶

Některá záhlaví obsahují další informace o dvojici klíčů a hodnot. Například hlavičky Odkaz obsahují odkaz a několik párů klíčových hodnot:

<http://foo.com>; rel="thing"; type="image/jpeg"

Guzzle poskytuje pohodlnou funkci, kterou lze použít k analýze těchto typů hlaviček:

use GuzzleHttp\Psr7;

$request = new Psr7\Request('GET', '/', [
    'Link' => '<http:/.../front.jpeg>; rel="front"; type="image/jpeg"'
]);

$parsed = Psr7\Header::parse($request->getHeader('Link'));
var_export($parsed);

Bude výstupem:

array (
  0 =>
  array (
    0 => '<http:/.../front.jpeg>',
    'rel' => 'front',
    'type' => 'image/jpeg',
  ),
)

Výsledek obsahuje hash dvojic klíč-hodnota. Hodnoty záhlaví, které nemají žádný klíč (tj. odkaz), jsou indexovány číselně, zatímco části záhlaví, které tvoří klíč, jsou indexovány číselně. hodnotu, jsou přidány jako dvojice klíč-hodnota.

Tělo¶

Zprávy požadavku i odpovědi mohou obsahovat tělo.

Tělo zprávy můžete získat pomocí metody getBody():

$response = GuzzleHttp\get('http://httpbin.org/get');
echo $response->getBody();
// JSON string: { ... }

Tělo používané v objektech požadavku a odpovědi je Psr\Http\Message\StreamInterface. Tento proud se používá jak pro odesílání dat i stahování dat. Guzzle ve výchozím nastavení ukládá tělo zprávy do proudu, který používá dočasné proudy PHP. Pokud je velikost těla přesáhne 2 MB, proud se automaticky přepne na ukládání dat na disk namísto v paměti (což chrání aplikaci před vyčerpáním paměti).

Nejjednodušší způsob, jak vytvořit tělo zprávy, je použít streamFor z třídy GuzzleHttp\Psr7\Utils -- Utils::streamFor. Tato metoda přijímá řetězce, zdroje, callables, iterátory, jiné streamables a vrací instanci třídy Psr\Http\Message\StreamInterface.

Tělo požadavku nebo odpovědi lze převést na řetězec nebo lze z proudu číst a zapisovat bajty podle potřeby.

use GuzzleHttp\Stream\Stream;
$response = $client->request('GET', 'http://httpbin.org/get');

echo $response->getBody()->read(4);
echo $response->getBody()->read(4);
echo $response->getBody()->read(1024);
var_export($response->eof());

Požadavky¶

Požadavky jsou odesílány z klienta na server. Požadavky zahrnují metodu být použita na prostředek, identifikátor prostředku a protokol. verzi, která se má použít.

Způsoby vyžádání¶

Při vytváření požadavku se očekává, že zadáte požadovanou metodu HTTP. provést. Můžete zadat libovolnou metodu, včetně vlastní metody. která nemusí být součástí RFC 7231 (například "MOVE").

// Create a request using a completely custom HTTP method
$request = new \GuzzleHttp\Psr7\Request('MOVE', 'http://httpbin.org/move');

echo $request->getMethod();
// MOVE

Požadavek můžete vytvořit a odeslat pomocí metod klienta, které mapují metodu HTTP, kterou chcete použít.

GET: $client->get('http://httpbin.org/get', [/** options **/])
POST: $client->post('http://httpbin.org/post', [/** options **/])
HEAD: $client->head('http://httpbin.org/get', [/** options **/])
PUT: $client->put('http://httpbin.org/put', [/** options **/])
DELETE: $client->delete('http://httpbin.org/delete', [/** options **/])
MOŽNOSTI: $client->options('http://httpbin.org/get', [/** options **/])
PATCH: $client->patch('http://httpbin.org/put', [/** options **/])

Například:

$response = $client->patch('http://httpbin.org/patch', ['body' => 'content']);

URI požadavku¶

URI požadavku je reprezentován objektem Psr\Http\Message\UriInterface. Guzzle poskytuje implementaci tohoto rozhraní pomocí objektu GuzzleHttp\Psr7\Uri třídy.

Při vytváření požadavku můžete zadat URI jako řetězec nebo instanci Psr\Http\Message\UriInterface.

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

Schéma¶

schéma požadavku určuje protokol, který se má použít při odesílání požadavku. Při použití nástroje Guzzle se schéma může být nastaveno na "http" nebo "https".

$request = new Request('GET', 'http://httpbin.org');
echo $request->getUri()->getScheme(); // http
echo $request->getUri(); // http://httpbin.org

Host¶

Hostitel je přístupný pomocí URI vlastněného požadavkem nebo přístupem k hlavičce Host.

$request = new Request('GET', 'http://httpbin.org');
echo $request->getUri()->getHost(); // httpbin.org
echo $request->getHeader('Host'); // httpbin.org

Port¶

Při použití schémat "http" nebo "https" není nutný žádný port.

$request = new Request('GET', 'http://httpbin.org:8080');
echo $request->getUri()->getPort(); // 8080
echo $request->getUri(); // http://httpbin.org:8080

Path¶

Cesta požadavku je přístupná prostřednictvím objektu URI.

$request = new Request('GET', 'http://httpbin.org/get');
echo $request->getUri()->getPath(); // /get

Obsah cesty bude automaticky filtrován, aby bylo zajištěno, že budou použity pouze se v cestě vyskytovaly povolené znaky. Všechny znaky, které nejsou povoleny v cestě, budou procentuálně zakódovány podle následujícího klíče RFC 3986 část 3.3.

Řetězec dotazů¶

K řetězci dotazu požadavku lze přistupovat pomocí getQuery() objektu URI vlastněného požadavkem.

$request = new Request('GET', 'http://httpbin.org/?foo=bar');
echo $request->getUri()->getQuery(); // foo=bar

Obsah řetězce dotazů bude automaticky filtrován, aby bylo zajištěno, že se v řetězci dotazu vyskytovaly pouze povolené znaky. Jakékoli znaky, které nejsou v řetězci dotazu povoleny, budou procentuálně zakódovány podle následujícího klíče RFC 3986 část 3.4.

Odpovědi¶

Odpovědi jsou zprávy HTTP, které klient obdrží od serveru po odeslání zprávy požadavku HTTP.

Úvodní řádek¶

Počáteční řádek odpovědi obsahuje protokol a verzi protokolu, stavový kód a důvodovou větu.

$client = new \GuzzleHttp\Client();
$response = $client->request('GET', 'http://httpbin.org/get');

echo $response->getStatusCode(); // 200
echo $response->getReasonPhrase(); // OK
echo $response->getProtocolVersion(); // 1.1

Body¶

Jak již bylo popsáno, tělo odpovědi můžete získat pomocí metody getBody().

$body = $response->getBody();
echo $body;
// Cast to a string: { ... }
$body->seek(0);
// Rewind the body
$body->read(1024);
// Read bytes of the body

Streamy¶

Guzzle používá k reprezentaci zprávy požadavku a odpovědi objekty proudu PSR-7. těla zpráv. Tyto proudové objekty umožňují pracovat s různými typy dat. pomocí společného rozhraní.

Zprávy HTTP se skládají z počátečního řádku, hlaviček a těla. Tělo zprávy HTTP může být velmi malé nebo velmi velké. Pokus o zobrazení těla zprávy jako řetězec může snadno spotřebovat více paměti, než bylo zamýšleno, protože tělo musí být kompletně uloženo v paměti. Pokus o uložení těla zprávy požadavku nebo odpovědi v paměti by znemožnilo použití této implementace z možnost pracovat s velkými těly zpráv. Rozhraní StreamInterface se používá v aby se skryly implementační podrobnosti o tom, odkud se proud dat čte. nebo do kterého se zapisuje.

Rozhraní PSR-7 Psr\Http\Message\StreamInterface vystavuje několik metod, které umožňují efektivní čtení, zápis a procházení toků.

Proudy odhalují své možnosti pomocí tří metod: isReadable(), isWritable() a isSeekable(). Tyto metody lze použít pomocí proudu spolupracovníci, aby zjistili, zda je proud schopen splnit jejich požadavky.

Každá instance streamu má různé možnosti: může být určena pouze pro čtení, pouze pro zápis, pro čtení a zápis, umožnit libovolný náhodný přístup (vyhledávání dopředu nebo dopředu) nebo zpět na libovolné místo), nebo umožnit pouze sekvenční přístup (např. v případě v případě socketu nebo roury).

Guzzle používá guzzlehttp/psr7 balíček pro podporu streamů. Více informace o používání streamů, vytváření streamů, převodu streamů do jazyka PHP zdroje proudů a dekorátory proudů naleznete v dokumentu Dokumentace Guzzle PSR-7.

Vytváření streamů¶

Nejlepší způsob, jak vytvořit stream, je použít GuzzleHttp\Psr7\Utils::streamFor metodu. Tato metoda přijímá řetězce, zdroje vrácené z fopen(), objekt, který implementuje __toString(), iterátory, callables a instance. Psr\Http\Message\StreamInterface.

use GuzzleHttp\Psr7;

$stream = Psr7\Utils::streamFor('string data');
echo $stream;
// string data
echo $stream->read(3);
// str
echo $stream->getContents();
// ing data
var_export($stream->eof());
// true
var_export($stream->tell());
// 11

Z iterátorů můžete vytvářet proudy. Iterátor může poskytnout libovolný počet bajtů na iteraci. Všechny přebytečné bajty vrácené iterátorem, které nebyly vyžádány konzumentem proudu, budou uloženy do vyrovnávací paměti až do dalšího čtení.

use GuzzleHttp\Psr7;

$generator = function ($bytes) {
    for ($i = 0; $i < $bytes; $i++) {
        yield '.';
    }
};

$iter = $generator(1024);
$stream = Psr7\Utils::streamFor($iter);
echo $stream->read(3); // ...

Metadata¶

Proudy vystavují metadata proudu prostřednictvím metody getMetadata(). Tato stránka poskytuje údaje, které byste získali při volání PHP metody funkci stream_get_meta_data(), a volitelně může zobrazit další vlastní data.

use GuzzleHttp\Psr7;

$resource = Psr7\Utils::tryFopen('/path/to/file', 'r');
$stream = Psr7\Utils::streamFor($resource);
echo $stream->getMetadata('uri');
// /path/to/file
var_export($stream->isReadable());
// true
var_export($stream->isWritable());
// false
var_export($stream->isSeekable());
// true

Stream Decorators¶

Přidávání vlastních funkcí do streamů je velmi jednoduché pomocí dekorátorů streamů. Guzzle poskytuje několik vestavěných dekorátorů, které poskytují další proudy. funkce.