Http Client Laravel Package

Getting Started

Begin by installing the psr/http-client package: composer require psr/http-client. Remember, this is only the interface specification—no actual HTTP client logic. You must also install a PSR-18-compliant implementation. For Laravel projects, the simplest path is to use Symfony’s HTTP client: composer require symfony/http-client, which Laravel automatically registers as the default for Http::client(). To verify setup, resolve the interface from the container: app(\Psr\Http\Client\ClientInterface::class)—if it resolves without error, you’re ready. The first concrete use case is replacing ad-hoc cURL or Guzzle calls with standardized client injection.

Implementation Patterns

In Laravel, prefer using the high-level Http facade—it’s PSR-18-backed under the hood and ideal for most API interactions. For testable, reusable services, inject ClientInterface directly:

use Psr\Http\Client\ClientInterface;
use Psr\Http\Message\RequestInterface;
use Psr\Http\Message\ResponseInterface;

class PaymentGateway
{
    public function __construct(private ClientInterface $client) {}

    public function charge(string $token, float $amount): ResponseInterface
    {
        $request = (new Request('POST', 'https://api.payments.com/charge'))
            ->withHeader('Authorization', "Bearer {$token}")
            ->withHeader('Content-Type', 'application/json')
            ->withBody(stream_for(json_encode(['amount' => $amount])));
        return $this->client->sendRequest($request);
    }
}

When building packages, depend on ClientInterface and RequestFactoryInterface (PSR-17) to maximize compatibility. For testing, mock ClientInterface without coupling to a specific HTTP library. Leverage Laravel’s Http::retry() and Http::asJson() for common workflows, but fall back to raw PSR-18 calls when handling non-JSON responses or custom streaming.

Gotchas and Tips

• No implementation: Confusing this with a real HTTP client is the #1 error—run composer show -i | grep 'psr/http-client-implementation' to confirm you have an actual client installed.
• Exception hierarchy: Handle NetworkExceptionInterface and TransportExceptionInterface separately—Laravel’s Http::response() throws ConnectionException ( Symfony-specific), not PSR-18 exceptions, unless you use Http::sendRequest().
• PSR-7/17 alignment: Ensure your client uses compatible psr/http-message versions. Laravel 11+ works out-of-the-box with symfony/http-client, but older versions may need php-http/guzzle7-adapter to avoid type errors.
• Laravel’s Http facade deviation: Http::get() returns a Laravel Response object, not ResponseInterface. Use Http::sendRequest($request) when you need raw PSR-18 responses.
• Extensibility via binding: Override the default client in AppServiceProvider to add custom timeouts, middleware, or logging: app()->singleton(ClientInterface::class, fn() => new LoggingClientDecorator(app()->make(ClientInterface::class))).