Guzzle6 Adapter Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require php-http/guzzle6-adapter
   

   Require the Http\Adapter\Guzzle6\Client in your Laravel project:

   composer require php-http/guzzle6-adapter guzzlehttp/guzzle
   

2. Basic Usage Register the Guzzle6 adapter in Laravel's HTTP client configuration (config/http.php):

   'plugins' => [
       \Http\Adapter\Guzzle6\Client::class,
   ],
   

3. First Use Case Fetch data from an external API:

   use Http\Client\Common\Plugin\AddHostPlugin;
   use Http\Client\Common\Plugin\UrlEncodePlugin;
   use Http\Client\Common\PluginClient;
   use Http\Message\Authentication\Bearer\BearerAuth;
   
   $client = new PluginClient(
       new \Http\Adapter\Guzzle6\Client(),
       [
           new AddHostPlugin(),
           new UrlEncodePlugin(),
       ]
   );
   
   $response = $client->get('https://api.example.com/data', [
       'auth' => new BearerAuth('your-token-here'),
   ]);
   
   $data = json_decode($response->getBody(), true);
   

Implementation Patterns

Common Workflows

1. Laravel HTTP Client Integration Use Laravel's built-in HTTP client with Guzzle6 adapter:

   $response = Http::withOptions(['debug' => true])
       ->withHeaders(['Authorization' => 'Bearer token'])
       ->get('https://api.example.com/endpoint');
   

2. Middleware/Plugins Leverage Guzzle middleware (e.g., retry, logging):

   use GuzzleHttp\Middleware;
   
   $stack = \Http\Promise\Promise::wrap(function () use ($client) {
       return $client->sendAsync(function ($request) {
           return $request->getBody()->write('Hello, World!');
       });
   });
   
   $stack->then(function ($response) {
       echo $response->getBody();
   });
   

3. Streaming Responses Handle large responses efficiently:

   $response = $client->get('https://api.example.com/large-file');
   $stream = $response->getBody();
   while (!$stream->eof()) {
       echo $stream->read(1024);
   }
   

Integration Tips

• Laravel HTTP Client: Prefer Laravel's Http facade for simplicity.
• Dependency Injection: Bind the adapter in Laravel's service container:

  $this->app->bind(\Http\Client\Common\PluginClient::class, function ($app) {
      return new PluginClient(
          new \Http\Adapter\Guzzle6\Client(),
          [$app->make(\Http\Client\Common\Plugin\BaseUrlPlugin::class)]
      );
  });
  

• Configuration: Use Laravel's config to centralize Guzzle settings:

  // config/guzzle.php
  'default' => [
      'timeout'  => 10.0,
      'verify'   => false, // Disable SSL verification (not recommended for production)
  ],
  

Gotchas and Tips

Pitfalls

1. Deprecated Guzzle6

   • The package is archived and not maintained for Guzzle 7+. Use php-http/guzzle7-adapter for new projects.
   • Guzzle6 reached end-of-life in 2021; avoid in production unless maintaining legacy systems.

2. SSL Verification Disabling SSL verification (verify => false) is unsafe. Use:

   'verify' => env('APP_ENV') !== 'production' ? false : __DIR__.'/path/to/cert.pem',
   

3. Stream Handling Guzzle6 streams behave differently than Guzzle7. Ensure proper resource cleanup:

   $stream = $response->getBody();
   $stream->rewind();
   $data = $stream->getContents();
   $stream->close();
   

Debugging

• Enable Debugging:

  $client = new \Http\Adapter\Guzzle6\Client([
      'debug' => fopen('guzzle.log', 'w'),
  ]);
  

• Common Errors:
  • CurlException: Check allow_redirects, timeout, and SSL settings.
  • ConnectionException: Verify the host/port and firewall rules.

Extension Points

1. Custom Middleware Add Guzzle middleware via Http\Client\Common\PluginClient:

   use GuzzleHttp\Middleware;
   
   $client = new PluginClient(
       new \Http\Adapter\Guzzle6\Client(),
       [
           Middleware::tap(function ($request) {
               $request->getHeaders()->add('X-Custom-Header', 'value');
           }),
       ]
   );
   

2. Retry Logic Use php-http/retry-plugin for automatic retries:

   use Http\Client\Common\Plugin\RetryPlugin;
   
   $client = new PluginClient(
       new \Http\Adapter\Guzzle6\Client(),
       [new RetryPlugin()]
   );
   

3. Mocking for Tests Use GuzzleHttp\Handler\MockHandler:

   $mock = new MockHandler([new Response(200, [], 'Mocked response')]);
   $handler = new \GuzzleHttp\HandlerStack($mock);
   $client = new \Http\Adapter\Guzzle6\Client(['handler' => $handler]);