Guzzle a PSR-7¶

Guzzle využíva PSR-7 ako rozhranie správ HTTP. To umožňuje Guzzle pracovať s akoukoľvek inou knižnicou, ktorá využíva rozhranie správ PSR-7.

Guzzle je klient HTTP, ktorý odosiela požiadavky HTTP na server a prijíma odpovede HTTP. Požiadavky aj odpovede sa označujú ako správy.

Guzzle sa pri implementácii správy PSR-7 spolieha na balík guzzlehttp/psr7 Composer.

Požiadavku môžete vytvoriť pomocou triedy 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);

Odpoveď môžete vytvoriť pomocou triedy 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¶

Správy s požiadavkami aj s odpoveďami obsahujú hlavičky HTTP.

Prístup k hlavičkám¶

Pomocou metódy hasHeader() môžete skontrolovať, či požiadavka alebo odpoveď obsahuje určitú hlavičku.

use GuzzleHttp\Psr7;

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

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

Všetky hodnoty hlavičky môžete získať ako pole reťazcov pomocou getHeader().

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

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

Hlavičky správy môžete iterovať pomocou metódy getHeaders().

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

Komplexné nadpisy¶

Niektoré hlavičky obsahujú ďalšie informácie o pároch kľúčov a hodnôt. Napríklad hlavičky Odkaz obsahujú odkaz a niekoľko párov kľúčov a hodnôt:

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

Guzzle poskytuje pohodlnú funkciu, ktorú možno použiť na analýzu týchto typov hlavičiek:

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ýstup:

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

Výsledok obsahuje hash dvojíc kľúč - hodnota. Hodnoty hlavičky, ktoré nemajú kľúč (t. j. odkaz), sú indexované číselne, zatiaľ čo časti záhlavia, ktoré tvoria kľúč hodnotu, sú pridané ako dvojica kľúč - hodnota.

Telo¶

Správy žiadosti aj odpovede môžu obsahovať telo.

Telo správy môžete získať pomocou metódy getBody():

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

Telo používané v objektoch požiadaviek a odpovedí je Psr\Http\Message\StreamInterface. Tento prúd sa používa pre odosielanie údajov, ako aj na sťahovanie údajov. Guzzle bude v predvolenom nastavení ukladať telo správy v prúde, ktorý používa dočasné prúdy PHP. Keď veľkosť tela prekročí 2 MB, prúd sa automaticky prepne na ukladanie údajov na disk namiesto do pamäte (čím sa aplikácia chráni pred vyčerpaním pamäte).

Najjednoduchší spôsob, ako vytvoriť telo správy, je použiť streamFor z triedy GuzzleHttp\Psr7\Utils -- Utils::streamFor. Táto metóda prijíma reťazce, zdroje, callables, iterátory, iné streamables a vracia inštanciu Psr\Http\Message\StreamInterface.

Telo požiadavky alebo odpovede je možné previesť na reťazec alebo môžete podľa potreby čítať a zapisovať bajty z prúdu.

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žiadavky¶

Požiadavky sa posielajú z klienta na server. Požiadavky obsahujú metódu sa použije na prostriedok, identifikátor prostriedku a protokol. verziu, ktorá sa má použiť.

Metódy požiadavky¶

Pri vytváraní požiadavky sa očakáva, že uvediete požadovanú metódu HTTP. vykonať. Môžete zadať ľubovoľnú metódu vrátane vlastnej metódy ktorá nemusí byť súčasťou RFC 7231 (naprí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žiadavku môžete vytvoriť a odoslať pomocou metód klienta, ktoré sa mapujú na metódu HTTP, ktorú chcete použiť.

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 **/])

Napríklad:

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

Request URI¶

URI požiadavky je reprezentovaný objektom Psr\Http\Message\UriInterface. Guzzle poskytuje implementáciu tohto rozhrania pomocou objektu GuzzleHttp\Psr7\Uri triedy.

Pri vytváraní požiadavky môžete poskytnúť URI ako reťazec alebo inštanciu Psr\Http\Message\UriInterface.

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

Schéma¶

schéma požiadavky určuje protokol, ktorý sa má použiť pri odosielaní požiadavky. Pri použití nástroja Guzzle sa schéma môže byť nastavená na "http" alebo "https".

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

Host¶

Hostiteľ je prístupný pomocou URI vlastneného požiadavkou alebo prístupom k hlavičke Host.

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

Port¶

