innmind / http-transport
Library to fulfill http resquest
Requires
- php: ~8.2
- ext-curl: *
- innmind/filesystem: ~7.1
- innmind/http: ~7.0
- innmind/immutable: ~4.15|~5.0
- innmind/io: ~2.2
- innmind/stream: ~4.0
- innmind/time-continuum: ~3.0
- innmind/time-warp: ~3.0
- innmind/url: ~4.0
- psr/log: ~3.0
- ramsey/uuid: ^4.7
Requires (Dev)
- innmind/black-box: ~5.5
- innmind/coding-standard: ~2.0
- phpunit/phpunit: ~10.2
- vimeo/psalm: ~5.11
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\Curl; use Innmind\TimeContinuum\Earth\Clock; use Innmind\Http\Request; $fulfill = Curl::of(new Clock); $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\Curl; use Innmind\Http\{ Request, Response, Method, ProtocolVersion, }; use Innmind\Url\Url; use Innmind\Immutable\Sequence; $fulfill = Curl::of(new Clock)->maxConcurrency(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\Logger use Psr\Log\LoggerInterface; $fulfill = Logger::psr(/* 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\ExponentialBackoff; use Innmind\TimeWarp\Halt\Usleep; $fulfill = ExponentialBackoff::of( /* an instance of Transport */, new Usleep, ); $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\CircuitBreaker; use Innmind\TimeContinuum\Earth\{ Clock, Period\Minute, }; $fulfill = CircuitBreaker::of( /* an instance of CircuitBreaker */, new Clock, new 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\FollowRedirections; $fulfill = FollowRedirections::of(/* 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.