Handlers and Middleware

Klienci Guzzle używają systemu obsługi i oprogramowania pośredniczącego do wysyłania żądań HTTP.

Handlers

Funkcja handler przyjmuje Psr\Message\RequestInterface i tablicę opcji żądania i zwraca GuzzleHttp\Promise\PromiseInterface, który jest spełniony przez Psr\Http\Message\ResponseInterface lub odrzucony z wyjątkiem. exception.

Możesz dostarczyć klientowi niestandardowy handler używając opcji handler w konstruktorze klienta. konstruktora klienta. Ważne jest, aby zrozumieć, że kilka opcji żądania używanych przez Guzzle'a wymaga, aby określone oprogramowanie pośredniczące przez klienta. Możesz upewnić się, że handler, który przekazujesz klientowi, korzysta z domyślnych mechanizmów pośredniczących, zawijając go w GuzzleHttpHandlerStack::create(callable $handler = null) metodą statyczną.

use GuzzleHttp\Client;
use GuzzleHttp\HandlerStack;
use GuzzleHttp\Handler\CurlHandler;

$handler = new CurlHandler();
$stack = HandlerStack::create($handler); // Wrap w/ middleware
$client = new Client(['handler' => $stack]);

Metoda create dodaje domyślne handler'y do HandlerStack. Gdy HandlerStack zostanie rozwiązany, handler'y zostaną wykonane w następującej kolejności:

  1. Wysłanie żądania:
  1. http_errors - Brak op podczas wysyłania żądania. Kod statusu odpowiedzi jest sprawdzany w przetwarzaniu odpowiedzi podczas zwracania obietnicy odpowiedzi w górę stosu.
  2. allow_redirects - Brak op podczas wysyłania żądania. Podążanie za przekierowaniami występuje, gdy obietnica odpowiedzi jest zwracana w górę stosu.
  3. cookies - Dodaje ciasteczka do żądań.
  4. prepare_body - Ciało żądania HTTP zostanie przygotowane (np, dodanie domyślnych nagłówków takich jak Content-Length, Content-Type, itd.)
  5. <send request with handler>
  1. Odpowiedź procesowa:
  1. prepare_body - brak op przy przetwarzaniu odpowiedzi.
  2. cookies - wyciąga ciasteczka odpowiedzi do słoika z ciasteczkami.
  3. allow_redirects - Podporządkowuje się przekierowaniom.
  4. http_errors - rzuca wyjątki, gdy kod statusu odpowiedzi >= 400.

Gdy nie podamy żadnego $handler argumentu, GuzzleHttp\HandlerStack::create() wybierze najbardziej odpowiedni handler, bazując na rozszerzeniach dostępnych w systemie. twoim systemie.

Ważne

Handlowiec dostarczony do klienta określa, w jaki sposób opcje żądania są stosowane i wykorzystywane dla każdego żądania wysłanego przez klienta. Na przykład, jeśli nie nie masz oprogramowania pośredniczącego cookie powiązanego z klientem, to ustawienie parametru cookies opcji żądania nie będzie miało żadnego wpływu na żądanie.

Middleware

Middleware rozszerza funkcjonalność handlerów poprzez wywoływanie ich w procesie w procesie generowania odpowiedzi. Middleware jest zaimplementowany jako funkcja wyższego rzędu która przyjmuje następującą postać.

use Psr\Http\Message\RequestInterface;

function my_middleware()
{
    return function (callable $handler) {
        return function (RequestInterface $request, array $options) use ($handler) {
            return $handler($request, $options);
        };
    };
}

Funkcje Middleware zwracają funkcję, która akceptuje następny handler do wywołania. Ta zwrócona funkcja zwraca następnie inną funkcję, która działa jako złożony handler - akceptuje żądanie i opcje oraz zwraca obietnicę, która jest spełniona wraz z odpowiedzią. Twoje skomponowane oprogramowanie pośredniczące może modyfikować żądanie, dodawać niestandardowe opcje żądania i modyfikować obietnicę zwracaną przez następny handler.

Oto przykład dodawania nagłówka do każdego żądania.

use Psr\Http\Message\RequestInterface;

function add_header($header, $value)
{
    return function (callable $handler) use ($header, $value) {
        return function (
            RequestInterface $request,
            array $options
        ) use ($handler, $header, $value) {
            $request = $request->withHeader($header, $value);
            return $handler($request, $options);
        };
    };
}

Po utworzeniu oprogramowania pośredniczącego, możesz dodać je do klienta poprzez zawijanie handlerów używanych przez klienta lub poprzez dekorowanie stosu handlerów.

use GuzzleHttp\HandlerStack;
use GuzzleHttp\Handler\CurlHandler;
use GuzzleHttp\Client;

$stack = new HandlerStack();
$stack->setHandler(new CurlHandler());
$stack->push(add_header('X-Foo', 'bar'));
$client = new Client(['handler' => $stack]);

Teraz, gdy wyślesz żądanie, klient użyje handler'a skomponowanego z dodanym przez Ciebie oprogramowaniem pośredniczącym, dodając nagłówek do każdego żądania.

Oto przykład tworzenia middleware, który modyfikuje odpowiedź downstreamowego handler'a. Ten przykład dodaje nagłówek do odpowiedzi.