Pri použití schém "http" alebo "https" nie je potrebný žiadny port.

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

Cesta¶

Cesta požiadavky je prístupná prostredníctvom objektu URI.

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

Obsah cesty sa automaticky filtruje, aby sa zabezpečilo, že sa v nej budú nachádzať len sa v ceste nachádzajú povolené znaky. Všetky znaky, ktoré nie sú povolené v ceste, budú percentuálne kódované podľa RFC 3986 časť 3.3

Query string¶

K reťazcu dopytu požiadavky možno pristupovať pomocou getQuery() objektu URI, ktorý vlastní požiadavka.

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

Obsah reťazca dopytu sa automaticky filtruje, aby sa zabezpečilo, že sa v reťazci dotazu nachádzali len povolené znaky. Všetky znaky, ktoré nie sú v reťazci dotazu povolené, budú percentuálne kódované podľa RFC 3986 časť 3.4

Odpovede¶

Odpovede sú správy HTTP, ktoré klient dostane od servera po odoslaní správy s požiadavkou HTTP.

Úvodný riadok¶

Úvodný riadok odpovede obsahuje protokol a verziu protokolu, stavový kód a dôvodovú vetu.

$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¶

Ako už bolo popísané, telo odpovede môžete získať pomocou metódy 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žíva na reprezentáciu správ typu request a response objekty PSR-7 telá správ. Tieto prúdové objekty umožňujú pracovať s rôznymi typmi údajov. pomocou spoločného rozhrania.

Správy HTTP sa skladajú z úvodného riadku, hlavičiek a tela. Telo správy HTTP môže byť veľmi malé alebo veľmi veľké. Pokus o reprezentáciu tela správy ako reťazec môže ľahko spotrebovať viac pamäte, než sa zamýšľalo, pretože telo musí byť kompletne uložené v pamäti. Pokus o uloženie tela žiadosti alebo odpovede v pamäti by znemožnilo použitie tejto implementácie možnosť pracovať s veľkými telami správ. Rozhranie StreamInterface sa používa v aby sa skryli implementačné podrobnosti o tom, odkiaľ sa číta prúd údajov alebo do ktorého sa zapisuje.

Rozhranie PSR-7 Psr\Http\Message\StreamInterface vystavuje niekoľko metód, ktoré umožňujú efektívne čítanie, zápis a prechádzanie tokov.

Streamy odhaľujú svoje možnosti pomocou troch metód: isReadable(), isWritable() a isSeekable(). Tieto metódy možno použiť pomocou prúdu spolupracovníci na určenie, či je prúd schopný splniť ich požiadavky.

Každá inštancia prúdu má rôzne možnosti: môže byť len na čítanie, len na zápis, na čítanie a zápis, umožniť ľubovoľný náhodný prístup (vyhľadávanie smerom dopredu alebo spätne na ľubovoľné miesto), alebo umožniť len sekvenčný prístup (napr. v prípade zásuvky alebo potrubia).

Guzzle používa balík guzzlehttp/psr7 na zabezpečenie podpory streamov. Viac na informácie o používaní streamov, vytváraní streamov, konverzii streamov do PHP zdrojov prúdov a dekorátory prúdov nájdete v Dokumentácia Guzzle PSR-7.

Vytváranie streamov¶

Najlepší spôsob, ako vytvoriť prúd, je použiť GuzzleHttp\Psr7\Utils::streamFor metódu. Táto metóda akceptuje reťazce, zdroje vrátené z fopen(), objekt, ktorý implementuje __toString(), iterátory, callables a inštancie 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átorov môžete vytvárať prúdy. Iterátor môže poskytnúť ľubovoľný počet bajtov na iteráciu. Všetky nadbytočné bajty vrátené iterátorom, ktoré neboli vyžiadané konzumentom prúdu, budú uložené do vyrovnávacej pamäte až do ďalšieho čítania.

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); // ...

Metadáta¶

Streamy zobrazujú metadáta toku prostredníctvom metódy getMetadata(). Táto poskytuje údaje, ktoré by ste získali pri volaní PHP funkcie stream_get_meta_data(), a voliteľne môže vystaviť ďalšie vlastné údaje.

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

Dekorátory prúdu¶

Pridávanie vlastných funkcií do tokov je veľmi jednoduché pomocou dekorátorov tokov. Guzzle poskytuje niekoľko vstavaných dekorátorov, ktoré poskytujú ďalšie prúdové funkčnosť prúdu.