README

This library allows you to send http request.

Important

to use this library correctly you must use vimeo/psalm.

Installation

composer require innmind/http-transport

Usage

Send a request:

use Innmind\HttpTransport\Transport;
use Innmind\Time\Clock;
use Innmind\Http\Request;

$fulfill = Transport::curl(Clock::live());

$either = $fulfill(
    Request::of(/* initialize your request */),
);

2xx responses will be on the right side of $either, all errors and other kinds of responses will be on the left side.

Important

you must call match to the returned Either otherwise the request will not be sent, but you can still call other methods on the Either before calling match.

Concurrency

By default there is no limit of concurrency for the Curl transport. But if you call many requests before unwrapping the results you may want to configure the max concurrency like below.

use Innmind\HttpTransport\Transport;
use Innmind\Http\{
    Request,
    Response,
    Method,
    ProtocolVersion,
};
use Innmind\Url\Url;
use Innmind\Immutable\Sequence;

$fulfill = Transport::curl(Clock::live())->map(
    static fn($config) => $config->limitConcurrencyTo(5),
);
$responses = Sequence::of(
    'https://github.com/user/repo-a',
    'https://github.com/user/repo-b',
    'https://github.com/user/repo-c',
    // etc...
)
    ->map(static fn($url) => Request::of(
        Url::of($url),
        Method::get,
        ProtocolVersion::v20,
    ))
    ->map($fulfill)
    ->flatMap(static fn($either) => $either->match(
        static fn($success) => Sequence::of($success->response()),
        static fn() => Sequence::of(), // discard errors
    ))
    ->toList();
$responses; // list<Response>

Let's say you have 100 urls to fetch, there will never be more than 5 requests being done in parallel.

Log the request

You can easily log all your requests like so:

use Innmind\HttpTransport\Transport;
use Psr\Log\LoggerInterface;

$fulfill = Transport::logger(/* an instance of Transport */, /* an instance of LoggerInterface */)

$fulfill(/* your request */);

Here a message is logged before the request is sent and another one once it's sent.

Exponential Backoff

Sometimes when calling an external API it may not be available due to heavy load, in such case you could retry the http call after a certain amount of time leaving time for the API to recover. You can apply this pattern like so:

use Innmind\HttpTransport\Transport;
use Innmind\Time\Halt;

$fulfill = Transport::exponentialBackoff(
    /* an instance of Transport */,
    Halt::new(),
);

$fulfill(/* your request */);

By default it will retry 5 times the request if the server is unavailable, following the given periods (in milliseconds) between each call: 100, 271, 738, 2008 and 5459.

Circuit breaker

When a call to a certain domain fails you may want to all further calls to that domain to fail immediately as you know it means the host is down. Such pattern is called a circuit breaker.

use Innmind\HttpTransport\Transport;
use Innmind\Time\{
    Clock,
    Period,
};

$fulfill = Transport::circuitBreaker(
    /* an instance of Transport */,
    Clock::live(),
    Period::minute(10),
);

$fulfill(/* your request */);

This code will open the circuit for a given domain for 10 minutes in case a call results in a server error, after this delay the transport will let new request through as if nothing happened.

Follow redirections

By default the transports do not follow redirections to give you full control on what to do. But you can wrap your transport with FollowRedirections like this:

use Innmind\HttpTransport\Transport;

$fulfill = Transport::followRedirections(/* an instance of Transport */);

$fulfill(/* your request */);

To avoid infinite loops it will follow up to 5 consecutive redirections.

Important

as defined in the rfc, requests with methods other than GET and HEAD that results in redirection with the codes 301, 302, 307 and 308 will NOT be redirected. It will be up to you to implement the redirection as you need to make sure such redirection is safe.