use Psr\Http\Message\RequestInterface;
use Psr\Http\Message\ResponseInterface;
use GuzzleHttp\HandlerStack;
use GuzzleHttp\Handler\CurlHandler;
use GuzzleHttp\Client;

function add_response_header($header, $value)
{
    return function (callable $handler) use ($header, $value) {
        return function (
            RequestInterface $request,
            array $options
        ) use ($handler, $header, $value) {
            $promise = $handler($request, $options);
            return $promise->then(
                function (ResponseInterface $response) use ($header, $value) {
                    return $response->withHeader($header, $value);
                }
            );
        };
    };
}

$stack = new HandlerStack();
$stack->setHandler(new CurlHandler());
$stack->push(add_response_header('X-Foo', 'bar'));
$client = new Client(['handler' => $stack]);

Tworzenie oprogramowania pośredniczącego, które modyfikuje żądanie, jest znacznie prostsze przy użyciu GuzzleHttpMiddleware::mapRequest() middleware. To oprogramowanie pośrednie przyjmuje funkcję, która pobiera argument żądanie i zwraca żądanie do wysłania.

use Psr\Http\Message\RequestInterface;
use GuzzleHttp\HandlerStack;
use GuzzleHttp\Handler\CurlHandler;
use GuzzleHttp\Client;
use GuzzleHttp\Middleware;

$stack = new HandlerStack();
$stack->setHandler(new CurlHandler());

$stack->push(Middleware::mapRequest(function (RequestInterface $request) {
    return $request->withHeader('X-Foo', 'bar');
}));

$client = new Client(['handler' => $stack]);

Modyfikowanie odpowiedzi jest również znacznie prostsze przy użyciu GuzzleHttpMiddleware::mapResponse() middleware.

use Psr\Http\Message\ResponseInterface;
use GuzzleHttp\HandlerStack;
use GuzzleHttp\Handler\CurlHandler;
use GuzzleHttp\Client;
use GuzzleHttp\Middleware;

$stack = new HandlerStack();
$stack->setHandler(new CurlHandler());

$stack->push(Middleware::mapResponse(function (ResponseInterface $response) {
    return $response->withHeader('X-Foo', 'bar');
}));

$client = new Client(['handler' => $stack]);

HandlerStack¦

Stos handlerów reprezentuje stos oprogramowania pośredniczącego, które ma być zastosowane do bazowej funkcji handlerów funkcji. Możesz przesunąć oprogramowanie pośredniczące na stos, aby dodać je do wierzchołka stosu, oraz odłożyć na stos, aby dodać je na sam dół stosu. Gdy stos jest rozwiązywany, handler jest przesuwany na stos. Każda wartość jest każda wartość jest odsuwana od stosu, zawijając poprzednią wartość odsuwaną od stosu. stosu.

use GuzzleHttp\Client;
use GuzzleHttp\HandlerStack;
use GuzzleHttp\Middleware;
use GuzzleHttp\Utils;
use Psr\Http\Message\RequestInterface;

$stack = new HandlerStack();
$stack->setHandler(Utils::chooseHandler());

$stack->push(Middleware::mapRequest(function (RequestInterface $r) {
    echo 'A';
    return $r;
}));

$stack->push(Middleware::mapRequest(function (RequestInterface $r) {
    echo 'B';
    return $r;
}));

$stack->push(Middleware::mapRequest(function (RequestInterface $r) {
    echo 'C';
    return $r;
}));

$client->request('GET', 'http://httpbin.org/');
// echoes 'ABC';

$stack->unshift(Middleware::mapRequest(function (RequestInterface $r) {
    echo '0';
    return $r;
}));

$client = new Client(['handler' => $stack]);
$client->request('GET', 'http://httpbin.org/');
// echoes '0ABC';

Możesz nadać oprogramowaniu pośredniczącemu nazwę, co pozwoli Ci dodać oprogramowanie pośredniczące przed innym nazwanym oprogramowaniem pośredniczącym, po innym nazwanym oprogramowaniu pośredniczącym lub usunąć oprogramowanie pośredniczące według nazwy.

use Psr\Http\Message\RequestInterface;
use GuzzleHttp\Middleware;

// Add a middleware with a name
$stack->push(Middleware::mapRequest(function (RequestInterface $r) {
    return $r->withHeader('X-Foo', 'Bar');
}, 'add_foo'));

// Add a middleware before a named middleware (unshift before).
$stack->before('add_foo', Middleware::mapRequest(function (RequestInterface $r) {
    return $r->withHeader('X-Baz', 'Qux');
}, 'add_baz'));

// Add a middleware after a named middleware (pushed after).
$stack->after('add_baz', Middleware::mapRequest(function (RequestInterface $r) {
    return $r->withHeader('X-Lorem', 'Ipsum');
}));

// Remove a middleware by name
$stack->remove('add_foo');

Tworzenie handlerówś

Jak wspomniano wcześniej, handler jest funkcją, która akceptuje PsrHttp\Message\RequestInterface oraz tablicę opcji żądania i zwraca GuzzleHttp\Promise\PromiseInterface, który jest spełniany za pomocą PsrHttp\Message\ResponseInterface lub odrzucone z wyjątkiem.

Handlowiec jest odpowiedzialny za stosowanie następujących Opcji żądania. Te opcje żądania są podzbiorem opcji żądania zwanych "opcje przekazu".