Guzzle wykorzystuje PSR-7 jako interfejs komunikatów HTTP. Dzięki temu Guzzle może współpracować z każdą inną biblioteką wykorzystującą interfejs komunikatów PSR-7.
Guzzle jest klientem HTTP, który wysyła żądania HTTP do serwera i odbiera odpowiedzi HTTP. Zarówno żądania, jak i odpowiedzi są określane jako komunikaty.
Guzzle opiera się na pakiecie guzzlehttp/psr7 Composer dla implementacji PSR-7.
Żądanie można utworzyć za pomocą klasy 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);
Odpowiedź można utworzyć za pomocą klasy 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);
Zarówno żądanie, jak i odpowiedź zawierają nagłówki HTTP.
Możesz sprawdzić czy żądanie lub odpowiedź ma określony nagłówek używając metody hasHeader().
use GuzzleHttp\Psr7;
$request = new Psr7\Request('GET', '/', ['X-Foo' => 'bar']);
if ($request->hasHeader('X-Foo')) {
echo 'It is there';
}
Możesz pobrać wszystkie wartości nagłówka jako tablicę ciągów znaków używając getHeader().
$request->getHeader('X-Foo'); // ['bar']
// Retrieving a missing header returns an empty array.
$request->getHeader('X-Bar'); // []
Możesz iterować po nagłówkach wiadomości używając metody getHeaders().
foreach ($request->getHeaders() as $name => $values) {
echo $name . ': ' . implode(', ', $values) . "\r\n";
}
Niektóre nagłówki zawierają dodatkowe informacje o parach wartości kluczy. Na przykład nagłówki Link zawierają link i kilka par wartości kluczy:
<http://foo.com>; rel="thing"; type="image/jpeg"
Guzzle udostępnia wygodną funkcję, która może być użyta do analizowania tego typu nagłówków:
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);
Wyjdzie:
array (
0 =>
array (
0 => '<http:/.../front.jpeg>',
'rel' => 'front',
'type' => 'image/jpeg',
),
)
Wynik zawiera hash par klucz-wartość. Wartości nagłówka, które nie posiadają klucza (np. link) są indeksowane numerycznie, podczas gdy części nagłówków, które tworzą parę klucz są dodawane jako para klucz-wartość.
Zarówno wiadomości żądania jak i odpowiedzi mogą zawierać ciało.
Możesz pobrać treść wiadomości używając metody getBody():
$response = GuzzleHttp\get('http://httpbin.org/get');
echo $response->getBody();
// JSON string: { ... }
Ciało używane w obiektach żądania i odpowiedzi jest code class="docutils literal">Psr. Ten strumień jest używany zarówno do wysyłania danych i pobierania danych. Guzzle domyślnie przechowuje treść wiadomości wiadomości w strumieniu, który wykorzystuje strumienie tymczasowe PHP. Gdy rozmiar treści przekroczy 2 MB, strumień automatycznie przełączy się na przechowywanie danych na dysku zamiast w pamięci (chroniąc Twoją aplikację przed wyczerpaniem pamięci).
Najprostszym sposobem na utworzenie ciała wiadomości jest użycie metody streamFor
metody z klasy GuzzleHttp -- Utils::streamFor. Metoda ta akceptuje ciągi znaków, zasoby,
callables, iteratory, inne streamable, i zwraca instancję
Psr\Message\StreamInterface.
Ciało żądania lub odpowiedzi może być rzutowane na ciąg znaków lub możesz odczytywać i zapisywać bajty ze strumienia w zależności od potrzeb.
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());
Żądania są wysyłane z klienta do serwera. Żądania zawierają metodę, która być zastosowana do zasobu, identyfikator zasobu i wersję protokołu wersji do użycia.
Podczas tworzenia żądania należy podać metodę HTTP, którą chcemy wykonać. Możesz podać dowolną metodę, włączając w to własną metodę która może nie być częścią RFC 7231 (np. "MOVE").
// Create a request using a completely custom HTTP method
$request = new \GuzzleHttp\Psr7\Request('MOVE', 'http://httpbin.org/move');
echo $request->getMethod();
// MOVE
Możesz utworzyć i wysłać żądanie używając metod na kliencie, które mapują się na metodę HTTP, której chcesz użyć.
$client->get('http://httpbin.org/get', [/** options **/])$client->post('http://httpbin.org/post', [/** options **/])$client->head('http://httpbin.org/get', [/** options **/])$client->put('http://httpbin.org/put', [/** options **/])$client->delete('http://httpbin.org/delete', [/** options **/])$client->options('http://httpbin.org/get', [/** options **/])$client->patch('http://httpbin.org/put', [/** options **/])Na przykład:
$response = $client->patch('http://httpbin.org/patch', ['body' => 'content']);
URI żądania jest reprezentowany przez obiekt Psr\Http\Message\UriInterface.
Guzzle udostępnia implementację tego interfejsu za pomocą
GuzzleHttp\Psr7\Uri.
Podczas tworzenia żądania, możesz podać URI jako ciąg znaków lub instancję Psr\Http\Message\UriInterface.
$response = $client->request('GET', 'http://httpbin.org/get?q=foo');
Schemat żądania określa protokół, którego należy użyć podczas wysyłania żądania. Podczas korzystania z Guzzle, schemat schemat może być ustawiony na "http" lub "https".
$request = new Request('GET', 'http://httpbin.org');
echo $request->getUri()->getScheme(); // http
echo $request->getUri(); // http://httpbin.org
Host jest dostępny przy użyciu URI należącego do żądania lub poprzez dostęp do nagłówka Host.
$request = new Request('GET', 'http://httpbin.org');
echo $request->getUri()->getHost(); // httpbin.org
echo $request->getHeader('Host'); // httpbin.org
W przypadku korzystania ze schematów "http" lub "https" nie jest wymagany żaden port.
$request = new Request('GET', 'http://httpbin.org:8080');
echo $request->getUri()->getPort(); // 8080
echo $request->getUri(); // http://httpbin.org:8080
Ścieżka żądania jest dostępna poprzez obiekt URI.
$request = new Request('GET', 'http://httpbin.org/get');
echo $request->getUri()->getPath(); // /get
Zawartość ścieżki będzie automatycznie filtrowana, aby zapewnić, że w ścieżce znajdują się tylko tylko dozwolone znaki są obecne w ścieżce. Wszelkie znaki, które nie są dozwolone w ścieżce zostaną zakodowane procentowo zgodnie z RFC 3986 sekcja 3.3
Ciąg zapytania żądania może być dostępny za pomocą getQuery() obiektu URI należącego do żądania.
$request = new Request('GET', 'http://httpbin.org/?foo=bar');
echo $request->getUri()->getQuery(); // foo=bar
Zawartość łańcucha zapytania zostanie automatycznie przefiltrowana, aby upewnić się, że tylko dozwolone znaki są obecne w łańcuchu zapytania. Wszelkie znaki, które nie są dozwolone w łańcuchu zapytania zostaną zakodowane procentowo zgodnie z RFC 3986 sekcja 3.4
Odpowiedzi są komunikatami HTTP, które klient otrzymuje od serwera po wysłaniu komunikatu żądania HTTP.
Linia początkowa odpowiedzi zawiera protokół i wersję protokołu, kod statusu i wyrażenie przyczyny.
$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
Jak opisano wcześniej, ciało odpowiedzi można uzyskać za 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
Guzzle używa obiektów strumieniowych PSR-7 do reprezentowania żądań i odpowiedzi ciała wiadomości. Obiekty strumieniowe pozwalają na pracę z różnymi typami danych przy użyciu wspólnego interfejsu.
Komunikaty HTTP składają się z linii startowej, nagłówków oraz treści. Ciało wiadomości HTTP może być bardzo małe lub bardzo duże. Próba przedstawienia treści komunikatu jako łańcuch znaków może łatwo pochłonąć więcej pamięci niż zamierzano, ponieważ ciało musi być przechowywane w całości w pamięci. Próba przechowywania treści żądania lub odpowiedzi w pamięci uniemożliwiłaby użycie tej implementacji z być w stanie pracować z dużymi ciałami wiadomości. Interfejs StreamInterface jest używany w aby ukryć szczegóły implementacji gdzie strumień danych jest odczytywany z lub zapisywane do.
PSR-7 Psr\Message\StreamInterface udostępnia kilka metod, które umożliwiają efektywne odczytywanie strumieni, zapisywanie do nich oraz ich przemierzanie.
Strumienie ujawniają swoje możliwości za pomocą trzech metod: isReadable()
isWritable(), oraz isSeekable(). Metody te mogą być używane przez
aby określić, czy strumień jest w stanie spełnić ich wymagania.
Każda instancja strumienia ma różne możliwości: mogą być tylko do odczytu, tylko do odczytu, tylko do zapisu, do odczytu-zapisu, umożliwiać dowolny dostęp losowy (wyszukiwanie do przodu lub wstecz do dowolnego miejsca), lub pozwalać tylko na dostęp sekwencyjny (na przykład w przypadku w przypadku gniazda lub rury).
Guzzle wykorzystuje pakiet guzzlehttp/psr7 do zapewnienia obsługi strumieni. Więcej
więcej informacji na temat używania strumieni, tworzenia strumieni, konwersji strumieni do PHP
i dekoratorach strumieni można znaleźć na stronie
dokumentacji Guzzle PSR-7.
Najlepszym sposobem na stworzenie strumienia jest użycie metody GuzzleHttp::streamFor
metoda. Metoda ta przyjmuje ciągi znaków, zasoby zwrócone z fopen(),
obiekt implementujący __toString(), iteratory, obiekty wywołujące i instancje Psr\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
Możesz tworzyć strumienie z iteratorów. Iterator może dostarczyć dowolną liczbę bajtów na iterację. Wszelkie nadmiarowe bajty zwrócone przez iterator, które nie zostały nie zostały zażądane przez konsumenta strumienia, zostaną zbuforowane do następnego odczytu.
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); // ...
Strumienie eksponują metadane strumienia poprzez metodę getMetadata(). Ta
dostarcza danych, które można by pobrać wywołując metodę PHP
stream_get_meta_data(),
i może opcjonalnie udostępniać inne niestandardowe dane.
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
Dodawanie niestandardowej funkcjonalności do strumieni jest bardzo proste dzięki dekoratorom strumieni. Guzzle dostarcza kilka wbudowanych dekoratorów, które zapewniają dodatkową funkcjonalność funkcjonalność.