Http Client Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require amphp/http-client
   

   For HTTP/2 optimizations, also install:

   composer require ext-nghttp2
   

2. First Request:

   use Amp\Http\Client\HttpClientBuilder;
   
   $client = HttpClientBuilder::buildDefault();
   $response = await $client->request('https://httpbin.org/get');
   echo $response->getBody()->buffer();
   

3. Key Classes:

   • HttpClientBuilder: Configures and builds clients.
   • Request: Defines HTTP requests (mutable).
   • Response: Handles responses (mutable).

First Use Case: Concurrent Requests

use Amp\Http\Client\HttpClientBuilder;
use Amp\Loop;

$client = HttpClientBuilder::buildDefault();
$urls = ['https://httpbin.org/get', 'https://httpbin.org/ip'];

$tasks = [];
foreach ($urls as $url) {
    $tasks[] = $client->request($url);
}

$responses = await Amp\Promise\all($tasks);
foreach ($responses as $response) {
    echo $response->getBody()->buffer() . "\n";
}

Implementation Patterns

1. Request Construction

Pattern: Use Request for structured requests.

$request = new Request('https://api.example.com/data', 'POST');
$request->setHeader('Authorization', 'Bearer token123');
$request->setHeader('Content-Type', 'application/json');
$request->setBody(json_encode(['key' => 'value']));

Workflow:

• Reuse Request objects for retries (deep clone with clone).
• Use HttpContent for streaming bodies (e.g., file uploads).

2. Response Handling

Pattern: Stream responses for large payloads.

$response = await $client->request('https://large-file.example.com/data');
$body = $response->getBody();

// Stream chunks (memory-efficient)
while (!$body->isEmpty()) {
    $chunk = await $body->read();
    // Process chunk (e.g., save to disk)
}

Integration Tip:

• Use getHeaders() for metadata (e.g., Content-Length).
• Check getStatus() for HTTP status codes (e.g., 200, 404).

3. Concurrency and Pooling

Pattern: Leverage default concurrency.

$client = HttpClientBuilder::buildDefault();
$promises = [];
for ($i = 0; $i < 100; $i++) {
    $promises[] = $client->request("https://httpbin.org/get?i=$i");
}
$responses = await Amp\Promise\all($promises);

Optimization:

• Use HttpClientBuilder::build() with custom connection pools for long-lived clients.
• Enable HTTP/2 for multiplexing:

  $client = (new HttpClientBuilder)
      ->withHttp2Support()
      ->build();
  

4. Interceptors for Cross-Cutting Concerns

Pattern: Compose interceptors for reusable logic.

use Amp\Http\Client\Interceptor\SetRequestHeader;

$client = (new HttpClientBuilder)
    ->intercept(new SetRequestHeader('X-API-Key', 'secret123'))
    ->intercept(new SetRequestHeader('User-Agent', 'MyApp/1.0'))
    ->build();

Common Use Cases:

• Authentication: Add Authorization headers.
• Logging: Use LogHttpArchive for HAR files.
• Retries: Add RetryRequests interceptor.
• Caching: Integrate PrivateCache or amphp/http-client-cache.

Example: Retry Failed Requests

use Amp\Http\Client\Interceptor\RetryRequests;

$client = (new HttpClientBuilder)
    ->intercept(new RetryRequests(3)) // Retry 3 times
    ->build();

5. Error Handling

Pattern: Use try/catch with RequestException.

try {
    $response = await $client->request('https://invalid.url');
} catch (Amp\Http\Client\RequestException $e) {
    echo "Request failed: " . $e->getMessage();
}

Common Exceptions:

• RequestException: Network/HTTP errors.
• ConnectionException: Connection issues (e.g., DNS failure).

6. Cookies and Sessions

Pattern: Use amphp/http-client-cookies.

use Amp\Http\Client\Cookie\CookieJar;
use Amp\Http\Client\Interceptor\CookieHandler;

$cookieJar = new CookieJar();
$client = (new HttpClientBuilder)
    ->intercept(new CookieHandler($cookieJar))
    ->build();

// First request (sets cookies)
$response = await $client->request('https://example.com/login');

// Subsequent requests (uses cookies)
$response = await $client->request('https://example.com/dashboard');

7. Proxies

Pattern: Route through proxies using amphp/http-tunnel.

use Amp\Http\Client\Proxy\ProxyResolver;
use Amp\Http\Client\Proxy\Socks5Proxy;

$proxy = new Socks5Proxy('proxy.example.com', 1080);
$resolver = new ProxyResolver($proxy);

$client = (new HttpClientBuilder)
    ->withProxyResolver($resolver)
    ->build();

Gotchas and Tips

1. Mutable Objects

• Gotcha: Request and Response are mutable. Avoid modifying them after passing to request().
• Tip: Clone requests for retries or variations:

  $original = new Request('https://api.example.com');
  $cloned = clone $original;
  $cloned->setMethod('POST');
  

2. Redirects

• Gotcha: Default FollowRedirects interceptor:
  • Limits redirects to 10 by default.
  • Only follows GET redirects (preserves method for 307/308).
  • Discards response bodies of intermediate redirects.
• Tip: Disable auto-redirects and handle manually:

  $client = (new HttpClientBuilder)
      ->followRedirects(0) // Disable auto-redirects
      ->build();
  

3. HTTP/2 Quirks

• Gotcha: HTTP/2 requires nghttp2 extension for optimal performance.
• Tip: Enable HTTP/2 explicitly:

  $client = (new HttpClientBuilder)
      ->withHttp2Support()
      ->build();
  

• Debugging: Slow consumers may trigger inactivity timeouts. Stream responses promptly.

4. Connection Pooling

• Gotcha: Default connection limits may throttle high-concurrency apps.
• Tip: Adjust pool size:

  $client = (new HttpClientBuilder)
      ->withConnectionLimit(50) // Default is 10
      ->build();
  

5. Headers and Encoding

• Gotcha: Headers are case-insensitive but stored as-is. Use getHeader() carefully.
• Tip: Normalize headers when setting:

  $request->setHeader('Content-Type', 'application/json');
  // Later: $request->getHeader('content-type') returns 'application/json'.
  

6. TLS and Security

• Gotcha: Default TLS settings may not match all environments.
• Tip: Customize TLS context:

  $client = (new HttpClientBuilder)
      ->withTlsContext(\Amp\Socket\TlsContext::create([
          'verify_peer' => false, // Disable for testing only!
          'cafile' => '/path/to/cert.pem',
      ]))
      ->build();
  

7. Debugging

• Tip: Use LogHttpArchive for HAR files:

  $client = (new HttpClientBuilder)
      ->listen(new LogHttpArchive('/tmp/debug.har'))
      ->build();
  

• Common Issues:
  • Timeouts: Increase timeout with SetRequestTimeout interceptor.
  • Stalled Connections: Ensure responses are streamed/buffered promptly.
  • Memory Leaks: Close responses explicitly with $response->close().

8. Extending the Library

• Extension Points:
  • Interceptors: Create custom ApplicationInterceptor or NetworkInterceptor.
  • Transport: Replace the default Transport implementation for custom protocols.
• Example: Custom Interceptor

  use Amp\Http\Client\Interceptor\ApplicationInterceptor;
  use Amp\Http\Client\Request;
  use Amp\Http\Client\Response;
  
  class CustomHeaderInterceptor implements ApplicationInterceptor {
      public function intercept(Request $request, callable $next): \Amp\Promise {
          $request->addHeader('X-Custom', 'value');
          return $next($request);
      }
  }
  

9. Performance Tips

• Reuse Clients: Instantiate HttpClient once and reuse it (